Skip to content

Releases: typelevel/cats-effect

v3.6.0-RC1

28 Dec 00:30
@djspiewak djspiewak
v3.6.0-RC1
This tag was signed with the committer’s verified signature.
djspiewak Daniel Spiewak
GPG key ID: 8DB0AD19E03F6F2F
Learn about vigilant mode.
adb0449
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Learn about vigilant mode.
Compare
Choose a tag to compare
v3.6.0-RC1 Pre-release
Pre-release

This is the fifty-third release in the Cats Effect 3.x lineage. It is fully binary compatible with every 3.x release and expected to be fully source-compatible with the eventual 3.6.x lineage.

This release candidate is expected to be very stable, and our main rationale for releasing it as such rather than as a full 3.6.0 is to allow the ecosystem (and adventurous end users!) to try it out and find unforeseen problems prior to full release. If fixing those problems require breaking compatibility prior to 3.6.0 (while maintaining bincompat with 3.x) we will do so, but otherwise you should expect this release to roughly represent the exact API surface area we will ultimately release.

Warning

Please note that Cats Effect 3.6.x is targeting Scala Native 0.4.x, which means it does not at present support native multithreading. This was a very intentional choice meant to give us an opportunity to break binary compatibility only on Scala Native if necessary when upgrading to Scala Native 0.5 and as we discover the impacts of the integrated runtime on the downstream ecosystem. It also reduces risk since Native multithreading in the runtime is a significant lift and we want to make sure we isolate that change from the already significant changes in 3.6.0. This functionality is already under development and we plan to release it in 3.7.0 as soon as possible.

What's Changed

This release contains the largest change to the Cats Effect internal work scheduler since the introduction of work stealing back in the run up to 3.0.0. In particular, we have finally completed implementation of the integrated runtime we first conceived of back in early 2022. Well, I say "we", but really @armanbilge deserves the absolute lion's share of the credit here. He did almost all of the work not only on the direct implementation in Cats Effect, but also the downstream functionality built on top of it in Fs2 and in Http4s… not only on the JVM but also in Scala Native and across multiple operating systems! It is hard to overstate how gargantuan of an effort this was, both in design and implementation.

As immense as the effort has been, the impact is even more dramatic. We've already observed scenarios in which the performance of microservices implemented on top of Http4s Ember on the JVM leveraging io_uring is improved by over 3.5x! That is to say, the performance is 3.5x higher than baseline using classical NIO2! (as measured by TechEmpower, suggesting performance more than 2x higher than pekko-http) Now, TechEmpower does have its limitations as a framework, but it does represent a useful standard candle for certain access patterns, and improving an already very fast trio of frameworks by this magnitude is not something that happens every day. Even more excitingly, this is just the tip of the iceberg! We ran these tests with very early, almost PoC code with a lot of performance-impacting caveats. The best is yet to come.

And if that wasn't enough, the biggest impacts are not on the JVM but actually on Scala Native. Without diving too far into the details, this type of syscall scheduling mechanism is exactly what is necessary on Scala Native to achieve any measure of performance from downstream services. It is actually remarkably similar to what the Go runtime does, though implemented in a more extensible way (e.g. Go does not, at present, have native support for io_uring, whereas Cats Effect can and has implemented this via a third-party library).

Going forward, Cats Effect will be maintaining support for the following polling systems:

  • JVM
    • Selector
  • Native
    • kqueue
    • epoll

Support for io_uring is already under heavy development, and we expect to incorporate this into Cats Effect at some future date, supporting both Native and JVM. The integrated runtime was specifically designed with io_uring's unique data patterns in mind and we have already been able to demonstrate that downstream layers of the ecosystem will be able to fully leverage its benefits. Additionally, we believe we can meaningfully improve JVM performance by implementing epoll and kqueue support for the JVM (and not just Native), the former for situations where io_uring is unavailable. This is mostly because Selector is actually very very slow, and while the performance of the Selector-based runtime is roughly on par with what we've been able to achieve on top of NIO2 (which has its own syscall management and is incompatible with the integrated runtime), we know we can do quite a bit better.

On top of the above, this release contains a large number of other enhancements covering a number of major scenarios. Most noticeably, thanks to @kamilkloch, explicitly importing cats.syntax.all._ is no longer required for most usage involving explicit IO! You will still need the syntax import for any use of parametric effects (commonly referred to as "tagless final" or F[_]), and unfortunately due to the way Scala's type inference works, it is also required for the very common traverse function, but nearly any and all other cases have had their implicit search tweaked to avoid this inconvenience. This in turn means that . completion now mostly Just Works™ when using IO (and when it doesn't, hunting for methods on the IO companion object definitely works).

