skip returns this, so every status branch of the evolution evaluates to this. A skipped SAMStage is therefore indistinguishable from an active one that evolves back to itself. This is appropriate for stateless or self-contained stages (e.g. h8io.stages.std.Complete, h8io.stages.std.GlobalSoftDeadline) that carry no external resources and always use the same instance as the next stage.
dispose is a no-op by default. Override it when the stage holds external resources that must be released (see h8io.stages.std.DeadEnd for an example).
Returns this stage's Evolution without consuming an input.
Returns this stage's Evolution without consuming an input.
Called instead of apply whenever the stage takes part in a run but has nothing to process: the upstream yielded no output, or a binary operator excluded this branch. The evolution must be the one the stage would have returned had it run. Like apply, skip() may perform side effects — a decorator, for instance, may advance or release the inner stage it owns.
Releases everything held by the Stage that produced this evolution. That stage is permanently unusable afterwards — neither applied nor skipped again — and this is the only place its resources are released.
Releases everything held by the Stage that produced this evolution. That stage is permanently unusable afterwards — neither applied nor skipped again — and this is the only place its resources are released.
Whoever terminates a pipeline is responsible for disposing the evolution of the final Yield, so that the continuation is released at once instead of being carried around. The reference terminal driver is the execute extension method of h8io.stages.base in the lib module.
dispose() stays valid after evolve has been called on the same instance, and must then release everything still alive, including whatever building the continuation acquired. evolve hands over no ownership: this evolution remains the cleanup point for its lineage until the continuation has run and produced an evolution of its own, which takes the role over from that moment.
Exceptions are not part of this contract: a stage whose apply throws produces no yield and therefore no evolution, so there is nothing to dispose — it must clean up after itself (see the ''Lifecycle'' section in Stage).
A no-op is a fine implementation for a stage holding nothing external.
May release what belongs to this generation alone — anything the returned stage and its own evolution will not reuse.
evolve and dispose are not mutually exclusive. Usually only one of them is called on an instance: a terminal driver disposes, a continuing pipeline evolves and drops the previous evolution. But a caller may do both, and operators owning their inner stage (Loop, Repeat and the rest of h8io.stages.cycles in the lib module) do exactly that — they evolve eagerly and keep the inner dispose as the cleanup handle of the generation they just built.
Composes this stage with that, feeding this stage's output into it. See the ''Composition'' section above for what happens when there is no output to feed.
Composes this stage with that, feeding this stage's output into it. See the ''Composition'' section above for what happens when there is no output to feed.