cats.effect

Represents the exit code of an application.

code is constrained to a range from 0 to 255, inclusive.

A pure abstraction representing the intention to perform a side effect, where the result of that side effect may be obtained synchronously (via return) or asynchronously (via callback).

IO values are pure, immutable values and thus preserve referential transparency, being usable in functional programming. An IO is a data structure that represents just a description of a side effectful computation.

IO can describe synchronous or asynchronous computations that:

1. on evaluation yield exactly one result
2. can end in either success or failure and in case of failure flatMap chains get short-circuited (IO implementing the algebra of MonadError)
3. can be canceled, but note this capability relies on the user to provide cancelation logic

Effects described via this abstraction are not evaluated until the "end of the world", which is to say, when one of the "unsafe" methods are used. Effectful results are not memoized, meaning that memory overhead is minimal (and no leaks), and also that a single effect may be run multiple times in a referentially-transparent manner. For example:

val ioa = IO.println("hey!")

val program = for {
 _ <- ioa
 _ <- ioa
} yield ()

program.unsafeRunSync()

The above will print "hey!" twice, as the effect will be re-run each time it is sequenced in the monadic chain.

IO is trampolined in its flatMap evaluation. This means that you can safely call flatMap in a recursive function of arbitrary depth, without fear of blowing the stack.

def fib(n: Int, a: Long = 0, b: Long = 1): IO[Long] =
 IO.pure(a + b) flatMap { b2 =>
   if (n > 0)
     fib(n - 1, b, b2)
   else
     IO.pure(a)
 }

A pure abstraction representing the intention to perform a side effect, where the result of that side effect is obtained synchronously.

SyncIO is similar to IO, but does not support asynchronous computations. Consequently, a SyncIO can be run synchronously to obtain a result via unsafeRunSync. This is unlike IO#unsafeRunSync, which cannot be safely called in general -- doing so on the JVM blocks the calling thread while the async part of the computation is run and doing so on Scala.js throws an exception upon encountering an async boundary.