h8io.stages
Members list
Packages
Type aliases used throughout the lib module for describing stage transformations.
Type aliases used throughout the lib module for describing stage transformations.
// A decorator is a stage itself: it wraps a Stage[I, O, E] and is one:
val myDecorator: Decorator[String, Int, Nothing] = CompleteIfNone(stage)
// A decoration is the function building it; an alteration is the same with the types free to change:
val myDecoration: Decoration[String, Int, Nothing] = CompleteIfNone(_)
val myAlteration: Alteration[Stage[String, Int, Nothing], Stage[String, Option[Int], Nothing]] = Lift(_)
Attributes
Type members
Classlikes
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.
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.
Type parameters
- E
-
the error type (covariant)
- I
-
the input type of the stages returned (contravariant)
- O
-
their output type (covariant)
Attributes
- Companion
- object
- Supertypes
-
class Objecttrait Matchableclass Any
- Known subtypes
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''' —
applythrows. NoYield, and therefore noEvolution, 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.
Type parameters
- E
-
the error type (covariant)
- I
-
the input type (contravariant)
- O
-
the output type (covariant)
Attributes
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,Repeatand the rest ofh8io.stages.cyclesin the lib module) use it to end the current cycle. Whenerrorsis empty this represents clean completion; whenerrorsis 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.
Type parameters
- E
-
the error type (covariant)
Attributes
- Companion
- object
- Supertypes
-
class Objecttrait Matchableclass Any
- Known subtypes
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.
Type parameters
- E
-
the error type (covariant)
- I
-
the input type of the stages held by the evolution (contravariant)
- O
-
the output type (covariant)
Attributes
- Companion
- object
- Supertypes
-
class Objecttrait Matchableclass Any
- Known subtypes