A FunctionIO[E, A, B] is an effectful function from A to B, which might fail with an E.

This is the moral equivalent of A => IO[E, B], and, indeed, FunctionIO extends this function type, and can be used in the same way.

The main advantage to using FunctionIO is that it provides you a means of importing an impure function A => B into FunctionIO[E, A, B], without actually wrapping the result of the function in an IO value.

This allows the implementation to aggressively fuse operations on impure functions, which in turn can result in significantly higher-performance and far less heap utilization than equivalent approaches modeled with IO.

The implementation allows you to lift functions from A => IO[E, B] into a FunctionIO[E, A, B]. Such functions cannot be optimized, but will be handled correctly and can work in conjunction with optimized (fused) FunctionIO.

Those interested in learning more about modeling effects with FunctionIO are encouraged to read John Hughes paper on the subject: Generalizing Monads to Arrows (www.cse.chalmers.se/~rjmh/Papers/arrows.pdf). The implementation in this file contains many of the same combinators as Hughes implementation.

A word of warning: while even very complex code can be expressed in FunctionIO, there is a point of diminishing return. If you find yourself using deeply nested tuples to propagate information forward, it may be no faster than using IO.

Given the following two FunctionIO:

val readLine = FunctionIO.impureVoid((_ : Unit) => scala.Console.readLine())
val printLine = FunctionIO.impureVoid((line: String) => println(line))

Then the following two programs are equivalent:

// Program 1
val program1: UIO[Unit] =
  for {
    name <- getStrLn
    _    <- putStrLn("Hello, " + name)
  } yield ())

// Program 2
val program2: UIO[Unit] = (readLine >>> FunctionIO.fromFunction("Hello, " + _) >>> printLine)(())

Similarly, the following two programs are equivalent:

// Program 1
val program1: UIO[Unit] =
  for {
    line1 <- getStrLn
    line2 <- getStrLn
    _     <- putStrLn("You wrote: " + line1 + ", " + line2)
  } yield ())

// Program 2
val program2: UIO[Unit] =
  (readLine.zipWith(readLine)("You wrote: " + _ + ", " + _) >>> printLine)(())

In both of these examples, the FunctionIO program is faster because it is able to perform fusion of effectful functions.