Packages

sealed abstract class Pull[+F[_], +O, +R] extends AnyRef

A purely functional data structure that describes a process. This process may evaluate actions in an effect type F, emit any number of output values of type O (or None), and may a) terminate with a single result of type R; or b) terminate abnormally by raising (inside the effect F) an exception, or c) terminate because it was cancelled by another process, or d) not terminate.

Like types from other effect libraries, pulls are pure and immutable values. They preserve referential transparency.

Chunking

The output values of a pull are emitted not one by one, but in chunks. A Chunk is an immutable sequence with constant-time indexed lookup. For example, a pull p: Pull[F, Byte, R] internally operates and emits Chunk[Byte] values, which can wrap unboxed byte arrays -- avoiding boxing/unboxing costs. The Pull API provides mechanisms for working at both the chunk level and the individual element level. Generally, working at the chunk level will result in better performance but at the cost of more complex implementations

A pull only emits non-empty chunks.

However, chunks are not merely an operational matter of efficiency. Each pull is emitted from a chunk atomically, which is to say, any errors or interruptions in a pull can only happen between chunks, not within a chunk. For instance, if creating a new chunk of values fails (raises an uncaught exception) while creating an intermediate value, then it fails to create the entire chunk and previous values are discarded.

Evaluation

Like other functional effect types (e.g. cats.effect.IO), a pull describes a _process_ or _computation_. It is not a running process nor a handle for the result of a spawned, running process, like scala.concurrent.Future.

A pull can be converted to a stream and then compiled to an effectful value. For a Pull[F, O, Unit], the result of compilation is a combination, via the monad instance of F, of all the actions in the effect F present in the pull. The result of that F action is the result of combining the outputs emitted by the pull, in the order it emits them, using a _fold_ function. Depending on that function, outputs may be collected into a list (or vector or array or ...), combined together into a single value, or just discarded altogether (by _draining_ the pull).

Compilation is pull-based, rather than push-based (hence the name of the datatype). It is the compilation process itself, that determines when the evaluation of each single effect can proceed or is held back. Effects and outputs later in the pull are not performed or emitted, _unless and until_ the compilation calls for them.

Resource scoping

The effects in a Pull may operate on resources, which must be retained during the execution of the pull, may be shared by several pulls, and must be properly finalised when no longer needed, regardless of whether the pull completed successfully or not. A pull tracks its resources using scopes, which register how many pulls are actively using each resource, and finalises resources when no longer used.

Some operations of the Pull API can be used to introduce new resource scopes, or resource boundaries.

Functional typeclasses

The Pull data structure is a "free" implementation of Monad and has an instance for cats.effect.kernel.Sync.

For any types F[_] and O, a Pull[F, O, *] holds the following laws:

  • pure >=> f == f
  • f >=> pure == f
  • (f >=> g) >=> h == f >=> (g >=> h) where f >=> g is defined as a => a flatMap f flatMap g
  • handleErrorWith(raiseError(e))(f) == f(e)
O

The outputs emitted by this Pull. An output type of Nothing means that this pull does not emit any outputs.

R

The type of result returned by this Pull upon successful termination. An output type of Nothing indicates that this pull cannot terminate successfully: it may fail, be cancelled, or never terminate.

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

