Iterant
Related Docs:
class Iterant
| package tail
Provides the cats.effect.Sync instance for Iterant.
Provides the cats.effect.Sync instance for Iterant.
The Concat state of the Iterant represents a state that specifies the concatenation of two streams.
The Halt state of the Iterant represents the completion state of a stream, with an optional exception if an error happened.
The Halt state of the Iterant represents the completion state of a stream, with an optional exception if an error happened.
Halt is received as a final state in the iteration process.
This state cannot be followed by any other element and
represents the end of the stream.
is an error to signal at the end of the stream,
or None in case the stream has completed normally
The Last state of the Iterant represents a completion state as an alternative to Halt(None), describing one last element.
The Last state of the Iterant represents a completion state as an alternative to Halt(None), describing one last element.
It is introduced as an optimization, being equivalent to
Next(item, F.pure(Halt(None)), F.unit), to avoid extra processing
in the monadic F[_] and to short-circuit operations such as
concatenation and flatMap.
is the last element being signaled, after which the consumer can stop the iteration
The Next state
of the Iterant represents a item / rest
cons pair, where the head item is a strict value.
The Next state
of the Iterant represents a item / rest
cons pair, where the head item is a strict value.
Note that item being a strict value means that it is
already known, whereas the rest is meant to be lazy and
can have asynchronous behavior as well, depending on the F
type used.
See NextCursor for a state where the head is a strict immutable list.
is the current element to be signaled
is the next state in the sequence that will produce the rest of the stream when evaluated
The NextBatch state
of the Iterant represents an batch / rest cons pair,
where batch is an Iterable
type that can generate a whole batch of elements.
The NextBatch state
of the Iterant represents an batch / rest cons pair,
where batch is an Iterable
type that can generate a whole batch of elements.
is a Iterable
type that can generate elements by traversing a collection,
a standard array or any Iterable
is the next state in the sequence that will produce the rest of the stream when evaluated
The NextCursor state
of the Iterant represents an batch / rest cons pair,
where batch is an Iterator
type that can generate a whole batch of elements.
The NextCursor state
of the Iterant represents an batch / rest cons pair,
where batch is an Iterator
type that can generate a whole batch of elements.
Useful for doing buffering, or by giving it an empty iterator, useful to postpone the evaluation of the next element.
is an Iterator type
that can generate elements by traversing a collection, a standard
array or any Iterator
is the next state in the sequence that will produce the rest of the stream when evaluated
The Scope state of the Iterant represents a stream that is able to specify the acquisition and release of a resource, to be used in generating stream events.
The Scope state of the Iterant represents a stream that is able to specify the acquisition and release of a resource, to be used in generating stream events.
Scope is effectively the encoding of
Bracket,
necessary for safe handling of resources. The use
parameter is supposed to trigger a side effectful action
that allocates resources, which are then used via use
and released via close.
Note that this is often used in combination with
Suspend and data types like
cats.effect.concurrent.Ref
in order to communicate the acquired resources between
open, use and close.
is an effect that should allocate necessary
resources to be used in use and released in close
is the stream created via this scope
is an effect that should deallocate
acquired resources via open and that will be executed
no matter what
Builds a stream state equivalent with Iterant.NextCursor.
Builds a stream state equivalent with Iterant.NextCursor.
The Suspend state
of the Iterant represents a suspended stream to be
evaluated in the F context. It is useful to delay the
evaluation of a stream by deferring to F.
is the next state in the sequence that will produce the rest of the stream when evaluated
Implements the
Visitor Pattern
for interpreting the Iterant data structure.
Implements the
Visitor Pattern
for interpreting the Iterant data structure.
This can be used as an alternative to pattern matching and is
used in the implementation of Iterant for performance reasons.
WARN: this being a class instead of a recursive function, it means that it often has to keep "shared state". Keeping shared state is great for performance, but breaks referential transparency, so use with care.
Returns an IterantBuilders instance for the specified F
monadic type that can be used to build Iterant instances.
Returns an IterantBuilders instance for the specified F
monadic type that can be used to build Iterant instances.
Example:
Iterant[Task].range(0, 10)
Provides the cats.effect.Sync instance for Iterant.
Provides the cats.effect.Sync instance for Iterant.
Concatenates list of Iterants into a single stream
Builds a stream state equivalent with Iterant.Concat.
Builds a stream state equivalent with Iterant.Concat.
The Concat state of the Iterant represents a state that specifies the concatenation of two streams.
is the left hand side of the concatenation, to be processed before the right-hand side
is the rest of the stream, to be processed after the left-hand side is
Alias for suspend.
Alias for suspend.
Promote a non-strict value representing a stream to a stream of the same type, effectively delaying its initialisation.
is the by-name parameter that will generate the stream when evaluated
Alias for eval.
Returns an empty stream.
Lifts a non-strict value into the stream context, returning a stream of one element that is lazily evaluated.
Converts any standard Array into a stream.
Converts a Batch into a stream.
Converts a BatchCursor into a stream.
Converts any Scala collection.IndexedSeq into a stream
(e.g.
Converts any Scala collection.IndexedSeq into a stream
(e.g. Vector).
Converts a scala.collection.Iterable into a stream.
Converts a scala.collection.Iterator into a stream.
Converts any Scala collection.immutable.LinearSeq into
a stream.
Given an org.reactivestreams.Publisher, converts it into an Iterant.
Given an org.reactivestreams.Publisher, converts it into an Iterant.
is the org.reactivestreams.Publisher reference to
wrap into an Iterant
a strictly positive number, representing the size
of the buffer used and the number of elements requested on each
cycle when communicating demand, compliant with the
reactive streams specification. If Int.MaxValue is given,
then no back-pressuring logic will be applied (e.g. an unbounded
buffer is used and the source has a license to stream as many
events as it wants)
can activate or deactivate the "eager buffer" mode in
which the buffer gets pre-filled before the Iterant's consumer is
ready to process it — this prevents having pauses due to
back-pressuring the Subscription.request(n) calls
Iterant.toReactivePublisher for converting an Iterant to
a reactive publisher.
Converts any scala.collection.Seq into a stream.
Given an initial state and a generator function that produces the
next state and the next element in the sequence, creates an
Iterant that keeps generating NextBatch items produced
by our generator function with default recommendedBatchSize.
Given an initial state and a generator function that produces the
next state and the next element in the sequence, creates an
Iterant that keeps generating NextBatch items produced
by our generator function with default recommendedBatchSize.
Example:
val f = (x: Int) => (x + 1, x * 2) val seed = 1 val stream = Iterant.fromStateAction[Task, Int, Int](f)(seed) // Yields 2, 3, 5, 9 stream.take(5)
fromStateActionL for version supporting F[_]
in result of generator function and seed element
Given an initial state and a generator function that produces the
next state and the next element in the sequence in F[_] context, creates an
Iterant that keeps generating Next items produced by our generator function.
Given an initial state and a generator function that produces the
next state and the next element in the sequence in F[_] context, creates an
Iterant that keeps generating Next items produced by our generator function.
Example:
val f = (x: Int) => F.pure((x + 1, x * 2)) val seed = F.pure(1) val stream = Iterant.fromStateAction[Task, Int, Int](f)(seed) // Yields 2, 3, 5, 9 stream.take(5)
fromStateAction for version without F[_] context which generates NextBatch items
Data constructor for building a Iterant.Halt value.
Data constructor for building a Iterant.Halt value.
The Halt state of the Iterant represents the completion state of a stream, with an optional exception if an error happened.
Halt is received as a final state in the iteration process.
This state cannot be followed by any other element and
represents the end of the stream.
is an error to signal at the end of the stream,
or None in case the stream has completed normally
Creates an iterant that emits auto-incremented natural numbers (longs).
Creates an iterant that
emits auto-incremented natural numbers (longs).
at a fixed rate, as given by the specified period.
The amount of time it takes to process an incoming
value gets subtracted from provided period, thus
created iterant tries to emit events spaced by the
given time interval, regardless of how long further
processing takes
This version of the intervalAtFixedRate allows specifying an
initialDelay before first value is emitted
initial delay before emitting the first value
period between 2 successive emitted values
is the timer implementation used to generate delays and to fetch the current time
Creates an iterant that emits auto-incremented natural numbers (longs).
Creates an iterant that
emits auto-incremented natural numbers (longs).
at a fixed rate, as given by the specified period.
The amount of time it takes to process an incoming
value gets subtracted from provided period, thus
created iterant tries to emit events spaced by the
given time interval, regardless of how long further
processing takes
period between 2 successive emitted values
is the timer implementation used to generate delays and to fetch the current time
Creates an iterant that emits auto-incremented natural numbers (longs) spaced by a given time interval.
Creates an iterant that
emits auto-incremented natural numbers (longs) spaced
by a given time interval. Starts from 0 with no delay,
after which it emits incremented numbers spaced by the
period of time. The given period of time acts as a
fixed delay between successive events.
is the delay to wait before emitting the first event
the time to wait between 2 successive events
is the timer implementation used to generate delays and to fetch the current time
Creates an iterant that emits auto-incremented natural numbers (longs) spaced by a given time interval.
Creates an iterant that
emits auto-incremented natural numbers (longs) spaced
by a given time interval. Starts from 0 with no delay,
after which it emits incremented numbers spaced by the
period of time. The given period of time acts as a
fixed delay between successive events.
Without having an initial delay specified, this overload will immediately emit the first item, without any delays.
the time to wait between 2 successive events
is the timer implementation used to generate delays and to fetch the current time
Builds a stream state equivalent with Iterant.Last.
Builds a stream state equivalent with Iterant.Last.
The Last state of the Iterant represents a completion state as an alternative to Halt(None), describing one last element.
It is introduced as an optimization, being equivalent to
Next(item, F.pure(Halt(None)), F.unit), to avoid extra processing
in the monadic F[_] and to short-circuit operations such as
concatenation and flatMap.
is the last element being signaled, after which the consumer can stop the iteration
Lifts a value from monadic context into the stream context, returning a stream of one element
Returns a stream that never emits any event and never completes.
Data constructor for building a Iterant.NextBatch value.
Data constructor for building a Iterant.NextBatch value.
The NextBatch state
of the Iterant represents an batch / rest cons pair,
where batch is an Iterable
type that can generate a whole batch of elements.
is a Iterable
type that can generate elements by traversing a collection,
a standard array or any Iterable
is the next state in the sequence that will produce the rest of the stream when evaluated
Data constructor for building a Iterant.NextCursor value.
Data constructor for building a Iterant.NextCursor value.
The NextCursor state
of the Iterant represents an batch / rest cons pair,
where batch is an Iterator
type that can generate a whole batch of elements.
Useful for doing buffering, or by giving it an empty iterator, useful to postpone the evaluation of the next element.
is an Iterator type
that can generate elements by traversing a collection, a standard
array or any Iterator
is the next state in the sequence that will produce the rest of the stream when evaluated
Data constructor for building a Iterant.Next value.
Data constructor for building a Iterant.Next value.
The Next state
of the Iterant represents a item / rest
cons pair, where the head item is a strict value.
Note that item being a strict value means that it is
already known, whereas the rest is meant to be lazy and
can have asynchronous behavior as well, depending on the F
type used.
See NextCursor for a state where the head is a strict immutable list.
is the current element to be signaled
is the next state in the sequence that will produce the rest of the stream when evaluated
Lifts a strict value into the stream context, returning a stream of one element.
Alias for now.
Returns an empty stream that ends with an error.
Builds a stream that on evaluation will produce equally spaced values in some integer interval.
Builds a stream that on evaluation will produce equally spaced values in some integer interval.
the start value of the stream
the end value of the stream (exclusive from the stream)
the increment value of the tail (must be positive or negative)
the tail producing values from, from + step, ... up
to, but excluding until
Builds a stream that repeats the items provided in argument.
Builds a stream that repeats the items provided in argument.
It terminates either on error or if the source is empty.
Builds a stream that suspends provided thunk and evaluates it indefinitely on-demand.
Builds a stream that suspends provided thunk and evaluates it indefinitely on-demand.
The stream will only terminate if evaluation throws an exception
Referentially transparent alternative to Iterator.continually
Example: infinite sequence of random numbers
import scala.util.Random val randomInts = Iterant[Coeval].repeatEval(Random.nextInt())
Builds a stream that evaluates provided effectful values indefinitely.
Builds a stream that evaluates provided effectful values indefinitely.
The stream will only terminate if an error is raised in F context
Creates a stream that depends on resource allocated by a monadic value, ensuring the resource is released.
Creates a stream that depends on resource allocated by a monadic value, ensuring the resource is released.
Typical use-cases are working with files or network sockets
Example:
val printer = Iterant.resource { IO(new PrintWriter("./lines.txt")) } { writer => IO(writer.close()) } // Safely use the resource, because the release is // scheduled to happen afterwards val writeLines = printer.flatMap { writer => Iterant[IO] .fromIterator(Iterator.from(1)) .mapEval(i => IO { writer.println(s"Line #$i") }) } // Write 100 numbered lines to the file // closing the writer when finished writeLines.take(100).completeL.unsafeRunSync()
resource to acquire at the start of the stream
function that releases the acquired resource
Creates a stream that depends on resource allocated by a monadic value, ensuring the resource is released.
Creates a stream that depends on resource allocated by a monadic value, ensuring the resource is released.
Typical use-cases are working with files or network sockets
Example:
val printer = Iterant.resource { IO(new PrintWriter("./lines.txt")) } { writer => IO(writer.close()) } // Safely use the resource, because the release is // scheduled to happen afterwards val writeLines = printer.flatMap { writer => Iterant[IO] .fromIterator(Iterator.from(1)) .mapEval(i => IO { writer.println(s"Line #$i") }) } // Write 100 numbered lines to the file // closing the writer when finished writeLines.take(100).completeL.unsafeRunSync()
an effect that acquires an expensive resource
function that releases the acquired resource
Builds a stream state equivalent with Iterant.Scope.
Builds a stream state equivalent with Iterant.Scope.
The Scope state of the Iterant represents a stream that is able to specify the acquisition and release of a resource, to be used in generating stream events.
Scope is effectively the encoding of
Bracket,
necessary for safe handling of resources. The use
parameter is supposed to trigger a side effectful action
that allocates resources, which are then used via use
and released via close.
Note that this is often used in combination with
Suspend and data types like
cats.effect.concurrent.Ref
in order to communicate the acquired resources between
open, use and close.
is an effect that should allocate necessary
resources to be used in use and released in close
is the stream created via this scope
is an effect that should deallocate
acquired resources via open and that will be executed
no matter what
Defers the stream generation to the underlying evaluation context (e.g.
Defers the stream generation to the underlying evaluation
context (e.g. Task, Coeval, IO, etc), building a reference
equivalent with Iterant.Suspend.
The Suspend state
of the Iterant represents a suspended stream to be
evaluated in the F context. It is useful to delay the
evaluation of a stream by deferring to F.
is the next state in the sequence that will produce the rest of the stream when evaluated
Promote a non-strict value representing a stream to a stream of the same type, effectively delaying its initialisation.
Promote a non-strict value representing a stream to a stream of the same type, effectively delaying its initialisation.
is the by-name parameter that will generate the stream when evaluated
Builds a stream state equivalent with Iterant.NextCursor.
Builds a stream state equivalent with Iterant.NextCursor.
The Suspend state
of the Iterant represents a suspended stream to be
evaluated in the F context. It is useful to delay the
evaluation of a stream by deferring to F.
is the next state in the sequence that will produce the rest of the stream when evaluated
Keeps calling f and concatenating the resulting iterants for
each scala.util.Left event emitted by the source,
concatenating the resulting iterants and generating
events out of scala.util.Right[B] values.
Keeps calling f and concatenating the resulting iterants for
each scala.util.Left event emitted by the source,
concatenating the resulting iterants and generating
events out of scala.util.Right[B] values.
Based on Phil Freeman's Stack Safety for Free.
Defines the standard Iterant builders.