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 (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:
- 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.
- 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 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: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
- class IterantBuilders [F[_]] extends AnyRef
Value Members
-
object
Iterant
extends IterantInstances with Serializable
Defines the standard Iterant builders.
- object IterantBuilders
-
object
IterantOfCoeval
extends IterantBuilders[Coeval]
Defines builders for Iterant instances powered by Coeval.
-
object
IterantOfTask
extends IterantBuilders[Task]
Defines builders for Iterant instances powered by Task.