Skip to content

v3.0.0-RC3

Pre-release
Pre-release
Compare
Choose a tag to compare
@djspiewak djspiewak released this 22 Mar 02:29
· 4922 commits to series/3.x since this release
v3.0.0-RC3
This tag was signed with the committer’s verified signature.
djspiewak Daniel Spiewak
GPG key ID: 8DB0AD19E03F6F2F
Learn about vigilant mode.
8d0894f
This commit was created on GitHub.com and signed with GitHub’s verified signature. The key has expired.
GPG key ID: 4AEE18F83AFDEB23
Expired
Learn about vigilant mode.

Cats Effect 3.0.0-RC3 is the third release candidate for 3.0.0. This will be the final release candidate prior to 3.0.0 final barring any serious show-stopper issues.

This release includes a few minor binary-incompatible changes from RC2. These are not expected to represent a significant hardship, though they do mean that the binaries are not directly substitutable.

What follows are the changes from RC2 to RC3. For a more complete summary of the changes generally included in Cats Effect 3.0.0, please see the M1, M2, M3, M4, M5, RC1, and RC2 release notes.

Notable Changes

uncancelable Mask Regions Are Now Open At The End

This is a very subtle issue, but consider the following code:

IO uncancelable { poll =>
  poll {
    IO uncancelable { _ =>
      ...
    }
    // what happens here?
  }
}

Assume that the containing fiber is canceled somewhere within the inner uncancelable block. Consider the commented line: is this cancelation visible at that point? Previously, the answer to this question was "yes". Unfortunately, this semantic would also make it impossible to write safe and composable code under some circumstances!

For example, any method which wraps its body in uncancelable and returns would be suspect. This is actually a significant percentage of Cats Effect itself, including major combinators such as bracket.

Unfortunately, fixing this requires removing the cancelation check at the closing boundary of uncancelable, which in turn means violating the functor laws. This, too, is quite subtle, but consider the following programs:

IO.uncancelable(_ => ...)                    // program 1
IO.uncancelable(_ => ...).flatMap(IO.pure)   // program 2

The functor laws state that these two programs must have equivalent semantics. Unfortunately, if we remove the cancelation check at the end of uncancelable, they no longer do! More specifically, any cancelation which happens within the uncancelable block will be invisible at the end of the first program, but may be visible at the end of the second program. Thus, the two programs are not directly substitutable.

Fortunately, this violation is only an issue within very small program scopes. Cancelation in general is a hint and you should not be relying on it becoming visible at any particular point, only relying on it definitely not being visible at other points (e.g. inside of uncancelable). Thus, much like catching exceptions with IO#map, we have made the pragmatic choice to facilitate the construction of safe and reliable programs rather than prioritizing strict adherence to the mathematics.

Scalafix Migration Now Available!

Thanks to the tireless efforts of @fthomas (author of Scala Steward, may his name be praised), we now have a full-featured scalafix migration which should be able to handle most of the heavy lifting moving codebases from Cats Effect 2 to Cats Effect 3. Note that Scala Steward will be aware of this scalafix and will apply it automatically in any upgrade PRs, meaning that, for many projects, the upgrade to Cats Effect 3 may be entirely automatic!

You can find more information on how to apply this scalafix manually in the subproject readme.

Ongoing Performance Work

Despite Cats Effect 3's monumental performance results, we have only begun to scratch the surface on various things that are possible within the runtime. @vasilmkd has remained hard at work adjusting, tuning, tweaking, and coming up with new tricks to advance the state of the art. This release contains several under-the-hood improvements within the runloop and within the scheduler which should result in very noticeable improvements even above and beyond the state of performance in RC1 and RC2.

Additionally, @TimWSpence has been working on a replacement for ScheduledExecutorService which should result in significantly improved timer performance, particularly under pressure. This change will not make it in time for 3.0.0, but should be something which lands in the near-term thereafter.

Document ALL the Things!

As we enter the final leg of the multi-year marathon that has been Cats Effect 3, the focus is increasingly on documentation and general polish. To that end, a massive amount of the changes which took place between RC2 and RC3 were not code-related at all, but actually documentation. Here again @TimWSpence has been pouring countless hours into making sure the site is fully-comprehensive and clearly explains how to use both basic and highly advanced functionality within the library.

We will be launching a brand new version of the Cats Effect website concurrently with the Cats Effect 3 release, and we absolutely cannot wait to get your feedback! Significant emphasis has been put on ensuring that newcomers have a smooth onboarding path while experienced users can find in-depth documentation that pulls back the curtain on what's really happening under the hood.

User-Facing Pull Requests

Special thanks to each and every one of you!

Assets 2
Loading