An additional class of work went into substantially improving the internal instrumentation and metrics associated with the runtime. As previously, these are all exposed as JMX MBeans on the JVM, but we have additionally added public APIs which allow applications to self-instrument (rather than forcing external untyped instrumentation via JMX). These metrics have been organized to mirror the structure of the runtime itself and can all be found within the cats.effect.unsafe.metrics package.

If you're an end-user of Cats Effect (in other words, you run applications built on Cats Effect, rather than building libraries or frameworks), one way you can very much aid the future development of the library is to incorporate these metrics (likely via JMX) into your application observability and key metrics. This should allow you to start to build up an intuition for what metrics are significant indicators of good or bad or just plain normal behavior. This is exactly the type of information that is difficult for library authors to realistically determine, but if end-users learn this on our behalf, you can help educate us on the precise details of how the runtime behaves for your application in your production context, shaping the future optimization and tuning of the framework! (note: Cats Effect does not proactively send metrics anywhere from your application, it merely exposes them to your own monitoring infrastructure)

Enhancements

Read more

Contributors

djspiewak, biochimia, and 30 other contributors
Assets 2
Loading

v3.5.7

25 Nov 18:11
@armanbilge armanbilge
v3.5.7
58a54e8
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Learn about vigilant mode.
Compare
Choose a tag to compare
v3.5.7 Latest
Latest

This is the fifty-second release in the Cats Effect 3.x lineage. It is fully binary compatible with every 3.x release and fully source-compatible with every 3.5.x release.

Warning

The 3.5.x series contains some changes that may be semantically breaking with respect to earlier 3.x releases. If you're using fs2, http4s, or other libraries from the ecosystem, make sure you've upgraded to versions of these libraries that are compatible with this release (for fs2, that's 3.7.0+, for http4s it's 0.23.19+)!

Additionally, if you're using methods like fromFuture, make sure you're aware of the major changes to async, described in these release notes.

What's Changed

Enhancements

  • Propagate Java thread interruption in Dispatcher#unsafeRunSync by @kamilkloch in #4167

Behind the Scenes

Full Changelog: v3.5.6...v3.5.7

Contributors

kamilkloch and samspills
Assets 2
Loading

v3.5.6

19 Nov 18:00
@armanbilge armanbilge
v3.5.6
98b175b
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Learn about vigilant mode.
Compare
Choose a tag to compare
v3.5.6

This is the fifty-first release in the Cats Effect 3.x lineage. It is fully binary compatible with every 3.x release and fully source-compatible with every 3.5.x release.

Warning

The 3.5.x series contains some changes that may be semantically breaking with respect to earlier 3.x releases. If you're using fs2, http4s, or other libraries from the ecosystem, make sure you've upgraded to versions of these libraries that are compatible with this release (for fs2, that's 3.7.0+, for http4s it's 0.23.19+)!

Additionally, if you're using methods like fromFuture, make sure you're aware of the major changes to async, described in these release notes.

What's Changed

Enhancements

  • Only remove error callback if we've added it by @durban in #4168

Bug Fixes

Documentation

Behind the Scenes

Full Changelog: v3.5.5...v3.5.6

Contributors

reardonj, lenguyenthanh, and 2 other contributors
Assets 2
Loading

v3.5.5

27 Oct 19:24
@armanbilge armanbilge
v3.5.5
d241856
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Learn about vigilant mode.
Compare
Choose a tag to compare
v3.5.5

This is the fiftieth release in the Cats Effect 3.x lineage. It is fully binary compatible with every 3.x release and fully source-compatible with every 3.5.x release.

Warning

The 3.5.x series contains some changes that may be semantically breaking with respect to earlier 3.x releases. If you're using fs2, http4s, or other libraries from the ecosystem, make sure you've upgraded to versions of these libraries that are compatible with this release (for fs2, that's 3.7.0+, for http4s it's 0.23.19+)!

Additionally, if you're using methods like fromFuture, make sure you're aware of the major changes to async, described in these release notes.

What's Changed

Enhancements

Bug Fixes

  • Fix #4066: shut down executors when IORuntime.global shuts down by @durban in #4067
  • Use IOApp#reportFailure instead of printStackTrace() for blocking EC by @fredfp in #4044
  • Fix cancelable to guarantee cancelation by @armanbilge in #4118

Documentation

Behind the Scenes

New Contributors

Full Changelog: v3.5.4...v3.5.5

Contributors

