Type Members

1.  trait Evolution[-I, +O, +E] extends AnyRef

   The continuation of a Stage: which stage handles the next input, chosen by the Status of the run that just finished.

   The continuation of a Stage: which stage handles the next input, chosen by the Status of the run that just finished. This is what makes a pipeline able to change as it runs — every Yield carries one.

   An Evolution is also the exclusive owner of cleanup for the stage that produced it: see dispose.

   The status to select on is the one carried alongside the evolution in the same yield, which is why callers normally go through Yield.evolve rather than dispatching on a status themselves. In a composed pipeline that status is the combined one of the whole run, never a single stage's own.

   I

   the input type of the stages returned (contravariant)

   O

   their output type (covariant)

   E

   the error type (covariant)

2.  trait Stage[-I, +O, +E] extends (I) ⇒ Yield[I, O, E]

   A single processing unit of a pipeline: a function from an input value to a Yield — an optional output, a Status, and an Evolution that decides what the pipeline looks like for the next run.

   A single processing unit of a pipeline: a function from an input value to a Yield — an optional output, a Status, and an Evolution that decides what the pipeline looks like for the next run.

   Lifecycle

   Every stage instance takes exactly one of three paths per pipeline run:

   • applied — apply receives an input value and returns a Yield. It may perform side effects and produce any output, status and evolution it likes.
   • skipped — skip returns the evolution the stage would have returned had it run, without consuming an input. Any stage that takes part in a run but does not process the current input takes this path.
   • failed — apply throws. No Yield, and therefore no Evolution, reaches the caller.

   Resource cleanup belongs to the Evolution returned by either of the first two: Evolution.dispose is the exclusive release point, and the stage is permanently unusable afterwards. The failed path is the one case where nobody outside can release anything — there is no evolution to dispose — so a stage that throws must release its own resources before letting the exception escape. The core takes no other part in exception handling; the lib module offers h8io.stages.operators.Safe as a crutch for the simplest, stateless cases. Fatal exceptions are outside this contract.

   Composition

   ~> builds a pipeline out of two stages. When the upstream yields an output, it becomes the downstream's input and the two yields are merged; when it yields nothing, the downstream is not applied for this input — it is skipped and its evolution composed in, so it still evolves in step with the rest of the pipeline.

   I

   the input type (contravariant)

   O

   the output type (covariant)

   E

   the error type (covariant)

3.  sealed trait Status[+E] extends AnyRef

   The execution status produced by a Stage.

   The execution status produced by a Stage.

   A Status travels alongside the output (or absence of output) in a Yield and is accumulated as stages are composed. There are two possible states:

   • Status.Success — the stage completed normally and processing may continue.
   • Status.Complete — a unit of work has finished. Passed to Evolution when selecting the next continuation stage; the enclosing cycle operators (Loop, Repeat and the rest of h8io.stages.cycles in the lib module) use it to end the current cycle. When errors is empty this represents clean completion; when errors is non-empty it carries one or more accumulated errors.

   Statuses form a monoid under combine, used when merging the results of composed stages: Success is the identity element and Complete accumulates errors on combination.

   E

   the error type (covariant)

4.  sealed trait Yield[-I, +O, +E] extends AnyRef

   What a Stage returns for one input: an optional output, the Status of that run, and the Evolution that picks the stage handling the next one.

   What a Stage returns for one input: an optional output, the Status of that run, and the Evolution that picks the stage handling the next one.

   Yield is the internal value flowing from stage to stage, not the answer the pipeline gives to the outside world — that is h8io.stages.base.Outcome in the lib module, produced once someone terminates the pipeline.

   There are two variants, Yield.Some and Yield.None, according to whether an output was produced. Match on them when the two cases are handled differently, on Yield itself when they are not.

   I

   the input type of the stages held by the evolution (contravariant)

   O

   the output type (covariant)

   E

   the error type (covariant)