Value Members

  1. final def !=(arg0: Any): Boolean
    Definition Classes
    AnyRef → Any
  2. final def ##: Int
    Definition Classes
    AnyRef → Any
  3. final def ==(arg0: Any): Boolean
    Definition Classes
    AnyRef → Any
  4. def >>[F2[x] >: F[x], O2 >: O, S](post: => Pull[F2, O2, S]): Pull[F2, O2, S]

    Lazily appends the given post pull, to be run after this pull.

    Lazily appends the given post pull, to be run after this pull.

    - If this pull succeeds, then its result is discarded, the post pull is built, and starts running. The result of post is the result of the composed pull.

    - If this pull raises an error or is interrupted, the post argument is not evaluated and the composed pull ends just as this pull did.

    In both cases, the effectful actions and outputs of the appended pull consists of those outputs and actions from the first pull, followed by those from the post pull, in the same order as they would come out of each pull.

    Since the post argument is lazy, this method can be used to build lazy pulls, which are not built in memory until after the prefix has run. This allows defining pulls recursively.

    This operation does not add or remove any resource scope boundaries. The post pull runs on the same scope in which this pull ended. The composed pull ends on whatever scope the post pull does.

    This is equivalent to .flatMap(_ => post)

  5. def as[S](s: S): Pull[F, O, S]

    Replaces the result of this pull with the given constant value.

    Replaces the result of this pull with the given constant value. If this pull succeeds, then its result is discarded and the resulting pull succeeds with the s value as its result. Otherwise, if this pull fails or is interrupted, then the result pull ends the same way.

    Alias for _.map(_ => o2).

    S

    The type of the constant,

    s

    The new result value of the pull

  6. final def asInstanceOf[T0]: T0
    Definition Classes
    Any
  7. def attempt: Pull[F, O, Either[Throwable, R]]

    Returns a pull with the result wrapped in Right, or an error wrapped in Left if the pull has raised an error.

    Returns a pull with the result wrapped in Right, or an error wrapped in Left if the pull has raised an error. If this pull is interrupted, the attempted pull ends the same way.

  8. def clone(): AnyRef
    Attributes
    protected[lang]
    Definition Classes
    AnyRef
    Annotations
    @throws(classOf[java.lang.CloneNotSupportedException]) @IntrinsicCandidate() @native()
  9. def covary[F2[x] >: F[x]]: Pull[F2, O, R]

    Short-hand for (this: Pull[F2, O, R]).

    Short-hand for (this: Pull[F2, O, R]). Used to assist with type inference.

  10. def covaryAll[F2[x] >: F[x], O2 >: O, R2 >: R]: Pull[F2, O2, R2]

    Short-hand for (this: Pull[F2, P, S]).

    Short-hand for (this: Pull[F2, P, S]). Used to assist with type inference.

  11. def covaryOutput[O2 >: O]: Pull[F, O2, R]

    Short-hand for (this: Pull[F, O2, R]).

    Short-hand for (this: Pull[F, O2, R]). Used to assist with type inference.

  12. def covaryResult[R2 >: R]: Pull[F, O, R2]

    Short-hand for (this: Pull[F, O, R2]).

    Short-hand for (this: Pull[F, O, R2]). Used to assist with type inference.

  13. final def eq(arg0: AnyRef): Boolean
    Definition Classes
    AnyRef
  14. def equals(arg0: AnyRef): Boolean
    Definition Classes
    AnyRef → Any
  15. def evalMap[F2[x] >: F[x], R2](f: (R) => F2[R2]): Pull[F2, O, R2]

    Alias for flatMap(r => Pull.eval(f(r))).

  16. def flatMap[F2[x] >: F[x], O2 >: O, R2](f: (R) => Pull[F2, O2, R2]): Pull[F2, O2, R2]

    Applies the result of this pull to f and returns the result.

    Applies the result of this pull to f and returns the result.

    This method returns a new composed pull, which will do as follows:

    - If this pull succeeds with a result r of type R, the f function is applied to r, to build a new pull f(r), and the result pull starts running that new pull. The composed pull will terminate (or not) just as the new pull f(r) does. - If this pull fails or is interrupted, then the composed pull terminates with that same failure or interruption. - If evaluating f(r) to build the pull throws an exception, the result is a pull that fails with that exception.

    The composed pull emits all outputs emitted by this pull, and if successful will start emitting the outputs from the generated pull.

    This operation does not modify resource scope boundaries. The generated post pull starts running on the same scope in which this pull ended, and the composed pull will end on the same scope in which post pull does.

  17. final def getClass(): Class[_ <: AnyRef]
    Definition Classes
    AnyRef → Any
    Annotations
    @IntrinsicCandidate() @native()
  18. def handleErrorWith[F2[x] >: F[x], O2 >: O, R2 >: R](handler: (Throwable) => Pull[F2, O2, R2]): Pull[F2, O2, R2]

    Allows to recover from any error raised by the evaluation of this pull.

    Allows to recover from any error raised by the evaluation of this pull. This method returns a composed pull with the following semantics: - If an error occurs, the supplied function is used to build a new handler pull, and it starts running it. However, the pull cannot be resumed from the point at which the error arose. - If no error is raised, the resulting pull just does what this pull does.

  19. def hashCode(): Int
    Definition Classes
    AnyRef → Any
    Annotations
    @IntrinsicCandidate() @native()
  20. final def isInstanceOf[T0]: Boolean
    Definition Classes
    Any
  21. def lease: Pull[F, O, R]

    Leases all resources that are currently open, canceling the lease at the termination of this pull.

  22. def map[S](f: (R) => S): Pull[F, O, S]

    Maps the result of this pull with the f mapping function.

    Maps the result of this pull with the f mapping function.

    If this pull ends in success with a result r, then the function f is applied to its result r, and the image f(r) is the result of the mapped pull. However, if the evaluation of f(r) throws an error, the mapped pull fails with that error.

    Note: for some simple cases of Pull, the map function may be eagerly applied, or discarded, _before_ the pull starts being run.

    If this pull terminates abnormally, so does the mapped pull.

  23. final def ne(arg0: AnyRef): Boolean
    Definition Classes
    AnyRef
  24. final def notify(): Unit
    Definition Classes
    AnyRef
    Annotations
    @IntrinsicCandidate() @native()
  25. final def notifyAll(): Unit
    Definition Classes
    AnyRef
    Annotations
    @IntrinsicCandidate() @native()
  26. def onComplete[F2[x] >: F[x], O2 >: O, R2](post: => Pull[F2, O2, R2]): Pull[F2, O2, R2]

    Run post after this, regardless of errors during this:

    Run post after this, regardless of errors during this:

    - If this pull terminates successfully, then its result is discarded and the post pull is run. However the post pull ends, be it in success, error, interruption, is how the combined pull ends.

    - If this pull fails, the post pull is run next. If the post pull ends, fails, or is interrupted, that is how the combined pull ends. However, if the post pull succeeds, then the combined onComplete pull fails again with the error that was raised from this pull.

    - If this pull is interrupted, then the post pull is never run and the combined pull ends with that same interruption.

  27. final def synchronized[T0](arg0: => T0): T0
    Definition Classes
    AnyRef
  28. def toString(): String
    Definition Classes
    AnyRef → Any
  29. def void: Pull[F, O, Unit]

    Discards the result of this pull.

    Discards the result of this pull.

    If this pull ends in success, its result is discarded and the _voided_ pull returns the unit () value. Otherwise, the voided pull just does the same as this pull does.

    Alias for this.map(_ => ()).

  30. final def wait(arg0: Long, arg1: Int): Unit
    Definition Classes
    AnyRef
    Annotations
    @throws(classOf[java.lang.InterruptedException])
  31. final def wait(arg0: Long): Unit
    Definition Classes
    AnyRef
    Annotations
    @throws(classOf[java.lang.InterruptedException]) @native()
  32. final def wait(): Unit
    Definition Classes
    AnyRef
    Annotations
    @throws(classOf[java.lang.InterruptedException])

Deprecated Value Members

  1. def finalize(): Unit
    Attributes
    protected[lang]
    Definition Classes
    AnyRef
    Annotations
    @throws(classOf[java.lang.Throwable]) @Deprecated
    Deprecated

    (Since version 9)

Inherited from AnyRef

Inherited from Any

Ungrouped