CompileOps

Compiles this stream in to a value of the target effect type G and discards any output values of the stream.

To access the output values of the stream, use one of the other compilation methods -- e.g., fold, toVector, etc.

Compiles this stream in to a value of the target effect type G by folding the output chunks together, starting with the provided init and combining the current value with each output chunk.

When this method has returned, the stream has not begun execution -- this method simply compiles the stream down to the target effect type.

Compiles this stream in to a value of the target effect type G, returning None if the stream emitted no values and returning the last value emitted wrapped in Some if values were emitted.

When this method has returned, the stream has not begun execution -- this method simply compiles the stream down to the target effect type.

Compiles this stream in to a value of the target effect type G, raising a NoSuchElementException if the stream emitted no values and returning the last value emitted otherwise.

When this method has returned, the stream has not begun execution -- this method simply compiles the stream down to the target effect type.

Compiles this stream in to a value of the target effect type G, raising a NoSuchElementException if the stream emitted no values, IllegalStateException if the stream emits more than one value and returning the only value emitted otherwise. Note that the stream execution will not short-circuit once it emits more than one element, it will still be evaluated to its end before raising the exception.

When this method has returned, the stream has not begun execution -- this method simply compiles the stream down to the target effect type.

Gives access to the whole compilation api, where the result is expressed as a cats.effect.Resource, instead of bare G.

import fs2._
import cats.effect._

val stream = Stream.iterate(0)(_ + 1).take(5).covary[IO]

val s1: Resource[IO, List[Int]] = stream.compile.resource.toList
val s2: Resource[IO, Int] = stream.compile.resource.foldMonoid
val s3: Resource[IO, Option[Int]] = stream.compile.resource.last

And so on for every other method in compile.

The main use case is interacting with Stream methods whose behaviour depends on the Stream lifetime, in cases where you only want to ultimately return a single element.

A typical example of this is concurrent combinators, here is an example with concurrently:

import fs2._
import cats.effect._
import cats.effect.kernel.Ref
import scala.concurrent.duration._

trait StopWatch[F[_]] {
 def elapsedSeconds: F[Int]
}
object StopWatch {
 def create[F[_]](implicit F: Temporal[F]): Stream[F, StopWatch[F]] =
   Stream.eval(F.ref(0)).flatMap { c =>
     val api = new StopWatch[F] {
       def elapsedSeconds: F[Int] = c.get
     }

     val process = Stream.fixedRate(1.second).evalMap(_ => c.update(_ + 1))

     Stream.emit(api).concurrently(process)
 }
}

This creates a simple abstraction that can be queried by multiple consumers to find out how much time has passed, with a concurrent stream to update it every second.

Note that create returns a Stream[F, StopWatch[F]], even though there is only one instance being emitted: this is less than ideal, so we might think about returning an F[StopWatch[F]] with the following code

StopWatch.create[F].compile.lastOrError

but it does not work: the returned F terminates the lifetime of the stream, which causes concurrently to stop the process stream. As a result, elapsedSeconds never gets updated.

Alternatively, we could implement StopWatch in F only using Fiber.start, but this is not ideal either: concurrently already handles errors, interruption and stopping the producer stream once the consumer lifetime is over, and we don't want to reimplement the machinery for that.

So basically what we need is a type that expresses the concept of lifetime, while only ever emitting a single element, which is exactly what cats.effect.Resource does.

What compile.resource provides is the ability to do this:

object StopWatch {
 // ... def create as before ...

 def betterCreate[F[_]: Temporal]: Resource[F, StopWatch[F]] =
   create.compile.resource.lastOrError
}

This works for every other compile. method, although it's a very natural fit with lastOrError.

Compiles this stream into a value of the target effect type G by collecting all of the output values in a collection.

Collection building is done via an explicitly passed Collector. Standard library collections have collector instances, allowing syntax like: s.compile.to(List) or s.compile.to(Array) or s.compile.to(Map).

A collector is provided for scodec.bits.ByteVector, providing efficient byte vector construction from a stream of bytes: s.compile.to(ByteVector).

When this method has returned, the stream has not begun execution -- this method simply compiles the stream down to the target effect type.

Compiles this stream in to a value of the target effect type G by logging the output values to a List. Equivalent to to[List].

When this method has returned, the stream has not begun execution -- this method simply compiles the stream down to the target effect type.

Compiles this stream in to a value of the target effect type G by logging the output values to a Vector. Equivalent to to[Vector].

When this method has returned, the stream has not begun execution -- this method simply compiles the stream down to the target effect type.