v2.2.0-RC2

This is the second release candidate for 2.2.0, containing all of the changes described in v2.2.0-RC1. This release is fully binary compatible with everything in the 2.x line, and it is expected to be mostly source-compatible, though some source incompatibilities may exist. A minor binary incompatibility exists with 2.2.0-RC1, in the MVar2 API. It is very unlikely that anyone will be affected by this, as it only applies to those who defined a custom MVar2 implementation.

The main reason we are following a release candidate cycle for this particular release is to solicit feedback on tracing, which is the largest new feature in the 2.2.0 line. Please try this out on your codebase and let us know how it works, where it didn't work, and what features or tweaks you would like to see!

The primary changes from 2.2.0-RC1 are as follows:

• #938 - Added IO#map2Eval (@johnynek)
• #912 - Added some additional functions to MVar2 (@vasilmkd)
• #981 - Improved semantic specificity of tracing on combinators (e.g. *>) (@RaasAhsan)
• #930 - Documentation fixes (@RaasAhsan)

Special thanks to each and every one of you!

v2.2.0-RC1

This is the seventh major release in the Cats Effect 2.x lineage and the first release candidate for a minor release in this line. It is fully binary compatible with all 2.x.y releases. As previously noted, this is the first Cats Effect release to be exclusively published for ScalaJS 1.x; there are no 0.6.x cross-releases.

This is a relatively large release with a few major changes, which is why we're following a release candidate process. We expect 2.2.0 final to be released within a few weeks, depending on feedback. Despite the "release candidate" moniker, we do not anticipate any serious issues with this release; please try it out and report any problems as soon as possible!

Notable New Features

Asynchronous Tracing

IO tracing is probably the single most-requested Cats Effect feature, and it's finally here! Thanks to the tireless work of @RaasAhsan, IO now has a basic, high-performance asynchronous tracing mechanism. Note that this mechanism has very different internals from the async tracing already available in Akka and ZIO, and thus comes with a different set of tradeoffs. Also please remember that no async tracing on the JVM is perfectly accurate, and you may see misleading trace frames depending on your program. Despite all this, the added information is very welcome and sometimes quite helpful in tracking down issues!

This is what it looks like:

IOTrace: 13 frames captured, 0 omitted
  ├ flatMap at org.simpleapp.example.Example.run (Example.scala:67)
  ├ flatMap at org.simpleapp.example.Example.program (Example.scala:57)
  ├ flatMap at org.simpleapp.example.Example.program (Example.scala:58)
  ├ flatMap at org.simpleapp.example.Example.program (Example.scala:59)
  ├ flatMap at org.simpleapp.example.Example.program (Example.scala:60)
  ├ async at org.simpleapp.example.Example.program (Example.scala:60)
  ├ flatMap at org.simpleapp.example.Example.program (Example.scala:61)
  ├ flatMap at org.simpleapp.example.Example.program (Example.scala:60)
  ├ flatMap at org.simpleapp.example.Example.program2 (Example.scala:51)
  ├ map at org.simpleapp.example.Example.program2 (Example.scala:52)
  ├ map at org.simpleapp.example.Example.program (Example.scala:60)
  ├ map at org.simpleapp.example.Example.program (Example.scala:62)
  ╰ flatMap at org.simpleapp.example.Example.run (Example.scala:67)

It's important to understand that this feature is very new and we have a lot of things we want to improve about it! We need user feedback to guide this process. Please file issues and/or chat us up in Gitter if you have ideas, and especially if you see problems!

Tracing has three modes:

• Disabled
• Cached (the default)
• Full

These are all governed by the cats.effect.stackTracingMode system property and are global to the JVM. As a rough performance reference, at present, Cached tracing imposes a roughly 10% performance penalty in synthetic benchmarks on asynchronous IOs. This difference should be entirely impossible to observe outside of microbenchmarks (though we would love to hear otherwise if you see evidence to the contrary!). Full tracing imposes an exceptionally high performance cost, and is expected to be used only in development environments when specifically attempting to track down bugs. Disabled tracing imposes an extremely negligible penalty, and should be used in production if Cached tracing imposes a noticeable performance hit. It is recommended that you stick with the default tracing mode in most cases.

Cached tracing produces a single linear trace of the actions an IO program takes. This tracing mode uses heuristics to determine call-site information on functions like flatMap and async, and those heuristics can be misleading, particularly when used with monad transformers or types like Resource or Stream. If you have ideas for how to improve these heuristics, please let us know!

Full tracing captures a full JVM stack-trace for every call into IO, which results in an extremely comprehensive picture of your asynchronous control flow. This imposes a significant performance cost, but it makes it possible to see through complex compositions such as monad transformers or third-party code. This is an appropriate mode for development when the heuristics which generate a Cached trace are insufficient or misleading.

The IO.traced function produces a backtrace from the call-site, and this object provides a printFiberTrace effect which renders the trace to standard error. The number of actions to retain in the trace can be configured by the system property cats.effect.traceBufferSize, which defaults to 128.

We want your feedback! There are so many different things that we can do with this functionality, and we want your opinions on how it should work and how it can be improved. We have many more features coming, but please file issues, talk to us, try it out, tweet angrily, you know the drill.

