12. Build your own IO
Chapter 1 said that functional Scala wraps a database query or an HTTP call in a type called IO, and that IO takes more getting used to than the rest of the style. The IO that services use comes from the Cats Effect library. We’ll write a small one of our own first. It takes about a dozen lines and has the methods we’ll use most on the real one.
12.1. A refactoring that changes the program
Create io.test.scala with one test:
package fullybooked
import java.time.LocalTime
class IOTests extends munit.FunSuite:
val eight = LocalTime.of(20, 0)
val silva = Party("Silva", 2)
test("calling reserve twice is not the same as using its result twice"):
val once = InMemoryBookingStore()
val result = reserve(once, silva, eight)
val pair = (result, result)
assertEquals(once.all.size, 1)
val again = InMemoryBookingStore()
val other = (reserve(again, silva, eight), reserve(again, silva, eight))
assertEquals(again.all.size, 2)
Both halves build a pair from a reservation for the Silvas. The first half makes the call once, gives the result a name and uses the name twice. The second writes the call out twice. If the expression were silva.size, naming it once or writing it twice would give the same program. With reserve the two are different programs: one store ends up with one booking and the other with two.
As well as working out a value, reserve changes the store. Chapter 4 used the term side effect for the printing a loop does. A change to the store is one too. Once a method has side effects, a call to it can’t be moved, named, repeated or dropped without asking what else would change. Before we can read a line that calls such a method, we have to know what the method goes on to do.
One side effect has been slowing the tests down since chapter 6. The Thread.sleep(300) inside reserve stands for a slow database, so every test that calls reserve waits for it. The delay belongs in a store, since it’s the store that plays the database. Delete that line from reserve in availability.scala and add a second store to store.scala that sleeps before it saves:
class SlowStore(delay: Long) extends InMemoryBookingStore:
override def add(booking: Booking): Unit =
Thread.sleep(delay)
super.add(booking)
A SlowStore is an InMemoryBookingStore with a different add. Scala insists on the keyword override there, where Java’s @Override is optional. The new add calls the original through super.add. In lastTable, in main.scala, build the store with SlowStore(300) in place of InMemoryBookingStore(). lastTable still double-books table 6 and takes a second or two longer about it, because seating the regulars goes through the slow store too. No test uses the slow store, so the tests no longer wait.
12.2. A description in place of an action
Suppose reserve returned a description of the reservation to be made, and making it were a separate step. Then naming the description, or writing it twice, would change nothing, because nothing would have happened yet. Create io.scala, with a class for descriptions of that kind:
package fullybooked
class IO[+A](val unsafeRun: () => A):
def map[B](change: A => B): IO[B] =
IO(() => change(unsafeRun()))
def flatMap[B](next: A => IO[B]): IO[B] =
IO(() => next(unsafeRun()).unsafeRun())
object IO:
def delay[A](body: => A): IO[A] = IO(() => body)
def pure[A](value: A): IO[A] = IO(() => value)
def printLine(text: String): IO[Unit] = IO.delay(println(text))
An IO[A] holds a function of no arguments that produces an A. None of the work inside that function is done until someone calls unsafeRun. The plus makes IO covariant, which is safe because an A only ever comes out of it. In the companion, delay takes its parameter by name: it’s written => A, with nothing to the left of the arrow, as the parameter of whenOpen was in chapter 7. The code we hand to delay is stored in the function without being run. A value we already have can be wrapped with pure.
The signatures of map and flatMap are the ones Noted had in chapter 10. Each returns a new IO around a new function, so calling map runs nothing. It builds a bigger description, one that will run this IO and then apply change when somebody calls unsafeRun on it. printLine gives us the first useful one: a println that waits to be run. From here on I’ll call an IO a program, since a program is what it describes.
I’ve used Cats Effect’s names where I could, IO, delay and pure, so that chapter 13 has less to rename. Cats Effect’s method for running an IO is called unsafeRunSync.
Create evening.scala, with the reservation as an IO:
package fullybooked
import java.time.LocalTime
def reserveIO(
store: BookingStore,
party: Party,
time: LocalTime
): IO[Either[BookingError, Booking]] =
IO.delay(reserve(store, party, time))
And add two methods to the end of io.scala, each of which takes a program and returns a bigger one:
def twice[A](io: IO[A]): IO[(A, A)] =
for
first <- io
second <- io
yield (first, second)
def retry[E, A](attempt: IO[Either[E, A]], times: Int): IO[Either[E, A]] =
attempt.flatMap:
case Left(error) if times > 1 => retry(attempt, times - 1)
case result => IO.pure(result)
The for in twice works because IO has a map and a flatMap. Each <- says that when the program runs, it will run the IO on the right of the arrow and give the result the name on the left. Add two tests to the end of IOTests:
test("building an IO does nothing"):
val store = InMemoryBookingStore()
val booking = reserveIO(store, silva, eight)
assertEquals(store.all.size, 0)
booking.unsafeRun()
assertEquals(store.all.size, 1)
test("an IO can be named or written out twice, and it's the same program"):
val named = InMemoryBookingStore()
val booking = reserveIO(named, silva, eight)
twice(booking).unsafeRun()
assertEquals(named.all.size, 2)
val written = InMemoryBookingStore()
val both =
for
first <- reserveIO(written, silva, eight)
second <- reserveIO(written, silva, eight)
yield (first, second)
both.unsafeRun()
assertEquals(written.all.size, 2)
In the first test the store is still empty after the call to reserveIO, and the booking only appears when unsafeRun is called. The second repeats the chapter’s opening test with IO: one half names the reservation and passes the name to twice, and the other writes reserveIO out twice in a for. Both stores end up with two bookings. Run the tests and the three in IOTests pass.
12.3. A program is a value too
Add a bigger program to evening.scala:
def walkInIO(store: BookingStore, party: Party, time: LocalTime): IO[Unit] =
for
_ <- printLine(s"${party.name}, party of ${party.size}, asks for a table at $time")
result <- reserveIO(store, party, time)
_ <- printLine(reply(party.name, result))
yield ()
@main def walkIns(): Unit =
val store = InMemoryBookingStore()
val eight = LocalTime.of(20, 0)
val program =
for
_ <- walkInIO(store, Party("Silva", 2), eight)
_ <- walkInIO(store, Party("Zielinski", 9), eight)
count <- IO.delay(store.all.size)
_ <- printLine(s"$count booking in the store")
yield ()
println("Nothing has happened yet")
program.unsafeRun()
In walkInIO only the middle step has a result that’s needed, so the other two are written _ <-. program runs walkInIO for two parties, then counts the bookings and prints the count. By the time println runs, program exists, though nothing in it has run:
$ scala run . --main-class fullybooked.walkIns
Nothing has happened yet
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
“Nothing has happened yet” is printed first, although its line comes after the whole of program in the source. Both walk-ins and the count are in that value. Nothing happens until the last line of walkIns calls program.unsafeRun(). A whole application can be written like this: the code builds one description, however large, and main runs it once. The place where it’s run is often called the edge of the program. The word unsafe in unsafeRun is there to make any other call to it look out of place.
12.4. What a value can do
The other method we added, retry, takes a program that might fail with a Left and returns a program that makes up to times attempts. Its lambda is written as two cases. The first has an if after its pattern, so it matches a Left only while more attempts are allowed, and it builds a retry with one attempt fewer. Any other result matches the second pattern, a bare name, and is handed back by IO.pure. Add a test for it to the end of IOTests:
test("retry runs an IO again until it gives a Right"):
var calls = 0
val flaky: IO[Either[String, Int]] = IO.delay:
calls = calls + 1
if calls < 3 then Left("not yet") else Right(calls)
assertEquals(retry(flaky, 5).unsafeRun(), Right(3))
In the test, flaky fails twice and then succeeds, so retry(flaky, 5) runs it three times. A retry for a plain method like reserve would need the call passed by name or wrapped in a function. An ordinary argument is worked out once, before the method starts. The result is all the method gets. What retry gets in attempt is the description, which it can run as many times as it needs.
12.5. What ours lacks
Add one more method to io.scala and one more test to IOTests:
def countdown(from: Int): IO[Unit] =
if from == 0 then IO.pure(())
else IO.delay(()).flatMap(_ => countdown(from - 1))
test("a long chain of flatMaps runs out of stack"):
countdown(1000).unsafeRun()
val outcome =
try
countdown(1000000).unsafeRun()
"finished"
catch case error: StackOverflowError => "stack overflow"
assertEquals(outcome, "stack overflow")
The new method, countdown, chains one flatMap for each number. A thousand is fine, but a million ends in a StackOverflowError. The test catches it with a try and catch, whose handler is written as a case. Look at flatMap to see why the stack overflows. Each step calls unsafeRun on the next from inside its own unsafeRun, so a program of a million steps needs a million nested calls. A loop that never ends, such as a server waiting for requests, would be a chain like that with no last step.
An exception thrown inside our IO flies straight out of unsafeRun, since the class has no method for handling it as a value. Everything runs on the calling thread, one step after another, and a program that’s been started can’t be cancelled or given a time limit. Nor does anything make sure that a file or a connection is closed afterwards.
Cats Effect’s IO deals with every one of those, and from the outside it still looks like ours: delay, pure, map, flatMap and for. Chapter 13 deletes io.scala and uses the real one in its place.
12.6. Exercises
Solutions are in the book’s downloadable code, under ch12/exercises.
-
Write
readLine: IO[String]aroundscala.io.StdIn.readLine(), and a program that asks for a name and then thanks the person by name. Run it from a@main. -
Write
after[A, B](first: IO[A], second: IO[B]): IO[B], which runs the first program, ignores its result and runs the second. -
Write
sequence[A](ios: List[IO[A]]): IO[List[A]], which turns a list of programs into one program that produces a list. Test that nothing runs untilunsafeRun. -
Write
timed[A](io: IO[A]): IO[(A, Long)], which gives a program’s result together with how many milliseconds it took. Reading the clock is a side effect as well, soSystem.nanoTime()belongs insideIO.delay. -
Write
attempt[A](io: IO[A]): IO[Either[Throwable, A]], which turns an exception thrown while a program runs into aLeft. -
countdown(1000000)overflows the stack when it’s run. Why doesn’t it overflow when it’s built?