The Iterant
is a type that describes lazy, possibly asynchronous
streaming of elements using a pull-based protocol.
Defines the standard Iterant builders.
Defines builders for Iterant instances powered by Coeval.
Defines builders for Iterant instances powered by Task.
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'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