fs2
package fs2
- Source
- fs2.scala
- Alphabetic
- By Inheritance
- fs2
- AnyRef
- Any
- Hide All
- Show All
- Public
- All
Type Members
-
sealed abstract
class
AsyncPull
[F[_], A] extends AnyRef
Result of
unconsAsync
.Result of
unconsAsync
. Conceptually similar to aFuture
. Can be forced viapull
orstream
. -
sealed abstract
class
Catenable
[+A] extends AnyRef
Trivial catenable sequence.
Trivial catenable sequence. Supports O(1) append, and (amortized) O(1)
uncons
, such that walking the sequence via N successiveuncons
steps takes O(N). Like a difference list, conversion to aSeq[A]
takes linear time, regardless of how the sequence is built up. -
abstract
class
Chunk
[+O] extends Segment[O, Unit]
Segment with a known size and that allows index-based random access of elements.
Segment with a known size and that allows index-based random access of elements.
Chunk
s can be created for a variety of collection types using methods on theChunk
companion (e.g.,Chunk.vector
,Chunk.seq
,Chunk.array
). Additionally, theChunk
companion defines a subtype ofChunk
for each primitive type, using an unboxed primitive array. To work with unboxed arrays, use methods liketoBytes
to convert aChunk[Byte]
to aChunk.Bytes
and then access the array directly.This type intentionally has a very limited API. Most operations are defined on
Segment
in a lazy/fusable fashion. In general, better performance comes from fusing as many operations as possible. As such, the chunk API is minimal, to encourage use of the fusable operations.Some operations have a lazy/fusable definition (on
Segment
) and a strict definition onChunk
. To call such operations, use the.strict
method -- e.g.,c.strict.splitAt(3)
. -
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 AnyVal
A
p: Pull[F,O,R]
reads values from one or more streams, returns a result of typeR
, and produces aStream[F,O]
when callingp.stream
.A
p: Pull[F,O,R]
reads values from one or more streams, returns a result of typeR
, and produces aStream[F,O]
when callingp.stream
.Any resources acquired by
p
are freed following the call tostream
.Much of the API of
Pull
is defined in Pull.InvariantOps.Laws:
Pull
forms a monad inR
withpure
andflatMap
:pure >=> f == f
f >=> pure == f
(f >=> g) >=> h == f >=> (g >=> h)
wheref >=> g
is defined asa => a flatMap f flatMap g
fail
is caught byonError
:onError(fail(e))(f) == f(e)
-
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 converted to aStream[F,O]
for allF
. -
abstract
class
Scheduler
extends AnyRef
Provides the ability to schedule evaluation of thunks in the future.
-
abstract
class
Segment
[+O, +R] extends AnyRef
Potentially infinite, pure sequence of values of type
O
and a result of typeR
.Potentially infinite, pure sequence of values of type
O
and a result of typeR
.All methods which return a
Segment
support fusion with other arbitrary methods that returnSegment
s. This is similar to the staging approach described in Stream Fusion, to Completeness, but without code generation in staging.Stack safety is ensured by tracking a fusion depth. If the depth reaches the limit, the computation is trampolined using
cats.Eval
.The Chunk type is a subtype of Segment that supports efficient index-based random access.
Implementation notes:
- Some operators ask for a segment remainder from within a callback (e.g.,
emits
). As such, segments should update state before invoking callbacks so that remainders can be computed accurately.
- Some operators ask for a segment remainder from within a callback (e.g.,
-
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
. -
final
class
Stream
[+F[_], +O] extends AnyVal
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
is Pure, the stream evaluates no effects.Much of the API of
Stream
is defined in Stream.InvariantOps.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
cons
is consistent with using++
to prepend a single segment:s.cons(seg) == Stream.segment(seg) ++ s
Stream.fail
propagates until being caught byonError
:Stream.fail(e) onError h == h(e)
Stream.fail(e) ++ s == Stream.fail(e)
Stream.fail(e) flatMap f == Stream.fail(e)
Stream
forms a monad withemit
andflatMap
:Stream.emit >=> f == f
(left identity)f >=> Stream.emit === f
(right identity - note weaker equality notion here)(f >=> g) >=> h == f >=> (g >=> h)
(associativity) whereStream.emit(a)
is defined assegment(Segment.singleton(a)) and
f >=> gis defined as
a => a flatMap f flatMap g
The monad is the list-style sequencing monad:
(a ++ b) flatMap f == (a flatMap f) ++ (b flatMap f)
Stream.empty flatMap f == Stream.empty
Technical notes
Note: since the segment structure of the stream is observable, and
s flatMap Stream.emit
produces a stream of singleton segments, the right identity law uses a weaker notion of equality,===
which normalizes both sides with respect to segment 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.flatMap(Stream.emit)
, which just produces a singly-chunked stream from any input streams
.Note: For efficiency
Stream.map
function operates on an entire segment at a time and preserves segment structure, which differs from themap
derived from the monad (s map f == s flatMap (f andThen Stream.emit)
) which would produce singleton segments. In particular, iff
throws errors, the segmented version will fail on the first segment with an error, while the unsegmented version will fail on the first element with an error. Exceptions in pure code like this are strongly discouraged.
Value Members
- object AsyncPull
- object Catenable
- object Chunk
- object Pipe
- object Pipe2
- object Pull
- object Scheduler extends SchedulerPlatform
- object Segment
-
object
Sink
Companion for Sink.
- object Stream
-
object
text
Provides utilities for working with streams of text (e.g., encoding byte streams to strings).