djspiewak, mzuehlke, and 7 other contributors
Assets 2
Loading

v3.5.4

05 Mar 21:45
@djspiewak djspiewak
v3.5.4
4fc5628
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Learn about vigilant mode.
Compare
Choose a tag to compare
v3.5.4

This is the forty-ninth release in the Cats Effect 3.x lineage. It is fully binary compatible with every 3.x release and fully source-compatible with every 3.5.x release.

Warning

The 3.5.x series contains some changes that may be semantically breaking with respect to earlier 3.x releases. If you're using fs2, http4s, or other libraries from the ecosystem, make sure you've upgraded to versions of these libraries that are compatible with this release (for fs2, that's 3.7.0+, for http4s it's 0.23.19+)!

Additionally, if you're using methods like fromFuture, make sure you're aware of the major changes to async, described in these release notes.

What's Changed

The most significant change in this release involves the complete greenfield rewrite of Dispatcher. While Dispatcher is, in practice, one of the most-used components of Cats Effect apart from IO itself, it is also one of the oldest and most "accreted" parts of the codebase. The original variant of Dispatcher had far fewer features and was thrown together relatively quickly during the 3.0 milestone process, and every change and enhancement to its functionality has been layered on top of that foundation.

In this release, we started with an empty editor buffer and rebuilt the whole thing, taking the opportunity to correct a number of corner cases in semantics while significantly beefing up the test suite. We're very confident that the results are much more stable and reliable than the previous iteration, and we're excited to get it into everyone's hands!

Enhancements

  • IORuntimeConfig: reject invalid auto-yield and cancelation check thresholds by @durban in #3987
  • Rewrote Dispatcher by @djspiewak in #3923

Bug Fixes

Documentation

  • Fix typos in Async scaladoc by @durban in #3995
  • Removes language:postfixOps from tutorial as it is not used. by @froth in #4025

Behind the Scenes

New Contributors

Full Changelog: v3.5.3...v3.5.4

Contributors

djspiewak, durban, and 3 other contributors
Assets 2
Loading

v3.5.3

15 Jan 22:37
@armanbilge armanbilge
v3.5.3
d246e7f
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.
Compare
Choose a tag to compare
v3.5.3

This is the forty-eighth release in the Cats Effect 3.x lineage. It is fully binary compatible with every 3.x release and fully source-compatible with every 3.5.x release.

Warning

The 3.5.x series contains some changes that may be semantically breaking with respect to earlier 3.x releases. If you're using fs2, http4s, or other libraries from the ecosystem, make sure you've upgraded to versions of these libraries that are compatible with this release (for fs2, that's 3.7.0+, for http4s it's 0.23.19+)!

Additionally, if you're using methods like fromFuture, make sure you're aware of the major changes to async, described in these release notes.

What's Changed

Enhancements

Bug Fixes

Documentation

Behind the Scenes

New Contributors

Full Changelog: v3.5.2...v3.5.3

Contributors

Daenyth, lenguyenthanh, and 8 other contributors
Assets 2
Loading

v3.5.2

27 Sep 22:36
@armanbilge armanbilge
v3.5.2
2637a5e
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.
Compare
Choose a tag to compare
v3.5.2

This is the forty-seventh release in the Cats Effect 3.x lineage. It is fully binary compatible with every 3.x release and fully source-compatible with every 3.5.x release.

⚠️ Important note

The 3.5.x series contains some changes that may be semantically breaking with respect to earlier 3.x releases. If you're using fs2, http4s, or other libraries from the ecosystem, make sure you've upgraded to versions of these libraries that are compatible with this release (for fs2, that's 3.7.0+, for http4s it's 0.23.19+)!

Additionally, if you're using methods like fromFuture, make sure you're aware of the major changes to async, described in these release notes.

What's Changed

Features

Bug Fixes

Behind the Scenes

Documentation

New Contributors

Full Changelog: v3.5.1...v3.5.2

Contributors

djspiewak, Daenyth, and 9 other contributors
Assets 2
Loading

v3.5.1

24 Jun 19:20
@djspiewak djspiewak
v3.5.1
9c00cf1
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.
Compare
Choose a tag to compare
v3.5.1

This is the forty-sixth release in the Cats Effect 3.x lineage. It is fully binary compatible with every 3.x release and fully source-compatible with every 3.5.x release.

⚠️ Important note

The 3.5.x series contains some changes that may be semantically breaking with respect to earlier 3.x releases. If you're using fs2, http4s, or other libraries from the ecosystem, make sure you've upgraded to versions of these libraries that are compatible with this release (for fs2, that's 3.7.0+, for http4s it's 0.23.19+)!

