The Iterant is a type that describes lazy, possibly asynchronous
streaming of elements.
The Iterant is a type that describes lazy, possibly asynchronous
streaming of elements.
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 Task, 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.
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 Task, in which case the streaming can have
asynchronous behavior, or you can use 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
The
Iterant
is a type that describes lazy, possibly asynchronous streaming of elements.It is similar somewhat in spirit to Scala's own
collection.immutable.Stream
and with Java'sIterable
, except that it is more composable and more flexible due to evaluation being controlled by anF[_]
monadic type that you have to supply (like Task, Coeval orcats.effect.IO
) which will control the evaluation. In other words, thisIterant
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 standardList
orIterable
.The type is an ADT, meaning a composite of the following types:
head
and arest
representing the rest of the streamNext
for signaling a whole batch of elements by means of a Batch, a type that's similar with Scala'sIterable
, along with therest
of the stream.Next
for signaling a whole strict batch of elements as a traversable BatchCursor, a type that's similar with Scala'sIterator
, along with therest
of the stream.Last(item)
as an optimisation onNext(item, F.pure(Halt(None)), F.unit)
.Parametric Polymorphism
The
Iterant
type accepts as type parameter anF
monadic type that is used to control how evaluation happens. For example you can use Task, in which case the streaming can have asynchronous behavior, or you can use Coeval in which case it can behave like a normal, synchronousIterable
.As restriction, this
F[_]
type used should be stack safe inmap
andflatMap
, otherwise you might get stack-overflow exceptions. This is why in general the type class required forF
iscats.effect.Sync
.When building instances, type
F[_]
which handles the evaluation needs to be specified upfront. Example:You'll usually pick between
Task
,Coeval
orIO
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 theIteratee
orIAsyncEnumerable
.is the data type that controls evaluation; note that it must be stack-safe in its
map
andflatMap
operationsis the type of the elements produced by this Iterant