fs2
package fs2
- Source
- fs2.scala
- Alphabetic
- By Inheritance
- fs2
- AnyRef
- Any
- Hide All
- Show All
- Public
- All
Type Members
-
trait
Chunk
[+A] extends AnyRef
A strict, in-memory sequence of
A
values.A strict, in-memory sequence of
A
values.Chunks can be constructed via various constructor methods on the
Chunk
companion object.Chunks are internally specialized for both single element chunks and unboxed arrays of primitives.
Supports unboxed operations for booleans, bytes, longs, and doubles, using a
Chunk
implementation that is backed by an array of primitives. When possible, operations onChunk
preserves unboxed-ness. To get access the underlying unboxed arrays, usetoBooleans
,toBytes
,toLongs
, andtoDoubles
.Note: the NonEmptyChunk type is a subtype of
Chunk
which is limited to chunks with at least one element. -
final
class
Handle
[+F[_], +A] extends AnyRef
A currently open
Stream[F,A]
which allows chunks to be pulled or pushed.A currently open
Stream[F,A]
which allows chunks to be pulled or pushed.To get a handle from a stream, use Stream.open.
-
sealed
trait
NonEmptyChunk
[+A] extends Chunk[A]
A chunk which has at least one element.
-
type
Pipe[F[_], -I, +O] = (Stream[F, I]) ⇒ Stream[F, O]
A stream transformation represented as a function from stream to stream.
A stream transformation represented as a function from stream to stream.
Pipes are typically applied with the
through
operation onStream
. -
type
Pipe2[F[_], -I, -I2, +O] = (Stream[F, I], Stream[F, I2]) ⇒ Stream[F, O]
A stream transformation that combines two streams in to a single stream, represented as a function from two streams to a single stream.
A stream transformation that combines two streams in to a single stream, represented as a function from two streams to a single stream.
Pipe2
s are typically applied with thethrough2
operation onStream
. -
final
class
Pull
[+F[_], +O, +R] extends AnyRef
Allows acquiring elements from a stream in a resource safe way, emitting elements of type
O
, working with a resource of typeR
, and evaluating effects of typeF
.Allows acquiring elements from a stream in a resource safe way, emitting elements of type
O
, working with a resource of typeR
, and evaluating effects of typeF
.Laws:
or
forms a monoid in conjunction withdone
:or(done, p) == p
andor(p, done) == p
.or(or(p1,p2), p3) == or(p1, or(p2,p3))
fail
is caught byonError
:onError(fail(e))(f) == f(e)
Pull
forms a monad withpure
andflatMap
:pure >=> f == f
f >=> pure == f
(f >=> g) >=> h == f >=> (g >=> h)
wheref >=> g
is defined asa => a flatMap f flatMap g
-
sealed
trait
Pure
[+A] extends AnyRef
Indicates that a stream evaluates no effects.
Indicates that a stream evaluates no effects.
A
Stream[Pure,O]
can be safely cast to aStream[Nothing,O]
, butStream[Pure,O]
has better type inference properties in some places. See usage inStream.pull
. -
trait
Scheduler
extends AnyRef
Provides the ability to schedule evaluation of thunks in the future.
-
final
class
Scope
[+F[_], +O] extends AnyRef
Tracks resources acquired while running a stream.
Tracks resources acquired while running a stream.
Note:
Scope
is not typically used directly by user code. -
sealed
trait
ScopedFuture
[F[_], A] extends AnyRef
A future that evaluates to a value of type
A
and aScope[F,Unit]
.A future that evaluates to a value of type
A
and aScope[F,Unit]
.To use a
ScopedFuture
, convert to aPull
(viaf.pull
) or aStream
(viaf.stream
). -
type
Sink[F[_], -I] = (Stream[F, I]) ⇒ Stream[F, Unit]
A pipe that converts a stream to a
Stream[F,Unit]
.A pipe that converts a stream to a
Stream[F,Unit]
.Sinks are typically applied with the
to
operation onStream
. -
trait
Strategy
extends AnyRef
Provides a function for evaluating thunks, possibly asynchronously.
-
final
class
Stream
[+F[_], +O] extends AnyRef
A stream producing output of type
O
and which may evaluateF
effects.A stream producing output of type
O
and which may evaluateF
effects. IfF
isNothing
orfs2.Pure
, the stream is pure.Laws (using infix syntax):
append
forms a monoid in conjunction withempty
:empty append s == s
ands append empty == s
.(s1 append s2) append s3 == s1 append (s2 append s3)
And
push
is consistent with usingappend
to prepend a single chunk:push(c)(s) == chunk(c) append s
fail
propagates until being caught byonError
:fail(e) onError h == h(e)
fail(e) append s == fail(e)
fail(e) flatMap f == fail(e)
Stream
forms a monad withemit
andflatMap
:emit >=> f == f
(left identity)f >=> emit === f
(right identity - note weaker equality notion here)(f >=> g) >=> h == f >=> (g >=> h)
(associativity) whereemit(a)
is defined aschunk(Chunk.singleton(a)) and
f >=> gis defined as
a => a flatMap f flatMap g
The monad is the list-style sequencing monad:
(a append b) flatMap f == (a flatMap f) append (b flatMap f)
empty flatMap f == empty
Technical notes
Note: since the chunk structure of the stream is observable, and
s flatMap (emit)
produces a stream of singleton chunks, the right identity law uses a weaker notion of equality,===
which normalizes both sides with respect to chunk structure:(s1 === s2) = normalize(s1) == normalize(s2)
where==
is full equality (a == b
ifff(a)
is identical tof(b)
for allf
)normalize(s)
can be defined ass.repeatPull(_.echo1)
, which just produces a singly-chunked stream from any input streams
.Note: For efficiency
Stream.map
function operates on an entire chunk at a time and preserves chunk structure, which differs from themap
derived from the monad (s map f == s flatMap (f andThen emit)
) which would produce singleton chunks. In particular, iff
throws errors, the chunked version will fail on the first chunk with an error, while the unchunked version will fail on the first element with an error. Exceptions in pure code like this are strongly discouraged. -
final
class
Task
[+A] extends AnyRef
Trampolined computation producing an
A
that may include asynchronous steps.Trampolined computation producing an
A
that may include asynchronous steps. Arbitrary monadic expressions involvingmap
andflatMap
are guaranteed to use constant stack space. In addition, usingTask.async
, one may construct aTask
from callback-based APIs. This makesTask
useful as a concurrency primitive and as a control structure for wrapping callback-based APIs with a more straightforward, monadic API.Task is also exception-safe. Any exceptions raised during processing may be accessed via the
attempt
method, which converts aTask[A]
to aTask[Attempt[A]]
.Unlike
scala.concurrent.Future
,map
andflatMap
do NOT spawn new tasks and do not require an implicitExecutionContext
. Instead,map
andflatMap
merely add to the current (trampolined) continuation that will be run by the 'current' thread, unless explicitly forked viaTask.start
.Task
also differs fromscala.concurrent.Future
in that it does not represent a _running_ computation. Instead, we reintroduce concurrency _explicitly_ using theTask.start
function. This simplifies our implementation and makes code easier to reason about, since the order of effects and the points of allowed concurrency are made fully explicit and do not depend on Scala's evaluation order.
Value Members
- object Chunk
- object Handle
- object NonEmptyChunk
- object Pull
- object Scheduler
- object Scope
- object ScopedFuture
- object Strategy
- object Stream
- object Task extends TaskPlatform with TaskInstances
-
object
concurrent
Provides utilities for working with streams concurrently.
-
object
pipe
Generic implementations of common pipes.
-
object
pipe2
Generic implementations of common 2-argument pipes.
-
object
text
Provides utilities for working with streams of text (e.g., encoding byte streams to strings).