Additionally, if you're using methods like fromFuture, make sure you're aware of the major changes to async, described in these release notes.

What's Changed

Bug Fixes

Behind the Scenes

Documentation

  • Point out cancelation semantics in fromCompletableFuture scaladoc by @danicheg in #3644

Full Changelog: v3.5.0...v3.5.1

Contributors

djspiewak, durban, and 3 other contributors
Assets 2
Loading

v3.5.0

12 May 01:59
@djspiewak djspiewak
v3.5.0
9236a21
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.
Compare
Choose a tag to compare
v3.5.0

This is the forty-fifth release in the Cats Effect 3.x lineage. It is fully binary compatible with every 3.x release.

⚠️ Important note

This release contains some changes that may be semantically breaking. If you're using fs2, http4s, or other libraries from the ecosystem, make sure you've upgraded to versions of these libraries that are compatible with this release (for fs2, that's 3.7.0, for http4s it's 0.23.19)!

Additionally, if you're using methods like fromFuture, make sure you're aware of the major changes to async, described in these release notes.

This is an incredibly exciting release! 3.5.0 represents the very first steps towards a fully integrated runtime, with support for timers (IO.sleep) built directly into the Cats Effect fiber runtime. This considerably increases performance for existing Cats Effect applications, but particularly those which rely more heavily on native IO concurrency (e.g. Http4s Ember will see more benefits than Http4s Blaze).

Additionally, we've taken the opportunity presented by a minor release to fix some breaking semantic issues within some of the core IO functionality, particularly related to async. For most applications this should be essentially invisible, but it closes a long-standing loophole in the cancelation and backpressure model, ensuring a greater degree of safety in Cats Effect's guarantees.

Major Changes

Despite the deceptively short list of merged pull requests, this release contains an unusually large number of significant changes in runtime semantics. The changes in async cancelation (and particularly the implications on async_) are definitely expected to have user-facing impact, potentially breaking existing code in subtle ways. If you have any code which uses async_ (or async) directly, you should read this section very carefully and potentially make the corresponding changes.

async Cancelation Semantics