Please note that this API is new in 2.2.0-RC1 and we may make changes to it before 2.2.0 final is released. Tracing support is also not yet enabled in ScalaJS.

Bracket Forwarders

This is a rather subtle issue, but on 2.1.x (and earlier), it is impossible to write something like the following:

def foo[F[_]: Sync] =
  Bracket[OptionT[F, *], Throwable].bracket(...)

The Bracket instance would fail to resolve, despite the fact that there's a Sync in scope, since Bracket cannot be inductively defined (see #860 for some discussion of the issues surrounding inductive Bracket instances). This change adds implicit forwarders to the Bracket companion object so that the inductive Sync instances, defined on the Sync companion object, could be resolved via the Bracket companion. Basically, this just moves the Sync instances into a scope wherein they can be addressed by implicit search starting from either Sync or Bracket.

There is a very small chance this will cause implicit ambiguities in some codebases. We are not aware of any specific cases where this can happen, but it's worth keeping in mind as you upgrade.

User-Facing Pull Requests

• #854 Fiber tracing: asynchronous stack tracing (@RaasAhsan)
• #918 Improved performance of Deferred and MVarConcurrent (@RaasAhsan)
• #847 Added Ref#modifyOr and Ref#updateOr (@RaasAhsan)
• #886 Improved performance of SyncIO (and certain IO cases) by 20-30% (@RaasAhsan)
• #827 Add Ref.lens constructor (@jwojnowski)
• #849 Workaround for scalac bugs when using Resource with F[+_] (@djspiewak)
• #739 Added MVar#tryRead (@kubum)
• #814 Add implicit proxies for transformers in Bracket (@ybasket)
• #844 Fix resolution of Clock implicits (e.g. Clock[Resource[IO, *]]) (@joroKr21)
• #846 Optimize redeem/redeemWith in typeclass instances (@alexandru)
• #906, #872, #884, #864, #851, #833, #839 - Documentation updates (@december32, @ronanM, @justinhj, @jgogstad, @azolotko, @arosien, @Slakah)

Special thanks to each and every one of you!

v2.1.4

This is the sixth major release in the Cats Effect 2.x lineage. It is fully binary compatible with all 2.x.y releases. As a note on ScalaJS support, we will be maintaining the cross-build between 0.6.x and 1.x until Cats Effect 2.2.0, which will exclusively be published for 1.x.

User-Facing Pull Requests

• #842 - Avoid exception when using IOApp in browsers (@rpiaggio)
• #841, #837 - Documentation updates (@anilkumarmyla, @nailyk)

Special thanks to each and every one of you!

v2.1.3

This is the fifth major release in the Cats Effect 2.x lineage. It is fully binary compatible with all 2.x.y releases. As a note on ScalaJS support, we will be maintaining the cross-build between 0.6.x and 1.0.x until Cats Effect 2.2.0, which will exclusively be published for 1.0.x.

User-Facing Pull Requests

• #835 - Remove Bracket constraint from Resource.mapK (@kubukoz)
• #812 - Remove sys.exit calls on JS runtime (@rossabaker)
• #804 - Add a bunch of useful functions directly on IO (@kubukoz)
• #816 - Documentation updates (@orvi)

Special thanks to each and every one of you!

v2.1.2

This is the fourth major release in the Cats Effect 2.x lineage. It is fully binary compatible with all 2.x.y releases. This is also the first release made available for ScalaJS 1.0.0 (final). As a note on ScalaJS support, we will be maintaining the cross-build between 0.6.x and 1.0.x until Cats Effect 2.2.0, which will exclusively be published for 1.0.x.

User-Facing Pull Requests

• #794 - Add getAndUpdate, updateAndGet to Ref (@kubukoz)
• #800, #790, #788, #783 - Documentation improvements/corrections/awesomeness (@theon, @kubukoz, @rossabaker, @kubum)
• #799 - Fix continual hanging when canceled really fast (@kubukoz)
• #796 - update to Scala.js 1.0.0 (@LarsH)
• #785 - Using blocker in Resorce.fromAutoClosable (@BalmungSan)

Special thanks to each and every one of you!

v2.1.1

This is the third major release in the Cats Effect 2.x lineage. It is fully binary compatible with all 2.0.x releases. Note that this version has not been released for ScalaJS 1.0.0 (final). There will be a 2.1.2 within the next few days which covers that version and drops support for 1.0-RC.

User-Facing Pull Requests

• #780 - Fix bug when double cancelation would hang second cancel (@Avasil)
• #776, #778, #769 - Documentation improvements/corrections/awesomeness (@rparree, @kell18, @calvellido)

Other contributors: @travisbrown, @raboof

Special thanks to each and every one of you!

v2.1.0

This is the second major release in the Cats Effect 2.x lineage. It is fully binary compatible with all 2.0.x releases, and should be source compatible in all but a few rare edge cases. It is also the first Cats Effect release which is not published for Scala 2.11. Cross-builds are available for 2.12 and 2.13 only.

Notable New Features

• New SyncEffect typeclass: analogous to Effect, but for non-asynchronous datatypes such as SyncIO

