Packages

p

fs2

package fs2

Source
fs2.scala
Linear Supertypes
AnyRef, Any
Ordering
  1. Alphabetic
  2. By Inheritance
Inherited
  1. fs2
  2. AnyRef
  3. Any
  1. Hide All
  2. Show All
Visibility
  1. Public
  2. Protected

Package Members

  1. package concurrent

    Provides several concurrency primitives.

    Provides several concurrency primitives. *

Type Members

  1. abstract class Chunk[+O] extends Serializable with ChunkPlatform[O]

    Strict, finite sequence of values that allows index-based random access of elements.

    Strict, finite sequence of values that allows index-based random access of elements.

    Chunks can be created from a variety of collection types using methods on the Chunk companion (e.g., Chunk.vector, Chunk.seq, Chunk.array). Additionally, the Chunk companion defines a subtype of Chunk for each primitive type, using an unboxed primitive array. To work with unboxed arrays, use methods like toBytes to convert a Chunk[Byte] to a Chunk.Bytes and then access the array directly.

    The operations on Chunk are all defined strictly. For example, c.map(f).map(g).map(h) results in intermediate chunks being created (1 per call to map).

  2. trait Collector[-A] extends AnyRef

    Supports building a result of type Out from zero or more Chunk[A].

    Supports building a result of type Out from zero or more Chunk[A].

    This is similar to the standard library collection builders but optimized for building a collection from a stream.

    The companion object provides implicit conversions (methods starting with supports), which adapts various collections to the Collector trait.

  3. trait CollectorK[+C[_]] extends AnyRef

    Mixin trait for companions of collections that can build a C[A] for all A.

  4. final class CompositeFailure extends Throwable

    Represents multiple (>1) exceptions were thrown.

  5. sealed trait Fallible[A] extends AnyRef

    Indicates that a stream evaluates no effects but unlike Pure, may raise errors.

    Indicates that a stream evaluates no effects but unlike Pure, may raise errors.

    Uninhabited.

    A Stream[Fallible,O] can be safely converted to a Stream[F,O] for all F via s.lift[F], provided an ApplicativeError[F, Throwable] is available.

  6. sealed trait Hotswap[F[_], R] extends AnyRef

    Supports treating a linear sequence of resources as a single resource.

    Supports treating a linear sequence of resources as a single resource.

    A Hotswap[F, R] instance is created as a Resource and hence, has a lifetime that is scoped by the Resource. After creation, a Resource[F, R] can be swapped in to the Hotswap by calling swap. The acquired resource is returned and is finalized when the Hotswap is finalized or upon the next call to swap, whichever occurs first.

    For example, the sequence of three resources r1, r2, r3 are shown in the following diagram:

    >----- swap(r1) ---- swap(r2) ---- swap(r3) ----X
    |        |             |             |          |
    Creation |             |             |          |
            r1 acquired    |             |          |
                          r2 acquired    |          |
                          r1 released   r3 acquired |
                                        r2 released |
                                                   r3 released

    This class is particularly useful when working with pulls that cycle through resources -- e.g., writing bytes to files, rotating files every N bytes or M seconds. Without Hotswap, such pulls leak resources -- on each file rotation, a file handle or at least an internal resource reference accumulates. With Hotswap, the Hotswap instance is the only registered resource and each file is swapped in to the Hotswap.

    Usage typically looks something like:

    Stream.resource(Hotswap(mkResource)).flatMap { case (hotswap, r) =>
      // Use r, call hotswap.swap(mkResource) as necessary
    }

    See fs2.io.file.writeRotate for an example of usage.

  7. abstract type INothing <: Nothing

    Alias for Nothing which works better with type inference.

  8. 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 on Stream.

  9. 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.

    Pipe2s are typically applied with the through2 operation on Stream.

  10. 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 type R, and produces a Stream[F,O] when calling p.stream.

    A p: Pull[F,O,R] reads values from one or more streams, returns a result of type R, and produces a Stream[F,O] when calling p.stream.

    Any resources acquired by p are freed following the call to stream.

    Laws:

    Pull forms a monad in R with pure and flatMap:

    • pure >=> f == f
    • f >=> pure == f
    • (f >=> g) >=> h == f >=> (g >=> h) where f >=> g is defined as a => a flatMap f flatMap g

    raiseError is caught by handleErrorWith:

    • handleErrorWith(raiseError(e))(f) == f(e)
  11. abstract type Pure[A] <: Nothing

    Indicates that a stream evaluates no effects.

    Indicates that a stream evaluates no effects.

    A Stream[Pure,O] can be safely converted to a Stream[F,O] for all F.

  12. trait RaiseThrowable[F[_]] extends AnyRef

    Witnesses that F supports raising throwables.

    Witnesses that F supports raising throwables.

    An instance of RaiseThrowable is available for any F which has an ApplicativeError[F, Throwable] instance. Alternatively, an instance is available for the uninhabited type Fallible.

    Annotations
    @implicitNotFound("Cannot find an implicit value for RaiseThrowable[${F}]: an instance is available for any F which has an ApplicativeError[F, Throwable] instance or for F = Fallible. If getting this error for a non-specific F, try manually supplying the type parameter (e.g., Stream.raiseError[IO](t) instead of Stream.raiseError(t)). If getting this error when working with pure streams, use F = Fallible.")
  13. abstract class Scope[F[_]] extends AnyRef

    Represents a period of stream execution in which resources are acquired and released.

    Represents a period of stream execution in which resources are acquired and released.

    Note: this type is generally used to implement low-level actions that manipulate resource lifetimes and hence, isn't generally used by user-level code.

  14. final class Stream[+F[_], +O] extends AnyVal

    A stream producing output of type O and which may evaluate F effects.

    A stream producing output of type O and which may evaluate F effects.

    - Purely functional a value of type Stream[F, O] _describes_ an effectful computation. A function that returns a Stream[F, O] builds a _description_ of an effectful computation, but does not perform them. The methods of the Stream class derive new descriptions from others. This is similar to how effect types like cats.effect.IO and monix.Task build descriptions of computations.

    - Pull: to evaluate a stream, a consumer pulls its values from it, by repeatedly performing one pull step at a time. Each step is a F-effectful computation that may yield some O values (or none), and a stream from which to continue pulling. The consumer controls the evaluation of the stream, which effectful operations are performed, and when.

    - Non-Strict: stream evaluation only pulls from the stream a prefix large enough to compute its results. Thus, although a stream may yield an unbounded number of values or, after successfully yielding several values, either raise an error or hang up and never yield any value, the consumer need not reach those points of failure. For the same reason, in general, no effect in F is evaluated unless and until the consumer needs it.

    - Abstract: a stream needs not be a plain finite list of fixed effectful computations in F. It can also represent an input or output connection through which data incrementally arrives. It can represent an effectful computation, such as reading the system's time, that can be re-evaluated as often as the consumer of the stream requires.

    Special properties for streams

    There are some special properties or cases of streams:

    • A stream is finite, or if we can reach the end after a limited number of pull steps, which may yield a finite number of values. It is empty if it terminates and yields no values.
    • A singleton stream is a stream that ends after yielding one single value.
    • A pure stream is one in which the F is Pure, which indicates that it evaluates no effects.
    • A never stream is a stream that never terminates and never yields any value.

    Pure Streams and operations

    We can sometimes think of streams, naively, as lists of O elements with F-effects. This is particularly true for pure streams, which are instances of Stream which use the Pure effect type. We can convert every pure and finite stream into a List[O] using the .toList method. Also, we can convert pure infinite streams into instances of the Stream[O] class from the Scala standard library.

    A method of the Stream class is pure if it can be applied to pure streams. Such methods are identified in that their signature includes no type-class constraint (or implicit parameter) on the F method. Pure methods in Stream[F, O] can be projected naturally to methods in the List class, which means that we can applying the stream's method and converting the result to a list gets the same result as first converting the stream to a list, and then applying list methods.

    Some methods that project directly to list are map, filter, takeWhile, etc. There are other methods, like exists or find, that in the List class they return a value or an Option, but their stream counterparts return an (either empty or singleton) stream. Other methods, like zipWithPrevious, have a more complicated but still pure translation to list methods.

    Type-Class instances and laws of the Stream Operations

    Laws (using infix syntax):

    append forms a monoid in conjunction with empty:

    • empty append s == s and s append empty == s.
    • (s1 append s2) append s3 == s1 append (s2 append s3)

    And cons is consistent with using ++ to prepend a single chunk:

    • s.cons(c) == Stream.chunk(c) ++ s

    Stream.raiseError propagates until being caught by handleErrorWith:

    • Stream.raiseError(e) handleErrorWith h == h(e)
    • Stream.raiseError(e) ++ s == Stream.raiseError(e)
    • Stream.raiseError(e) flatMap f == Stream.raiseError(e)

    Stream forms a monad with emit and flatMap:

    • Stream.emit >=> f == f (left identity)
    • f >=> Stream.emit === f (right identity - note weaker equality notion here)
    • (f >=> g) >=> h == f >=> (g >=> h) (associativity) where Stream.emit(a) is defined as chunk(Chunk.singleton(a)) and f >=> g is 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 chunk structure of the stream is observable, and s flatMap Stream.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 iff f(a) is identical to f(b) for all f)

    normalize(s) can be defined as s.flatMap(Stream.emit), which just produces a singly-chunked stream from any input stream s.

    For instance, for a stream s and a function f: A => B, - the result of s.map(f) is a Stream with the same _chunking_ as the s; wheras... - the result of s.flatMap(x => S.emit(f(x))) is a Stream structured as a sequence of singleton chunks. The latter is using the definition of map that is derived from the Monad instance.

    This is not unlike equality for maps or sets, which is defined by which elements they contain, not by how these are spread between a tree's branches or a hashtable buckets. However, a Stream structure can be _observed_ through the chunks method, so two streams "_equal_" under that notion may give different results through this method.

    Note: For efficiency Stream.map function operates on an entire chunk at a time and preserves chunk structure, which differs from the map derived from the monad (s map f == s flatMap (f andThen Stream.emit)) which would produce singleton chunk. In particular, if f 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.

