Projection of a Stream
providing various ways to compile a Stream[F,O]
to an F[...]
.
Type class which describes compilation of a Stream[F, O]
to a G[?]
.
Provides syntax for fallible streams.
Provides syntax for pure pipes based on cats.Id
.
Provides syntax for streams that are invariant in F
and O
.
Provides operations on effectful pipes for syntactic convenience.
Provides syntax for pure streams.
Provides operations on pure pipes for syntactic convenience.
Provides operations on pure pipes for syntactic convenience.
When merging multiple streams, this represents step of one leg.
When merging multiple streams, this represents step of one leg.
It is common to uncons
, however unlike uncons
, it keeps track
of stream scope independently of the main scope of the stream.
This assures, that after each next stepLeg
each Stream leg
keeps its scope
when interpreting.
Usual scenarios is to first invoke stream.pull.stepLeg
and then consume whatever is
available in leg.head
. If the next step is required leg.stepLeg
will yield next Leg
.
Once the stream will stop to be interleaved (merged), then stream
allows to return to normal stream
invocation.
Projection of a Stream
providing various ways to get a Pull
from the Stream
.
Provides syntax for streams with effect type Fallible
.
Provides syntax for streams with effect type cats.Id
.
Provides syntax for streams that are invariant in F
and O
.
Provides syntax for pure streams.
Creates a pure stream that emits the supplied values.
Creates a pure stream that emits the supplied values. To convert to an effectful stream, use covary
.
Creates a single element stream that gets its value by evaluating the supplied effect.
Creates a single element stream that gets its value by evaluating the supplied effect. If the effect fails, a Left
is emitted. Otherwise, a Right
is emitted.
Use eval instead if a failure while evaluating the effect should fail the stream.
scala> import cats.effect.IO scala> Stream.attemptEval(IO(10)).compile.toVector.unsafeRunSync res0: Vector[Either[Throwable,Int]] = Vector(Right(10)) scala> Stream.attemptEval(IO(throw new RuntimeException)).compile.toVector.unsafeRunSync res1: Vector[Either[Throwable,Nothing]] = Vector(Left(java.lang.RuntimeException))
Light weight alternative to awakeEvery
that sleeps for duration d
before each pulled element.
Discrete stream that every d
emits elapsed duration
since the start time of stream consumption.
Discrete stream that every d
emits elapsed duration
since the start time of stream consumption.
For example: awakeEvery[IO](5 seconds)
will
return (approximately) 5s, 10s, 15s
, and will lie dormant
between emitted values.
FiniteDuration between emits of the resulting stream
Creates a stream that emits a resource allocated by an effect, ensuring the resource is eventually released regardless of how the stream is used.
Creates a stream that emits a resource allocated by an effect, ensuring the resource is eventually released regardless of how the stream is used.
A typical use case for bracket is working with files or network sockets. The resource effect
opens a file and returns a reference to it. One can then flatMap on the returned Stream to access
the file, e.g to read bytes and transform them in to some stream of elements
(e.g., bytes, strings, lines, etc.).
The release
action then closes the file once the result Stream terminates, even in case of interruption
or errors.
resource to acquire at start of stream
function which returns an effect that releases the resource
Like bracket but the result value consists of a cancellation Stream and the acquired resource.
Like bracket but the result value consists of a cancellation Stream and the acquired resource. Running the cancellation Stream frees the resource. This allows the acquired resource to be released earlier than at the end of the containing Stream scope. Note that this operation is safe: if the cancellation Stream is not run manually, the resource is still guaranteed be release at the end of the containing Stream scope.
Like bracket but the release action is passed an ExitCase[Throwable]
.
Like bracket but the release action is passed an ExitCase[Throwable]
.
ExitCase.Canceled
is passed to the release action in the event of either stream interruption or
overall compiled effect cancelation.
Like bracketCancellable but the release action is passed an ExitCase[Throwable]
.
Like bracketCancellable but the release action is passed an ExitCase[Throwable]
.
ExitCase.Canceled
is passed to the release action in the event of either stream interruption or
overall compiled effect cancelation.
Creates a pure stream that emits the elements of the supplied chunk.
Creates a pure stream that emits the elements of the supplied chunk.
scala> Stream.chunk(Chunk(1,2,3)).toList res0: List[Int] = List(1, 2, 3)
Creates an infinite pure stream that always returns the supplied value.
Creates an infinite pure stream that always returns the supplied value.
Elements are emitted in finite chunks with chunkSize
number of elements.
scala> Stream.constant(0).take(5).toList res0: List[Int] = List(0, 0, 0, 0, 0)
Implicitly covaries a pipe.
A continuous stream of the elapsed time, computed using System.nanoTime
.
A continuous stream of the elapsed time, computed using System.nanoTime
.
Note that the actual granularity of these elapsed times depends on the OS, for instance
the OS may only update the current time every ten milliseconds or so.
Creates a singleton pure stream that emits the supplied value.
Creates a singleton pure stream that emits the supplied value.
scala> Stream.emit(0).toList res0: List[Int] = List(0)
Creates a pure stream that emits the supplied values.
Creates a pure stream that emits the supplied values.
scala> Stream.emits(List(1, 2, 3)).toList res0: List[Int] = List(1, 2, 3)
Empty pure stream.
Creates a single element stream that gets its value by evaluating the supplied effect.
Creates a single element stream that gets its value by evaluating the supplied effect. If the effect fails, the returned stream fails.
Use attemptEval instead if a failure while evaluating the effect should be emitted as a value.
scala> import cats.effect.IO scala> Stream.eval(IO(10)).compile.toVector.unsafeRunSync res0: Vector[Int] = Vector(10) scala> Stream.eval(IO(throw new RuntimeException)).covaryOutput[Int].compile.toVector.attempt.unsafeRunSync res1: Either[Throwable,Vector[Int]] = Left(java.lang.RuntimeException)
like eval
but resulting chunk is flatten efficiently *
Creates a stream that evaluates the supplied fa
for its effect, discarding the output value.
Creates a stream that evaluates the supplied fa
for its effect, discarding the output value.
As a result, the returned stream emits no elements and hence has output type INothing
.
Alias for eval(fa).drain
.
scala> import cats.effect.IO scala> Stream.eval_(IO(println("Ran"))).covaryOutput[Int].compile.toVector.unsafeRunSync res0: Vector[Int] = Vector()
A continuous stream which is true after d, 2d, 3d...
elapsed duration,
and false otherwise.
A continuous stream which is true after d, 2d, 3d...
elapsed duration,
and false otherwise.
If you'd like a 'discrete' stream that will actually block until d
has elapsed,
use awakeEvery
instead.
Light weight alternative to fixedRate that sleeps for duration d
before each pulled element.
Light weight alternative to fixedRate that sleeps for duration d
before each pulled element.
Behavior differs from fixedRate
because the sleep between elements occurs after the next element
is pulled whereas fixedRate
accounts for the time it takes to process the emitted unit.
This difference can roughly be thought of as the difference between scheduleWithFixedDelay
and
scheduleAtFixedRate
in java.util.concurrent.Scheduler
.
Alias for sleep(d).repeat
.
Discrete stream that emits a unit every d
.
Discrete stream that emits a unit every d
.
See fixedDelay for an alternative that sleeps d
between elements.
FiniteDuration between emits of the resulting stream
Lifts an effect that generates a stream in to a stream.
Lifts an effect that generates a stream in to a stream. Alias for eval(f).flatMap(_)
.
scala> import cats.effect.IO scala> Stream.force(IO(Stream(1,2,3).covary[IO])).compile.toVector.unsafeRunSync res0: Vector[Int] = Vector(1, 2, 3)
Lifts an Either[Throwable, A] to an effectful Stream.
Lifts an Either[Throwable, A] to an effectful Stream.
scala> import cats.effect.IO, scala.util.Try scala> Stream.fromEither[IO](Right(42)).compile.toList.unsafeRunSync res0: List[Int] = List(42) scala> Try(Stream.fromEither[IO](Left(new RuntimeException)).compile.toList.unsafeRunSync) res1: Try[List[Nothing]] = Failure(java.lang.RuntimeException)
Lifts an iterator into a Stream
Gets the current scope, allowing manual leasing or interruption.
Gets the current scope, allowing manual leasing or interruption. This is a low-level method and generally should not be used by user code.
An infinite Stream
that repeatedly applies a given function
to a start value.
An infinite Stream
that repeatedly applies a given function
to a start value. start
is the first value emitted, followed
by f(start)
, then f(f(start))
, and so on.
scala> Stream.iterate(0)(_ + 1).take(10).toList res0: List[Int] = List(0, 1, 2, 3, 4, 5, 6, 7, 8, 9)
Like iterate, but takes an effectful function for producing the next state.
Like iterate, but takes an effectful function for producing
the next state. start
is the first value emitted.
scala> import cats.effect.IO scala> Stream.iterateEval(0)(i => IO(i + 1)).take(10).compile.toVector.unsafeRunSync res0: Vector[Int] = Vector(0, 1, 2, 3, 4, 5, 6, 7, 8, 9)
MonadError
instance for Stream
.
MonadError
instance for Stream
.
scala> import cats.implicits._ scala> Stream(1, -2, 3).fproduct(_.abs).toList res0: List[(Int, Int)] = List((1,1), (-2,2), (3,3))
Monoid
instance for Stream
.
A stream that never emits and never terminates.
Creates a stream that, when run, fails with the supplied exception.
Creates a stream that, when run, fails with the supplied exception.
The F
type must be explicitly provided (e.g., via raiseError[IO]
or raiseError[Fallible]
).
scala> import cats.effect.IO scala> Stream.raiseError[Fallible](new RuntimeException).toList res0: Either[Throwable,List[INothing]] = Left(java.lang.RuntimeException) scala> Stream.raiseError[IO](new RuntimeException).covaryOutput[Int].compile.drain.attempt.unsafeRunSync res0: Either[Throwable,Unit] = Left(java.lang.RuntimeException)
Creates a random stream of integers using a random seed.
Creates a random stream of integers using the supplied seed.
Creates a random stream of integers using the supplied seed. Returns a pure stream, as the pseudo random number generator is deterministic based on the supplied seed.
Lazily produce the range [start, stopExclusive)
.
Lazily produce the range [start, stopExclusive)
. If you want to produce
the sequence in one chunk, instead of lazily, use
emits(start until stopExclusive)
.
scala> Stream.range(10, 20, 2).toList res0: List[Int] = List(10, 12, 14, 16, 18)
Lazily produce a sequence of nonoverlapping ranges, where each range
contains size
integers, assuming the upper bound is exclusive.
Lazily produce a sequence of nonoverlapping ranges, where each range
contains size
integers, assuming the upper bound is exclusive.
Example: ranges(0, 1000, 10)
results in the pairs
(0, 10), (10, 20), (20, 30) ... (990, 1000)
Note: The last emitted range may be truncated at stopExclusive
. For
instance, ranges(0,5,4)
results in (0,4), (4,5)
.
scala> Stream.ranges(0, 20, 5).toList res0: List[(Int,Int)] = List((0,5), (5,10), (10,15), (15,20))
IllegalArgumentException
if size
<= 0
Alias for eval(fo).repeat
.
Converts the supplied resource in to a singleton stream.
Retries fo
on failure, returning a singleton stream with the
result of fo
as soon as it succeeds.
Retries fo
on failure, returning a singleton stream with the
result of fo
as soon as it succeeds.
Duration of delay before the first retry
Applied to the previous delay to compute the next, e.g. to implement exponential backoff
Number of attempts before failing with the
latest error, if fo
never succeeds
Function to determine whether a failure is
retriable or not, defaults to retry every
NonFatal
. A failed stream is immediately
returned when a non-retriable failure is
encountered
A single-element Stream
that waits for the duration d
before emitting unit.
A single-element Stream
that waits for the duration d
before emitting unit. This uses the implicit
Timer
to avoid blocking a thread.
Alias for sleep(d).drain
.
Alias for sleep(d).drain
. Often used in conjunction with ++
(i.e., sleep_(..) ++ s
) as a more
performant version of sleep(..) >> s
.
Starts the supplied task and cancels it as finalization of the returned stream.
Returns a stream that evaluates the supplied by-name each time the stream is used, allowing use of a mutable value in stream computations.
Returns a stream that evaluates the supplied by-name each time the stream is used, allowing use of a mutable value in stream computations.
Note: it's generally easier to reason about such computations using effectful
values. That is, allocate the mutable value in an effect and then use
Stream.eval(fa).flatMap { a => ??? }
.
scala> Stream.suspend { | val digest = java.security.MessageDigest.getInstance("SHA-256") | val bytes: Stream[Pure,Byte] = ??? | bytes.chunks.fold(digest) { (d,c) => d.update(c.toBytes.values); d } | }
Creates a stream by successively applying f
until a None
is returned, emitting
each output O
and using each output S
as input to the next invocation of f
.
Creates a stream by successively applying f
until a None
is returned, emitting
each output O
and using each output S
as input to the next invocation of f
.
scala> Stream.unfold(0)(i => if (i < 5) Some(i -> (i+1)) else None).toList res0: List[Int] = List(0, 1, 2, 3, 4)
Like unfold but each invocation of f
provides a chunk of output.
Like unfold but each invocation of f
provides a chunk of output.
scala> Stream.unfoldChunk(0)(i => if (i < 5) Some(Chunk.seq(List.fill(i)(i)) -> (i+1)) else None).toList res0: List[Int] = List(1, 2, 2, 3, 3, 3, 4, 4, 4, 4)
Like unfoldChunk, but takes an effectful function.
Like unfold, but takes an effectful function.