• Concurrent#background function, similar to start, but with resource handling wrapped around the Fiber to ensure it is properly scoped and cannot leak

• Resource is now covariant in both its F[_] and A parameter types. This makes it considerably more convenient to use in conjunction with subtype encodings. A common example:

  if (test)
    Resource.liftF(IO.pure(Some(42)))
  else
    Resource.liftF(IO.pure(None))

  As of this change, the above will now correctly infer Resource[IO, Option[Int]], as you would expect. Note that this change is source incompatible under some very specific circumstances (especially when using import cats.implicits._). For more discussion on this, see the pull request.

• There is now a Parallel instance for Resource (for any F where Parallel[F]). This makes it possible to safely run resource acquisition in parallel with the par-combinators (e.g. parZip).

• Scala.js 1.0 support. The Scala.js ecosystem is approaching its 1.0 milestone. Cats Effect is now cross-published for both 0.6.x and 1.0.x. The 0.6.x cross-build will be removed at some point after 1.0.x becomes relatively widespread.

Notable Bug Fixes

• Eliminated the (unintentional) async boundaries generated by IO#bracket, which in turn corrupted SyncIO's guarantees regarding purely synchronous execution
• Actions sequenced within Blocker will now properly exit when fatal errors are raised, mirroring the behavior of actions sequenced within the default ContextShift
• Under some circumstances, the use action within an IO#bracket could be evaluated even if the acquire is canceled. Obviously, acquisition cannot be interrupted, but when cancelation occurs during acquisition, the intended semantics are that use is simply ignored and the release is run immediately. That wasn't happening, and has now been corrected.

User-Facing Pull Requests

• #638 - Don't create async boundaries for SyncIO#bracket (@LukaJCB)
• #682 - Remove ambiguity in Clock derivation (@bplommer)
• #697 - Add a derivation for Timer[Resource[F, ?]] whenever Timer[F] is in scope (@barambani)
• #690 - Add Blocker.blockOnK (@nigredo-tori)
• #694 - Wrap default Blocker EC with exitOnFatal (@danxmoran)
• #713 - Drop support for Scala 2.11.x (@LukaJCB)
• #622 - Added SyncEffect typeclass (@LukaJCB)
• #640, #719 - start as Resource - background (@kubukoz)
• #722 - Indexed blocker thread names JVM (@Slakah)
• #729 - Add Align instances for IO, SyncIO and IO.Par (@LukaJCB)
• #706 - Bracket: Do not evaluate "use" if "acquire" is canceled (@Avasil)
• #731 - Make Resource covariant in F and A (@7mind)
• #742, #766 - Parallel resource (@SystemFw)
• #753 - Support ScalaJS 1.0.x (@cquiroz)
• #674, #685, #704, #665, #730, #761 - Documentation improvements/corrections/awesomeness (@kluen, @mlrv, @bwignall, @xuwei-k san, @qingwei91, @arosien)

Other contributors: @iRevive, @takayahilton, @jhnsmth, @travisbrown

Special thanks to each and every one of you!

v2.0.0

This is the first production release of cats-effect 2.x. It retains binary compatibility with 1.x, except Scala 2.11 and static forwarders for Java interop. See #566, #584 for a deeper discussion.

Changes

Laws:

• #611: Add fiber spawn latch to ConcurrentEffectLaws.runCancelableIsSynchronous

Chores:

• #618: Update to sbt-microsites-0.9.4
• #620: Update to sbt-1.3.0
• #625: Update to sbt-sonatype-3.6
• #627: Update to scalatestplus-sclaacheck-3.1.0.0-RC2
• #630: Update to cats-2.0.0

Special Thanks

This release was made possible by:

• @7mind
• @djspiewak
• @neko-kai
• @rossabaker

v2.0.0-RC2

This is the second release candidate of cats-effect-2.0.0. It retains binary compatibility with 1.x, except Scala 2.11 and static forwarders for Java interop. See #566, #584 for a deeper discussion.

Changes

Chores:

• #606: Update to sbt-mima-plugin-0.6.0
• #607: Update to sbt-tpolecat-0.1.8
• #609: Update to cats-2.0.0-RC2. Includes binary-compatible changes to features related to Parallel.

Special Thanks

This release was made possible by:

• @travisbrown

v2.0.0-RC1

This is the first release candidate of cats-effect-2.0.0. It retains binary compatibility with 1.x, except Scala 2.11 and static forwarders for Java interop. See #566, #584 for a deeper discussion.

Changes

Features:

• #601: Make IO's global scheduler thread pool configurable
• #577: Add inductive instances for ReaderWriterStateT
• #603: Drop laws' dependency on discipline-scalatest in favor of discipline-core

Documentation:

• #597: Fix MLock constructor to not hang on first call to acquire
• #600: Link to Java 8 javadoc instead of EOL Java 9.

Chores:

• #599: Update to cats-core-2.0.0-RC1
• #598: Update to discipline-scalatest-1.0.0-M1

Special Thanks

This release was made possible by:

• @rossabaker
• @sloshy
• @ybasket

Thanks to all those involved!