Deprecated Type Members

  1. 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 on Stream.

    Annotations
    @deprecated
    Deprecated

    (Since version 1.0.2) Use Pipe[F, I, Unit] instead

Value Members

  1. object Chunk extends CollectorK[Chunk] with ChunkCompanionPlatform with Serializable
  2. object Collector extends CollectorPlatform
  3. object CollectorK
  4. object CompositeFailure extends Serializable
  5. object Fallible
  6. object Hotswap
  7. object Pipe
  8. object Pull extends PullLowPriority
  9. object RaiseThrowable
  10. object Scope
  11. object Stream extends StreamLowPriority
  12. object compression

    Provides utilities for compressing/decompressing byte streams.

  13. object hash

    Provides various cryptographic hashes as pipes.

  14. object text

    Provides utilities for working with streams of text (e.g., encoding byte streams to strings).

Deprecated Value Members

  1. object Sink

    Companion for Sink.

    Companion for Sink.

    Annotations
    @deprecated
    Deprecated

    (Since version 1.0.2) Use Pipe instead

  2. object compress

    Provides utilities for compressing/decompressing byte streams.

    Provides utilities for compressing/decompressing byte streams.

    Annotations
    @deprecated
    Deprecated

    (Since version 2.3.0) Use fs2.compression instead

Inherited from AnyRef

Inherited from Any

Ungrouped