monix.tail
Type members
Classlikes
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 arest
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'sIterable
, along with therest
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'sIterator
, along with therest
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 onNext(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
.
- Type Params
- A
is the type of the elements produced by this Iterant
- F
is the data type that controls evaluation; note that it must be stack-safe in its
map
andflatMap
operations
- Companion
- object
IterantBuilders.Apply is a set of builders for Iterant
returned
by Iterant.apply
IterantBuilders.Apply is a set of builders for Iterant
returned
by Iterant.apply
This is used to achieve the Partially-Applied Type technique.
So instead of having to do:
import monix.eval.Task
Iterant.pure[Task, Int](1)
You can do:
Iterant[Task].pure(1)