package tail
- Alphabetic
- Public
- All
Type Members
- 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'sIterable
, except that it is more composable and more flexible due to evaluation being controlled by anF[_]
monadic type that you have to supply (likemonix.eval.Task
,monix.eval.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:
- 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 anF
monadic type that is used to control how evaluation happens. For example you can usemonix.eval.Task
, in which case the streaming can have asynchronous behavior, or you can usemonix.eval.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: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
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
.- F
is the data type that controls evaluation; note that it must be stack-safe in its
map
andflatMap
operations- A
is the type of the elements produced by this Iterant
- Next which signals a single strict
element, the
Value Members
- object Iterant extends IterantInstances with Serializable
Defines the standard Iterant builders.
- object IterantBuilders
IterantBuilders.Apply is a set of builders for
Iterant
returned by Iterant.applyIterantBuilders.Apply is a set of builders for
Iterant
returned by Iterant.applyThis 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)
This is the API documentation for the Monix library.
Package Overview
monix.execution exposes lower level primitives for dealing with asynchronous execution:
Atomic
types, as alternative tojava.util.concurrent.atomic
monix.catnap exposes pure abstractions built on top of the Cats-Effect type classes:
monix.eval is for dealing with evaluation of results, thus exposing Task and Coeval.
monix.reactive exposes the
Observable
pattern:Observable
implementationsmonix.tail exposes Iterant for purely functional pull based streaming:
Batch
andBatchCursor
, the alternatives to Scala'sIterable
andIterator
respectively that we are using within Iterant's encodingYou can control evaluation with type you choose - be it Task, Coeval, cats.effect.IO or your own as long as you provide correct cats-effect or cats typeclass instance.