13. Cats Effect
Delete io.scala and io.test.scala. The project stops compiling, because evening.scala has lost its IO. The replacement comes from Cats Effect. Libraries like it are known as effect systems: they supply an IO type and the runtime that runs it. The service in Part IV is built from http4s and doobie, which are both written on top of Cats Effect.
13.1. The real IO
In project.scala, add the dependency under the one for Cats:
//> using dep org.typelevel::cats-effect:3.7.1
Cats Effect is another library compiled with Scala 3.3, so the Unsafe warning that chapter 6 switched off for tests would now appear on every scala run. Change the last line of the file from test.javaOpt to javaOpt, which applies the option to both:
//> using javaOpt --sun-misc-unsafe-memory-access=allow
Then replace the whole of evening.scala:
package fullybooked
import cats.effect.{IO, IOApp}
import java.time.LocalTime
def reserveIO(
store: BookingStore,
party: Party,
time: LocalTime
): IO[Either[BookingError, Booking]] =
IO.blocking(reserve(store, party, time))
def walkInIO(store: BookingStore, party: Party, time: LocalTime): IO[Unit] =
for
_ <- IO.println(s"${party.name}, party of ${party.size}, asks for a table at $time")
result <- reserveIO(store, party, time)
_ <- IO.println(reply(party.name, result))
yield ()
object WalkIns extends IOApp.Simple:
val eight = LocalTime.of(20, 0)
def run: IO[Unit] =
for
store <- IO.delay(InMemoryBookingStore())
_ <- walkInIO(store, Party("Silva", 2), eight)
_ <- walkInIO(store, Party("Zielinski", 9), eight)
count <- IO.delay(store.all.size)
_ <- IO.println(s"$count booking in the store")
yield ()
Don’t leave out the import of cats.effect.IO, in this file or any later one. Java 25 has a small console class of its own called java.lang.IO. Without the import the compiler finds that one and reports that “IO does not take type parameters”.
Cats Effect has an IO.println, so our printLine has gone from walkInIO. reserveIO now uses IO.blocking where it had IO.delay. Both wrap code in an IO, and the section on threads below says how they differ.
The @main method has become WalkIns, an object that extends IOApp.Simple and supplies run, the program. IOApp provides the main method, starts the threads that Cats Effect runs on, runs our IO and shuts everything down afterwards. That main method is the edge of the program from chapter 12, and since the library wrote it, WalkIns calls nothing with unsafe in its name. Creating the store has moved inside the for as well. IO.delay(InMemoryBookingStore()) makes a new store each time the program runs, where a val outside the for would be made once and shared by every run.
An object is run by its name:
$ scala run . --main-class fullybooked.WalkIns
Silva, party of 2, asks for a table at 20:00
Silva: table 1 at 20:00
Zielinski, party of 9, asks for a table at 20:00
Zielinski: sorry, we can't seat 9, our largest table takes 8
1 booking in the store
13.2. When something throws
Create effects.test.scala:
package fullybooked
import cats.effect.{IO, Resource}
import cats.effect.unsafe.implicits.global
class EffectTests extends munit.FunSuite:
val failing: IO[Int] = IO.delay("seven".toInt)
test("an exception inside an IO is a value until someone asks for it"):
val result = failing.attempt.unsafeRunSync()
assert(result.isLeft)
test("handleErrorWith swaps a failed program for another one"):
assertEquals(failing.handleErrorWith(error => IO.pure(0)).unsafeRunSync(), 0)
A test has no IOApp, so it runs its programs by hand with unsafeRunSync(), until chapter 21 brings in a tidier way. That method takes the threads Cats Effect runs on as a using parameter, and the second import supplies them. Nothing uses the Resource in the first import until the next section. Run the tests.
Inside failing, "seven".toInt throws a NumberFormatException. Our own IO let an exception like that fly out of unsafeRun. The real one catches it and the program becomes a failed IO, in which every later step is skipped until something handles the failure. In the first test, attempt turns the IO[Int] into an IO[Either[Throwable, Int]] that never fails, with the exception as a Left. In the second test, handleErrorWith is given a function that takes the exception and returns a program to run instead of the failed one, which here is IO.pure(0).
When reserveIO meets a full restaurant, the result is a Left inside a successful IO. A write to a disk that’s full would make the IO itself fail. Chapter 9 split failures that way: the ones that are part of the job were returned as values and the rest were left as exceptions.
13.3. Something to close afterwards
The owner wants a record on disk of every answer the restaurant gives. A file has to be opened, written to and closed, even if something fails halfway. Create journal.scala:
package fullybooked
import cats.effect.{IO, Resource}
import java.io.PrintWriter
class Journal(writer: PrintWriter):
def record(line: String): IO[Unit] =
IO.blocking:
writer.println(line)
writer.flush()
object Journal:
def open(path: String): Resource[IO, Journal] =
Resource
.make(IO.blocking(PrintWriter(path))): writer =>
for
_ <- IO.blocking(writer.close())
_ <- IO.println(s"Closed $path")
yield ()
.map(writer => Journal(writer))
In open, the first argument to Resource.make is a program that acquires something, here a PrintWriter on the file. The second is a function that takes the writer and returns the program that releases it. Resource.make returns a Resource, which describes something that can be opened and closed. Calling use with a function gives a program that acquires the writer, runs the function and releases the writer again, whether the function finished or failed. Nothing is opened until that program runs. Java’s try with resources gives that guarantee for one block of code. A Resource is a value, so a method such as open can return one and leave its caller to decide where to use it. A Resource also has a map that changes what it holds. The .map on the last line of open carries on the chain after the indented block and turns the writer into a Journal.
Add a test for the failing case to the end of EffectTests:
test("a resource is released when its use fails"):
var open = 0
val door = Resource.make(IO.delay { open = open + 1 })(_ => IO.delay { open = open - 1 })
val result = door.use(_ => IO.raiseError(RuntimeException("fire alarm"))).attempt
assert(result.unsafeRunSync().isLeft)
assertEquals(open, 0)
The resource here is only a counter, which goes up by one when it’s acquired and down by one when it’s released. The function given to use returns IO.raiseError(...), a failed IO made from an exception without throwing it. After attempt has caught the failure the counter is back at zero, so the release ran. The braces around open = open + 1 are the older way of passing a block, which is still handy when the block fits on one line.
In chapter 12 a chain of a million flatMaps overflowed the stack. Add one more test, for that chain on Cats Effect, and run them all:
test("a million flatMaps are no trouble"):
def countdown(from: Int): IO[Unit] =
if from == 0 then IO.unit
else IO.delay(()).flatMap(_ => countdown(from - 1))
countdown(1000000).unsafeRunSync()
13.4. Configuration
The journal’s file name shouldn’t be written into the code. PureConfig is a library that reads settings from a file into a case class. Add two more lines to project.scala, a dependency to go with the others and a directory for files that aren’t Scala:
//> using dep com.github.pureconfig::pureconfig-core:0.17.11
//> using resourceDir resources
Make a directory called resources in the project and put a file called application.conf in it:
restaurant = "Fully Booked"
journal = "journal.log"
store-delay = 300 milliseconds
Then create config.scala:
package fullybooked
import cats.effect.IO
import pureconfig.{ConfigReader, ConfigSource}
import scala.concurrent.duration.FiniteDuration
case class AppConfig(
restaurant: String,
journal: String,
storeDelay: FiniteDuration
) derives ConfigReader
val loadConfig: IO[AppConfig] =
IO.blocking(ConfigSource.default.loadOrThrow[AppConfig])
The derives clause from chapter 11 has the compiler write a ConfigReader, the code that reads each field of AppConfig from the setting of the same name. A name like storeDelay is matched with store-delay in the file. The ConfigReader turns 300 milliseconds into a FiniteDuration, Scala’s type for a length of time. If a setting is missing or can’t be read as its field’s type, loadOrThrow throws an exception that lists every setting with a problem. Because the call is inside IO.blocking, the exception makes loadConfig a failed IO. I want a program with bad configuration to stop at start-up and say why.
13.5. Logging
IO.println won’t do for a service, where logging needs levels and a choice of where the output goes. The usual arrangement on the JVM is the SLF4J interface with Logback behind it. log4cats puts an IO in front of that. Add two more dependencies to project.scala. The second is a Java library, so it has single colons:
//> using dep org.typelevel::log4cats-slf4j:2.8.0
//> using dep ch.qos.logback:logback-classic:1.6.7
Logback reads its settings from a file called logback.xml. Put it in resources too:
<configuration>
<statusListener class="ch.qos.logback.core.status.NopStatusListener"/>
<appender name="console" class="ch.qos.logback.core.ConsoleAppender">
<encoder>
<pattern>%-5level %logger{0}: %msg%n</pattern>
</encoder>
</appender>
<root level="INFO">
<appender-ref ref="console"/>
</root>
</configuration>
I’ve left the time out of the pattern so that the output printed in this book is the same on every run. A real service would normally include the time. The statusListener line stops Logback describing its own start-up, which it would otherwise do at length here because the scala command puts logback.xml on the classpath twice.
13.6. Putting it together
One more file uses the configuration, the logger and the journal together. Create service.scala:
package fullybooked
import cats.effect.{IO, IOApp}
import java.time.LocalTime
import org.typelevel.log4cats.Logger
import org.typelevel.log4cats.slf4j.Slf4jLogger
object Evening extends IOApp.Simple:
val logger: Logger[IO] = Slf4jLogger.getLogger[IO]
val eight = LocalTime.of(20, 0)
def book(store: BookingStore, journal: Journal, party: Party): IO[Unit] =
for
result <- reserveIO(store, party, eight)
_ <- logger.info(reply(party.name, result))
_ <- journal.record(reply(party.name, result))
yield ()
val evening: IO[Unit] =
for
config <- loadConfig
_ <- logger.info(s"${config.restaurant} is open")
store <- IO.delay(SlowStore(config.storeDelay.toMillis))
_ <- Journal.open(config.journal).use: journal =>
for
_ <- book(store, journal, Party("Silva", 2))
_ <- book(store, journal, Party("Zielinski", 9))
yield ()
_ <- logger.info("Done for the night")
yield ()
def run: IO[Unit] =
evening.handleErrorWith: error =>
logger.error(s"Stopped early: ${error.getMessage}")
Each call to logger.info returns an IO[Unit], so the message is only logged if that IO is part of the program that gets run. An IO that’s built and then dropped, on a line of its own outside the for, does nothing. That’s the mistake to look for when a log message or a write goes missing.
$ scala run . --main-class fullybooked.Evening
INFO Evening: Fully Booked is open
INFO Evening: Silva: table 1 at 20:00
INFO Evening: Zielinski: sorry, we can't seat 9, our largest table takes 8
Closed journal.log
INFO Evening: Done for the night
Print the journal with cat, or with type on Windows:
$ cat journal.log
Silva: table 1 at 20:00
Zielinski: sorry, we can't seat 9, our largest table takes 8
In the program’s output, “Closed journal.log” comes before “Done for the night”, because the journal is released as soon as use finishes. Now run it with the journal somewhere that doesn’t exist. The configuration library underneath PureConfig lets a Java system property override a setting, and --java-prop sets one:
$ scala run . --main-class fullybooked.Evening --java-prop journal=/no/such/place/journal.log
INFO Evening: Fully Booked is open
ERROR Evening: Stopped early: /no/such/place/journal.log (No such file or directory)
Opening the file failed, so the IO failed and the steps after it never ran. The handleErrorWith in run turned that into one line in the log. There’s no “Closed” line, since nothing had been opened.
13.7. Threads
The pool of threads that IOApp starts is small, with one thread for each processor core. By default every step of every IO runs on it. That’s enough for a great deal of work, but only as long as no step holds on to a thread while it waits. A call that waits for a disk or a database, or sits in a Thread.sleep, ties up one of those few threads until it returns.
Wrapping a call like that in IO.blocking tells the runtime that the body will wait. The runtime then runs the body on a thread outside the pool, which stays at full strength. reserveIO is written with IO.blocking because the store it’s given may be a SlowStore. The journal uses it for writing its file and loadConfig for reading one. Code that doesn’t wait goes in IO.delay. For waiting on purpose there’s IO.sleep, which takes a duration and holds no thread at all while the time passes. The rule I work to is that anything which might wait on the outside world goes in IO.blocking. Getting it wrong shows up late, as a program that’s slow under load and hard to diagnose.
13.8. Reading F[_]
We’ve given IO as a type argument three times, in Logger[IO], Resource[IO, Journal] and getLogger[IO]. Look up Logger in the documentation for log4cats and you’ll find it declared as Logger[F[_]], with methods such as info(message: => String): F[Unit].
The F[_] there is a type parameter that stands for a type which itself takes a parameter, such as IO, Option or List. Put IO where the F is and F[Unit] reads IO[Unit]. Libraries are written this way so that they work with more than one effect system. Their signatures also carry context bounds like [F[_]: Sync], which asks for an F that has a given Sync. That’s a type class from Cats Effect for types that can delay code, as IO.delay does. IO has a given for it, and for Async, Concurrent and Temporal, which turn up in the same position.
Some teams write all of their own code against F[_] as well, a style called tagless final. I write IO in Fully Booked, so F[_] only appears in other people’s signatures, where you can nearly always read it as IO.
13.9. Exercises
Solutions are in the book’s downloadable code, under ch13/exercises.
-
Add a
greetingsetting toapplication.confand toAppConfig, with a default of “Good evening”. A second line,greeting = ${?FULLY_BOOKED_GREETING}, lets an environment variable replace it when it’s set. Try both. -
Write chapter 12’s
retryagain for Cats Effect’sIO, this time waiting between attempts.IO.sleep(pause)takes aFiniteDuration, and importingscala.concurrent.duration.*lets you write one as10.millis. -
A
forworks overResourcetoo. WritetwoJournals(first: String, second: String): Resource[IO, (Journal, Journal)]and use it. In which order are the two files closed? -
Write
timed[A](program: IO[A]): IO[(A, FiniteDuration)].IO.monotonicis anIOthat reads a clock.