Type Members

1.  sealed abstract class Iterant[F[_], A] extends Product with Serializable

   The Iterant is a type that describes lazy, possibly asynchronous streaming of elements using a pull-based protocol.

   The Iterant is a type that describes lazy, possibly asynchronous streaming of elements using a pull-based protocol.

   It is similar somewhat in spirit to Scala's own collection.immutable.Stream and with Java's Iterable, except that it is more composable and more flexible due to evaluation being controlled by an F[_] monadic type that you have to supply (like monix.eval.Task, monix.eval.Coeval or cats.effect.IO) which will control the evaluation. In other words, this Iterant type is capable of strict or lazy, synchronous or asynchronous evaluation.

   Consumption of an Iterant happens typically in a loop where the current step represents either a signal that the stream is over, or a (head, rest) pair, very similar in spirit to Scala's standard List or Iterable.

   The type is an ADT, meaning a composite of the following types:

   • Next which signals a single strict element, the head and a rest representing the rest of the stream
   • NextBatch is a variation on Next for signaling a whole batch of elements by means of a Batch, a type that's similar with Scala's Iterable, along with the rest of the stream.
   • NextCursor is a variation on Next for signaling a whole strict batch of elements as a traversable BatchCursor, a type that's similar with Scala's Iterator, along with the rest of the stream.
   • Suspend is for suspending the evaluation of a stream.
   • Concat represents the concatenation of two streams.
   • Scope is to specify the acquisition and release of resources. It is effectively the encoding of Bracket.
   • Halt represents an empty stream, signaling the end, either in success or in error.
   • Last represents a one-element stream, where Last(item) as an optimisation on Next(item, F.pure(Halt(None)), F.unit).

   Parametric Polymorphism

   The Iterant type accepts as type parameter an F monadic type that is used to control how evaluation happens. For example you can use monix.eval.Task, in which case the streaming can have asynchronous behavior, or you can use monix.eval.Coeval in which case it can behave like a normal, synchronous Iterable.

   As restriction, this F[_] type used should be stack safe in map and flatMap, otherwise you might get stack-overflow exceptions. This is why in general the type class required for F is cats.effect.Sync.

   When building instances, type F[_] which handles the evaluation needs to be specified upfront. Example:

   import cats.effect.IO
   import monix.eval.{Task, Coeval}
   
   // Builds an Iterant powered by Monix's Task
   Iterant[Task].of(1, 2, 3)
   
   // Builds an Iterant powered by Monix's Coeval
   Iterant[Coeval].of(1, 2, 3)
   
   // Builds an Iterant powered by Cats's IO
   Iterant[IO].of(1, 2, 3)

   You'll usually pick between Task, Coeval or IO for your needs.

   Attribution

   This type was inspired by the Streaming type in the Typelevel Cats library (later moved to Dogs), originally committed in Cats by Erik Osheim. It was also inspired by other push-based streaming abstractions, like the Iteratee or IAsyncEnumerable.

   F

   is the data type that controls evaluation; note that it must be stack-safe in its map and flatMap operations

   A

   is the type of the elements produced by this Iterant