Module pipeline 

Composition: chains of Plugin stages, and the registry that builds them.

Cost model

A chunk is threaded through the stages of a segment by reference. A stage that only observes (ctx.pass_through()) does not cause a copy: the next stage (and ultimately the socket) is handed the original read buffer. Only a stage that rewrites bytes materialises them, and even then the pipeline ping-pongs between two buffers it owns rather than allocating.

So a pipeline of N observers costs N virtual calls per chunk and zero copies, which is why running one is not much worse than not running one.

Framing

A chunk off the wire is one unit: one call to the stage below, one write at the far end. A stage that calls Ctx::boundary says it wants what it emitted delivered as several, which is how a stage like block cuts a stream into fixed-size records rather than merely accumulating them.

Units cost something, so nothing pays for them unless it asked. A stage that never calls boundary leaves the boundary list empty, which reads as “one unit” everywhere and allocates nothing. Below a stage that did, every stage is called once per unit, so unit counts multiply down a chain: this is the reason boundary exists as an explicit request rather than something inferred from a stage emitting more than once.

Passing through is still free under a framing stage. A stage that hands every unit back untouched copies nothing and answers Emit::Passthrough, exactly as it would on an unframed chunk; the copy starts at the first unit it rewrites, drops or reframes.

Ticks

A stage may also ask to be called on a schedule. The pipeline owns the schedules (one deadline per ticking stage) and the host owns the timer that asks whether any of them have come due. Splitting it that way means the host wakes at one period (the shortest any stage asked for) rather than holding a timer per stage, and a pipeline with nothing ticking costs nothing at all: Pipeline::tick_interval returns None and no timer is created.

Structs

BoundaryFault

A stage placed where it cannot work.

Chain

Everything that runs on one direction, split into segments.

Declaration

What one stage declared about message boundaries, and what it is called.

Emitted

What came out of a pipeline, and how it is framed.

Pipeline

An ordered chain of stages that run inline on one task.

Registry

Every plugin this binary knows how to build.

Enums

Segment

One link in a chain: either stages the host calls inline, or a subprocess it feeds and drains.

Side

Which way a stage was looking when its requirement went unmet.