Comparing Cats Effect and ZIO
ZIO and Cats Effect, two great Scala libraries, compared side by side. Each of them offers tools for writing asynchronous and concurrent applications.
Asynchronous and concurrent programming for Scala that is type-safe and composable
The slogan on the ZIO website
A pure asynchronous runtime for Scala
The slogan on the Cats Effect website
This article sets out to compare two great Scala libraries: ZIO and Cats Effect. Each of them offers tools for writing asynchronous and concurrent applications.
Both have proven themselves in battle and run in production at many companies. What’s more, both rest on the functional programming paradigm – they implement a functional effect system. We’ll look at the philosophy behind the libraries, their core features, and what they have in common and where they differ. I won’t go into the nitty-gritty – many aspects of these libraries would need articles of their own.
I’ll concentrate on the newest versions of both: the ZIO 2.x series and Cats Effect 3.x.
The IO monad
Both Cats Effect and ZIO rely on a dedicated data type for suspending computations, known as the IO monad. In CE, it’s named IO, while in ZIO it’s simply ZIO (though some specialized aliases such as URIO or Task are used as well – more on that later).
The IO monad lets us suspend computations that produce a value and may perform a side effect. The central idea is that such actions can be composed and transformed just like any other value in functional programming. Programs built from composed IOs can then be evaluated, ideally at the application’s entry point, known as the “end-of-the-world”. The component that runs these programs efficiently is called the runtime, and it is at the heart of both libraries.
Core features
Each library offers a range of combinators for suspending impure, side-effecting computations and working with them. Here’s a brief overview.
Cats Effect
In CE, the easiest way to turn impure code into a functional effect is to wrap the computation in IO, using the apply method.
val io: IO[Int] = IO(StdIn.readInt())
Because the action is evaluated lazily (suspended), the value can be safely reused in different places in the program, and it will behave the same each time.
When we know for sure that our code has no side effects and just returns a value, we can wrap it in IO with IO.pure.
val pureIO: IO[Int] = IO.pure(42)
CE also ships with numerous combinators for creating frequently used effects, for example:
- getting the current time (
IO.realTime) - reading a line from standard input (
IO.readLine) - printing a line (
IO.printLine) - sleeping for a while (
IO.sleep) - and plenty of others
IO values are monadic and offer methods such as map and flatMap, which let us combine IOs into larger programs:
//> using dep "org.typelevel::cats-effect:3.5.1"
val program: IO[String] = for {
_ <- IO.println("What is your name?")
name <- IO.readLine
_ <- IO.sleep(1.second)
_ <- IO.println(s"Hello, $name")
} yield name
A CE program’s result type is IO. It takes a single type argument A, which specifies the type of the value produced when the program evaluates successfully.
To define the application’s entry point, CE offers the IOApp trait.
//> using dep "org.typelevel::cats-effect:3.5.1"
import cats.effect.{IO, IOApp}
import scala.concurrent.duration.*
object CatsApp extends IOApp.Simple {
override def run: IO[Unit] =
for {
_ <- IO.sleep(2.seconds)
_ <- IO.println("Hello World")
} yield ()
}
This is the recommended way of bootstrapping a CE application. It brings in CE’s default runtime, which evaluates the program.
ZIO
In ZIO, the equivalent of IO.apply is ZIO.attempt. It takes code with side effects and places it in a ZIO context. Pure values can also be wrapped in ZIO using ZIO.succeed.
val t: ZIO[Any, Throwable, Long] =
ZIO.attempt(System.currentTimeMillis())
ZIO provides a comparable set of operators for everyday actions. For example, Console.readLine reads a line of text from standard input, Clock.currentTime gets the time, and ZIO.sleep pauses the program for a given amount of time. Every operator returns a ZIO instance that can be composed using the flatMap and map functions.
val zio: ZIO[Any, IOException, Int] = for {
_ <- Console.printLine("Calculating random number:")
_ <- ZIO.sleep(2.seconds)
result <- Random.nextInt
} yield result
The program’s structure resembles the CE app, but the result types are what catch the eye. Rather than a single generic parameter, the ZIO type has three of them. We’ll explore what each of them means in the next paragraphs; for now, just a short overview.
The last parameter, A, means the same thing as the only parameter of CE’s IO – the type of the value returned on successful evaluation, i.e. the success channel. The second type, E, is the error channel – it specifies the type (or types) of errors the application may fail with. Nothing in the error channel indicates that the program won’t fail (or at least isn’t expected to). The first one, R, is the environment – it lists all the dependencies needed to evaluate the program. A program whose environment is of type Any describes an application without dependencies.
ZIO defines a number of aliases for convenience. For example, UIO[A] represents an effect that produces a value A, can’t fail with any expected error, and needs nothing from the environment. The full list of aliases is available here.
Just like CE, ZIO provides a helper trait for bootstrapping a new app: ZIOApp, which brings in the default ZIO runtime.
//> using dep "dev.zio::zio:2.0.15"
import zio.*
object ZIOApp extends ZIOApp {
def run: ZIO[ZIOAppArgs, IOException, Unit] =
for {
_ <- ZIO.sleep(2.seconds)
_ <- Console.printLine("Hello World")
} yield ()
}
Apart from the result type signature, both libraries look and feel alike so far. Now let’s move on to the first big difference – error handling.
Error handling
Each library is designed around asynchronous processing, in which a single computation may run on many threads over its lifetime. Because of this, we can’t simply rely on the language’s standard mechanisms for throwing and catching exceptions. That’s why CE and ZIO offer dedicated machinery for raising, propagating and handling errors.
ZIO
ZIO handles errors in its own distinctive way, distinguishing three kinds of errors:
- expected errors, known as failures
- unexpected errors – defects
- fatal errors
We’ll begin with expected errors. ZIO wants to make sure we deal with them properly. It does so by placing the expected error types in its second type parameter – the error channel. Each time we raise an error with ZIO.fail, it automatically shows up in the type signature.
val failedZIO: ZIO[Any, String, Nothing] = ZIO.fail("Ups :(")
Trying to compose this ZIO with another one that has a different error type results in a compilation error. In this way, ZIO guarantees that the error has been dealt with somehow. To resolve it, we must either transform the errors with one of the many operators available, or eliminate them from the signature by handling the error.
def app: ZIO[Any, Throwable, Unit] = for {
name <- Console.readLine("What's your name?")
_ <- failedZIO //this will prevent the code from compiling
_ <- Console.printLine(s"Hello, $name!")
} yield ()
ZIO comes with a rich, flexible API for error management. We can, for example, handle just some errors with catchSome, or every error at once with catchAll.
failedZIO.catchAll(error => Console.printLine(s"Error: $error"))
ZIO also interoperates with APIs that manage errors through Either. Using ZIO.either, we can move the error out of ZIO’s error channel into an Either on the success channel (ZIO[R, E, A] => ZIO[R, Nothing, Either[E, A]]). To go in the other direction, ZIO[R, Nothing, Either[E, A]] => ZIO[R, E, A], there’s ZIO.absolve.
What about defects, then? They stand for exceptional, faulty application behavior that shouldn’t occur in the normal flow, and we’re not supposed to catch them. ZIO’s guides recommend the Let it crash approach instead. A defect is raised with ZIO.die.
val crashedZIO = ZIO.die(new IllegalStateException("SAD"))
While failures can be of any type, reported defects must be a subtype of Throwable. It usually isn’t needed, but defects can still be caught with operators such as catchAllDefects. There’s also orDie, which turns an ordinary failure (as long as it’s a subtype of Throwable) into a defect, and resurrect, which turns a defect back into a failure.
Lastly, fatal errors stand for catastrophic JVM failures, such as OOM errors. ZIO offers no way of intercepting or handling them.
Cats Effect
CE’s approach to error handling is simpler. There are no typed error channels, and the only errors we can raise are subtypes of Throwable. We then either catch them further downstream, or the unhandled exception brings the application down. In this respect, they work much like ZIO’s defects.
Errors are raised with IO.raiseError.
val failedIO: IO[Nothing] = IO.raiseError(
new IllegalStateException("NOPE")
)
To catch them, we can use handleError or handleErrorWith.
failedIO.handleErrorWith (
error => IO.println(s"Error: $error")
)
Internally, CE relies on MonadError from Cats, with the error type fixed to Throwable.
Is it possible to have typed errors in CE, though? We can still nest an Either inside IO, and two utility methods help move errors between Either and the CE error channel. The attempt method takes us from IO[A] to IO[Either[Throwable, A]], while rethrow performs the reverse transformation. Be careful – these methods aren’t foolproof. Nothing prevents us, for example, from calling attempt several times and ending up with a deeply nested Either.
val io: IO[Either[Throwable, Either[Throwable, Int]]]
= IO(1).attempt.attempt //doesn't really make sense
Working with nested monad stacks (such as Either inside IO) can get clumsy. That’s why there is a dedicated category of data types that simplifies it: monad transformers. Even so, using monad transformers isn’t as smooth as working with ZIO’s built-in error channel.
Structuring of the application
On to the next topic – how should Scala applications built with functional effect systems be structured? Pieces of business code may rely on other parts of the system that implement different bits of the logic. There may also be infrastructure dependencies (the so-called application context): a logger, database managers, or HTTP clients.
The simplest way to pass dependencies down the object graph is through constructors. Another, Scala-specific option is to use implicits (given/using in Scala 3).
The former is typically used for business logic, the latter for infrastructure-related context.
In functional Scala, we rarely rely on reflection-based DI frameworks to wire dependencies. The most popular approaches are building the object graph by hand or using a macro-based utility library such as MacWire.
These approaches work for any Scala app – so do ZIO or CE have anything extra to offer here?
ZIO
We’ve already covered errors in ZIO and how it uses a type parameter to make sure exceptions get handled properly. What about the environment type parameter, though? It lets us describe the dependencies needed to evaluate a given ZIO program. These dependencies represent application layers, described by a data type named ZLayer.
Here’s an example. Say we want to build an app that uses a layer backed by a simple in-memory map. We begin by defining the contract for the layer – an interface:
trait KVStore {
def put(key: Int, value: String): ZIO[Any, Throwable, Unit]
def get(key: Int): ZIO[Any, Throwable, Option[String]]
}
Now we can summon the layer with ZIO.service, or call a function on it with ZIO.serviceWithZIO or ZIO.serviceWith.
val app: ZIO[KVStore, Throwable, Unit] = for {
_ <- ZIO.serviceWithZIO[KVStore](_.put(1, "Adrian"))
_ <- ZIO.serviceWithZIO[KVStore](_.put(2, "Zygmunt"))
user <- ZIO.serviceWithZIO[KVStore](_.get(1))
_ <- Console.printLine(s"User: $user")
} yield ()
ZIO notices that the code refers to a layer and updates the environment type to match – here, the environment type includes KVStore. If we try to assign this ZIO type to one that doesn’t require the dependency, we get a helpful compile-time error message:
───────────── ZIO APP ERROR─────────────
─────────────────────────────────────
Your effect requires a service that is not in the environment.
Please provide a layer for the following type:
1. KVStore
To make the error go away, we need to supply the right layer. First, though, let’s implement the trait:
class InMemKVStore(val s: Ref[Map[Int, String]]) extends KVStore {
override def put(key: Int, value: String): Task[Unit]
= s.update(_.updated(key, value))
override def get(key: Int): Task[Option[String]]
= s.get.map(_.get(key))
}
Now we can create the layer. We’ll place the code in a companion object:
object InMemoryKVStore {
val layer: ZLayer[Any, Nothing, InMemoryKVStore] = ZLayer {
Ref.make(Map.empty[Int, String]).map(InMemoryKVStore(_))
}
}
Layers are supplied with the provide method (passing all of them at once) or with provideSome (supplying only some of them).
val appWithDeps: ZIO[Any, Throwable, Unit] =
app.provide(InMemoryKVStore.layer)
Layers compose very well, and they can depend on one another – for example, a database access layer may need a logger. They’re flexible too, since they can be built from many sources: ZIO effects, functions, values, and even resources whose lifecycle has to be managed.
Layers are a powerful feature that’s unique to ZIO, and a worthwhile complement to what the language already offers (such as implicits). ZIO has an opinionated way of building the object graph: declare dependencies through constructors, and then reify those constructors as values by means of layers.
Cats Effect
CE doesn’t have a built-in counterpart to ZIO’s layers, so we typically rely on what the language itself provides.
Another way to supply application context, which turns up fairly often in CE codebases, is using the Reader monad. We usually work with a monad transformer for Reader – ReaderT (also known as Kleisli). It comes with some downsides – ReaderT and IO are separate monads and can’t be composed directly. To use both in one for-comprehension, we have to lift the IO into ReaderT using ReaderT.liftF.
val app: ReaderT[IO, KVStore, Unit] = for {
_ <- ReaderT((store: KVStore) => store.put(1, "Adrian"))
_ <- ReaderT((store: KVStore) => store.put(2, "Zygmunt"))
user <- ReaderT((store: KVStore) => store.get(1))
//we need to lift IO to ReaderT
_ <- ReaderT.liftF(IO.println(s"User: $user"))
} yield ()
The required dependencies can then be supplied with the run method:
val program: IO[Unit] = app.run(InMemoryKVStore)
Resource management
Both CE and ZIO are designed on the premise that safe resource management comes first.
Curiously, each of them uses a somewhat different mechanism to reliably release resources once they’re no longer needed.
Cats Effect
We’ll start with CE, which offers a dedicated type called Resource. It describes what’s needed to manage a resource’s lifecycle: how to set it up and how to tear it down. A new Resource is created with the make method, which takes two arguments: an effect describing how to open the resource, and a function returning an effect that specifies how to close it.
def fileWriter(fileName: String): Resource[IO, FileWriter] =
Resource.make(
IO(new FileWriter(fileName))
)(
writer => IO(writer.close())
)
We can then use it through the use method.
fileWriter("foo.txt").use(writer =>
IO(writer.write("Hello World!"))
)
Resource is a monad, so it composes with flatMap. This makes it easy to build a hierarchy of resources that are opened one after another and closed in the reverse order.
val resources: Resource[IO, (FileWriter, Supervisor[IO])] = for {
writer <- fileWriter("foo.txt")
supervisor <- Supervisor[IO]
} yield (writer, supervisor)
Resource can be seen as a companion to IO. It offers a similar set of methods, but the two are separate monads and can’t be composed with each other (just like ReaderT and IO). To use both IO and Resource in one for-comprehension, the IO has to be lifted into Resource with Resource.eval.
val resources: Resource[IO, FileWriter] = for {
writer <- fileWriter("foo.txt")
_ <- Resource.eval(IO.println("Allocating file writer"))
} yield writer
ZIO
ZIO 1.x’s resource-management model is quite close to CE’s. It also includes a dedicated datatype named Managed, which can be handled much like Resource and works together with ZIO.
ZIO 2 changed this approach by introducing Scope. Like Resource, a scope represents the lifetime of one or more resources. A scope can be created with the ZIO.acquireRelease method.
def fileWriter(fileName: String):ZIO[Scope, Throwable, FileWriter] =
ZIO.acquireRelease(
ZIO.attempt(new FileWriter(fileName))
)(
fw => ZIO.succeed(fw.close())
)
As you can see, in contrast to the Resource.make method, acquireRelease doesn’t produce a special-purpose object but an ordinary ZIO. The only difference is a specific environment value called Scope. Being a plain old ZIO effect, it can be freely composed with flatMap or passed to any operator that expects a ZIO.
The magic happens with the ZIO.scoped operator. It accepts any ZIO workflow that has Scope in its environment, creates the required resources, provides them, and closes them once the workflow is done. By default, resources are opened in the order in which they were added to the scope and closed in the reverse order, though this can be customized.
The resulting type no longer has Scope in its environment, which signals that there are no more resources to handle.
def run: ZIO[ZIOAppArgs, Throwable, Unit] =
ZIO.scoped {
for {
writer <- fileWriter("foo.txt")
_ <- ZIO.attempt(writer.write("Hello World!"))
} yield ()
}
Concurrency
CE and ZIO are both excellent for building concurrent applications. Their concurrency systems are built on the fiber – a lightweight logical thread representing a sequence of actions. Here, that means a list of operations suspended in the IO monad and chained with flatMap. The ZIO and CE runtimes can multiplex tens of thousands of fibers onto just a few system threads.
In CE, a new fiber is started by calling start on the IO; in ZIO, the equivalent method is named fork. To wait for a fiber’s result, we call join (ZIO & CE). A fiber can be stopped and its computation canceled with cancel (CE) or interrupt (ZIO)
//ZIO 2.x.x
val fiber1: Task[Fiber.Runtime[Throwable, Unit]] =
ZIO.attempt(heavyComputations).fork
//CE 3.x.x
val fiber2: IO[FiberIO[Unit]] = IO(heavyComputations).start
Both libraries offer higher-level operators that follow the structured concurrency paradigm, in which the fiber’s lifecycle matches the syntactic structure of the code. For example, operators such as parSequence (CE) or collectAllPar (ZIO) run several operations in parallel. They start a number of fibers to execute the operations concurrently and shut them down once they’re no longer needed.
//ZIO 2.x.x
val result1 = ZIO.collectAllPar(listOfZIOTasks)
//CE 3.x.x
import cats.syntax.all.*
val result2 = listOfIOTasks.parSequence
Once more, the two libraries offer similar APIs and capabilities, yet there are some notable differences. In ZIO, Fibers are supervised and bound to their parents’ lifecycle. When a fiber (the parent) forks new fibers and then terminates, all of its children get interrupted too. Creating an unmanaged fiber requires the forkDaemon operator. In CE, by contrast, fibers aren’t supervised. We need a special resource, Supervisor, which ties the fibers’ lifecycle to its own. The difference may look subtle, but it can be confusing when moving between the libraries.
Both ZIO and CE ship with powerful standard libraries that support concurrency. They offer semaphores, atomic references, concurrent queues, and much more. On top of that, community-driven projects such as ZIO Actors or Cats STM give us even more capabilities.
Streaming
With streaming, just a chunk of the data sits in memory at any given time, so we can process infinite data using finite resources. Both ZIO and CE can boast mature, efficient libraries for streaming operations. CE uses fs2 as a dependency, while ZIO ships with ZIO Streams.
The two streaming libraries make some of the same design choices. Both are functional and pull-based, and they process data in chunks (as a performance optimization). They also offer a comparable high-level, declarative API for expressing complex, concurrent workflows.
Here’s a simple example of a stream built with fs2:
val stream: Stream[IO, Int] = Stream.emits(1 to 10)
.filter(_ % 2 == 0)
.map(_ * 2)
.evalTap(num => IO.println(s"Number $num"))
fs2 streams are evaluated lazily, so consuming one requires calling compile followed by one of the finalizing methods:
for {
//we need to compile to consume the stream
result <- stream.compile.fold(0)(_ + _)
_ <- IO.println(s"Result: $result")
} yield ()
And now the ZIO example:
val stream: ZStream[Any, IOException, RuntimeFlags] =
ZStream.fromIterable(1 to 10)
.filter(_ % 2 == 0)
.map(_ * 2)
.tap(num => Console.printLine(s"Number $num"))
for {
result <- stream.run(ZSink.foldLeft(0) (_ + _))
_ <- Console.printLine(s"Result: $result")
} yield ()
At a glance, the two examples look very much alike, but there’s one key difference. ZIO Streams offer an extra data type to work with – the ZSink. A sink serves much the same purpose as fs2’s compile method – consuming the stream. Its advantage is that it’s a value, which can be transformed and combined with other sinks.
The philosophy, design, and ecosystem
So far, we’ve covered the most important similarities and differences between the two libraries. Let’s now look at the design goals their developers set.
ZIO strives to be as pragmatic as it can. It follows a batteries-included approach, trying to provide everything needed to build a modern functional application right out of the box.
CE, in contrast, is lighter and less opinionated. Many features that ZIO has built in are delivered in CE by a broad range of external libraries.
In addition, CE follows the Tagless Final approach: every datatype, such as Resource, Ref, or fs2’s Stream, can take an abstract F[_] as its effect type. The only requirement for F[_] is that it implements the typeclasses defined by the Cats Effect library. As a result, we aren’t tied to IO as the monad implementation – an extra degree of flexibility that ZIO doesn’t offer.
Both CE and ZIO have rich, fast-growing ecosystems of libraries for database access, JSON parsing, HTTP clients and servers, and much more. CE libraries typically follow Tagless Final and work with any effect system that implements the CE typeclasses. Luckily, ZIO provides these through the interop-cats module, which also makes it possible to run ZIO libraries with CE.
Summary
That brings us to the end of this brief comparison of Scala’s popular effect systems. I didn’t hand out scores or strong opinions, but I hope the article helps if you’re torn between CE and ZIO for your next project. I also skipped benchmarks, which could make an interesting subject for a separate article.
Both libraries deserve a try, and both are solid choices for building modern FP-oriented apps.