The IO.async (and correspondingly, Async#async) constructor takes a function which returns a value of type IO[Option[IO[Unit]]], with the Some case indicating the finalizer which should be invoked if the fiber is canceled while asynchronously suspended at this precise point, and None indicating that there is no finalizer for the current asynchronous suspension. This mechanism is most commonly used for "unregister" functions. For example, consider the following reimplementation of the sleep constructor:

def sleep(time: FiniteDuration, executor: ScheduledExecutorService): IO[Unit] =
  IO.async[Unit] { cb =>
    IO {
      val f = executor.schedule(() => cb(Right(())), time.toNanos, TimeUnit.NANOSECONDS)
      Some(IO(f.cancel()))
    }
  }

In the above, the IO returned from sleep will suspend for time. If its fiber is canceled, the f.cancel() function will be invoked (on ScheduledFuture), which in turn removes the Runnable from the ScheduledExecutorService, avoiding memory leaks and such. If we had instead returned None from the registration effect, there would have been no finalizer and no way for fiber cancelation to clean up the stray ScheduledFuture.

The entirety of Cats Effect's design is prescriptively oriented around safe cancelation. If Cats Effect cannot guarantee that a resource is safely released, it will prevent cancelation from short-circuiting until execution proceeds to a point at which all finalization is safe. This design does have some tradeoffs (it can lead to deadlocks in poorly behaved programs), but it has the helpful outcome of strictly avoiding resource leaks, either due to incorrect finalization or circumvented backpressure.

...except in IO.async. Prior to 3.5.0, defining an async effect without a finalizer (i.e. producing None) resulted in an effect which could be canceled unconditionally, without the invocation of any finalizer. This was most seriously felt in the async_ convenience constructor, which always returns None. Unfortunately, this semantic is very much the wrong default. It makes the assumption that the normal case for async is that the callback just cleans itself up (somehow) and no unregistration is possible or necessary. In almost all cases, the opposite is true.

It is exceptionally rare, in fact, for an async effect to not have an obvious finalizer. By defining the default in this fashion, Cats Effect made it very easy to engineer resource leaks and backpressure loss. This loophole is now closed, both in the IO implementation and in the laws which govern its behavior.

As of 3.5.0, the following is now considered to be uncancelable:

IO.async[A] { cb =>
  IO {
    // ...
    None    // we aren't returning a finalizer
  }
}

Previously, the above was cancelable without any caveats. Notably, this applies to all uses of the async_ constructor!

In practice, we expect that usage of the async constructor which was already well behaved will be unaffected by this change. However, any use which is (possibly unintentionally) relying on the old semantic will break, potentially resulting in deadlock as a cancelation which was previously observed will now be suppressed until the async completes. For this reason, users are advised to carefully audit their use of async to ensure that they always return Some(...) with the appropriate finalizer that unregisters their callback.

In the event that you need to restore the previous semantics, they can be approximated by producing Some(IO.unit) from the registration. This is a very rare situation, but it does arise in some cases. For example, the definition of IO.never had to be adjusted to the following:

def never: IO[Nothing] =
  IO.async(_ => IO.pure(Some(IO.unit)))  // was previously IO.pure(None)

This change can result in some very subtle consequences. If you find unexpected effects in your application after upgrading to 3.5.0, you should start your investigation with this change! (note that this change also affects third-party libraries using async, even if they have themselves not yet updated to 3.5.0 or higher!)

Integrated Timers

From the very beginning, Cats Effect and applications built on top of it have managed timers (i.e. IO.sleep and everything built on top of it) on the JVM by using a separate thread pool. In particular, ScheduledExecutorService. This is an extremely standard approach used prolifically by almost all JVM applications. Unfortunately, it is also fundamentally suboptimal.

The problem stems from the fact that ScheduledExecutorService isn't magic. It works by maintaining one or more event dispatch threads which interrogate a data structure containing all active timers. If any timers have passed their expiry, the thread invokes their Runnable. If no timers are expired, the thread blocks for the minimum time until the next timer becomes available. In its default configuration, the Cats Effect runtime provisions exactly one event dispatch thread for this purpose.

This isn't so bad when an application makes very little use of timers, since the thread in question will spend almost all of its time blocked, doing nothing. This affects timeslice granularity within the OS kernel and adds an additional GC root, but both effects are small enough that they are usually unnoticed. The bigger problem comes when an application is using a lot of timers and the thread is constantly busy reading that data structure and dispatching the next set of Runnable(s) (all of which complete asyncs and immediately shift back into the Cats Effect compute pool).

Unfortunately, this situation where a lot of timers are in use is exactly what happens in every network application, since each and every active socket must have at least one IO.sleep associated with it to time out handling if the remote side stops responding (in most cases, such as HTTP, even more than one timer is needed). In other words, the fact that IO.sleep is relatively inefficient when a lot of concurrent sleeps are scheduled is particularly egregiously bad, since this is precisely the situation that describes most real-world usage of Cats Effect.

So we made this better! Cats Effect 3.5.0 introduces a new implementation of timers based on cooperative polling, which is basically the idea that timers can be dispatched and handled entirely by the same threads which handle compute work. Every time a compute worker thread runs out of work to do (and has nothing to steal), rather than just parking and waiting for more work, it first checks to see if there are any outstanding timers. If there are some which are ready to run, it runs them. Otherwise, if there are timers which aren't yet completed, the worker parks for that period of time (or until awakened by new work), ensuring the timer fires on schedule. In the event that a worker has not had the opportunity to park in some number of iterations, it proactively checks on its timers just to see if any have expired while it has been busy doing CPU-bound work.

This technique works extremely well in Cats Effect precisely because every timer had to shift back to the compute pool anyway, meaning that it was already impossible for any timer to have a granularity which was finer than that of the compute worker thread task queue. Thus, having that same task queue manage the dispatching of the timers themselves ensures that at worst those timers run with the same precision as previously, and at best we are able to avoid a considerable amount of overhead both in the form of OS kernel scheduler contention (since we are removing a whole thread from ...

Read more

Contributors

djspiewak, Odomontois, and 18 other contributors
Assets 2
Loading

v3.4.11

11 May 22:50
@djspiewak djspiewak
v3.4.11
This tag was signed with the committer’s verified signature.
djspiewak Daniel Spiewak
GPG key ID: 8DB0AD19E03F6F2F
Learn about vigilant mode.
7cd4523
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.
Compare
Choose a tag to compare
v3.4.11

This is the forty-fourth release in the Cats Effect 3.x lineage. It is fully binary compatible with every 3.x release. It is fully binary compatible with every 3.x release, and fully source-compatible with every 3.4.x release. Note that source compatibility has been broken with 3.3.x in some minor areas. Since those changes require active choice on the part of users to decide the best adjusted usage for their specific scenario, we have chosen to not provide scalafixes which automatically patch the affected call sites.

User-Facing Pull Requests

Thank you, Daniel!

Contributors

durban
Assets 2
Loading