skid-pipe
Reusable, state-capable, fully static computation pipelines for Rust
core.
skid-pipe turns a chain of ordinary Rust functions into a reusable value.
Its default core uses only core:
no_std- zero default library dependencies
- zero allocation
- static dispatch
- no runtime or executor
- no
unsafeanywhere in the crate (#![forbid(unsafe_code)]) - native, WebAssembly, and embedded-core compatible
It is not an immediate-value pipe operator, a Result-only framework, or a
network middleware stack. It is for defining an ordinary computation once and
running that same typed computation repeatedly.
use Pipe;
let mut classify = new
.then;
assert!;
assert!;
Each stage may change the value type. Rust checks every adjacent connection:
u16 ──▶ f32 ──▶ bool
When it earns its keep
Use plain Rust when a computation runs once:
#
#
#
Use skid-pipe when the composed computation itself must become a value that
you can:
- build in one module and return as
impl Chain; - run repeatedly while
FnMutstages retain state; - reuse across native, Wasm, and
no_stdtargets.
This crate does not replace Rust control flow. Branches remain ordinary
if/match expressions inside stages.
Why this shape
Pipe::new(a).then(b).then(c) stores a → b → c as one reusable value while
preserving the type of every connection. This makes it a useful boundary for
portable computation such as sensor processing, serialization, validation, or
model pre/post-processing.
The deliberately narrow contract is the point:
- ordinary functions and
FnMutclosures, including captured state; - synchronous, fallible, and async computations as separate static APIs;
- no allocator, executor, dynamic dispatch, macro expansion, or service model.
Use a value-piping crate when execution should happen immediately. Use Tower
when the problem is service readiness, backpressure, retry, timeout, or HTTP
middleware. Alternatives compares both, and measures this
crate against the futures combinators and against a plain async fn.
Core model
Appending a stage creates a new recursive type:
use Pipe;
let _pipeline = new.then.then;
Pipe<F3, Pipe<F2, Pipe<F1, End>>>
The newest stage is stored at the head, but run evaluates the tail first.
Values therefore flow left to right exactly as written:
input ──▶ F1 ──▶ F2 ──▶ F3 ──▶ output
The core path allocates nothing and uses no dynamic dispatch.
Cost model and benchmark
The recursive generic representation gives the compiler complete visibility of every stage. It adds no allocation or virtual call, but exact generated code still depends on the compiler, target, and stages. Long pipelines with many distinct type combinations can also increase compile time and binary size.
The native Criterion benchmark compares equivalent direct calls with Pipe,
TryPipe, AsyncPipe, and TryAsyncPipe composition. Fallible cases cover
different chain lengths and error positions, including first, middle, and last
errors in a 100-stage chain. Async comparisons use the same
core::future::Ready-returning stages on both sides. Construction is outside
the measured loop, matching a reusable pipeline's normal use:
Criterion is a benchmark-only development dependency; the published library's
default normal dependency graph remains empty. Neither the opt-in tokio
feature nor wide is included in these measurements.
Treat the resulting nanoseconds as machine-local evidence, not a portable performance promise. Flash size, stack use, and assembly require target-specific measurement before making embedded optimization claims.
The checked-in benchmark snapshot records the full direct comparison, including 100-stage runtime, future layout, and a Cortex-M code size probe. It intentionally reports the unfavorable long-async cases too, and records three optimizations that were measured and did not land.
A second benchmark, benches/vs_futures.rs, compares composition against the
futures combinators and against a plain async fn. See
Alternatives.
benches/vs_tower.rs separately compares the same fallible Ready stages to
Tower's normal ready-and-call service path. It is intentionally separate: Tower
implements a service contract rather than a local function pipeline.
Examples
| Example | Demonstrates | Run |
|---|---|---|
typed_sensor.rs |
Type-changing embedded-style processing | cargo run --example typed_sensor |
fallible_protocol.rs |
First-error short-circuiting | cargo run --example fallible_protocol |
stateful_router.rs |
Branching and state retained across runs | cargo run --example stateful_router |
Fallible pipelines
TryPipe composes ordinary Result<T, E> functions. It runs left to right
and stops at the first error.
use TryPipe;
let mut pipeline = new.try_then;
assert_eq!;
assert_eq!;
All stages use one caller-selected error type. The crate does not synthesize, box, or convert errors.
Stateful pipelines
Stages implement FnMut, so a pipeline may retain state between completed
runs without allocation:
use Pipe;
let mut calls = 0_u32;
let mut pipeline = new;
assert_eq!;
assert_eq!;
The mutable pipeline borrow makes this sequencing explicit. Synchronization for state shared outside the pipeline remains the caller's responsibility.
This applies to Pipe and TryPipe. An async stage cannot keep state by
capturing it into the future it returns. AsyncStep's blanket implementation
maps a stage to type Future<'a> = Fut, which does not borrow the closure, so
each call moves a fresh copy of the captured state into a new future and the
original is never updated. This compiles and silently counts nothing:
use AsyncPipe;
# async
Hold async state in a Cell
captured by shared reference instead:
use Cell;
use AsyncPipe;
# async
That Cell is ordinary Rust and works with or without this crate, so async
state retention is not something skid-pipe gives you. Composition as a value
is. TryAsyncPipe behaves the same way.
Branching
Branching is a normal stage. The selected arm may run its own typed sub-pipeline, and an enum can merge branches with different output types:
use Pipe;
let mut sensor = new;
let mut command = new;
let mut pipeline = new.then;
There is no branch DSL to learn and no branch object to allocate.
Async without an executor dependency
AsyncPipe composes functions that return futures. It returns the composed
future without boxing it, polling it, or selecting an executor.
use AsyncPipe;
async
async
# async
The caller may use Tokio, Embassy, a browser/Wasm integration, or any other
environment. Creating a run future is lazy and free: it is an async block, so
no stage runs and nothing is written until the future is first polled, whatever
the chain's length. run holds the mutable pipeline borrow until its future
completes or is dropped, so a stateful pipeline instance cannot run
concurrently. The default core crate does not depend on any executor.
Tokio feature
Enable the optional integration when the application already uses Tokio:
[]
= { = "0.3", = ["tokio"] }
The feature enables Tokio's minimal rt feature and exports two extension
traits: TokioAsyncChainExt and TokioTryAsyncChainExt. They move a pipeline
and one input into a Tokio task, making the required ownership boundary
explicit. The default feature set remains no_std, dependency-free, and free
of Tokio.
For tokio::spawn,
import the extension trait and consume the pipeline with spawn:
use ;
let task = new
.then
.spawn;
spawn requires the pipeline, input, output, and composed run future to meet
Tokio's Send + 'static boundary. A run future created from a pipeline that
stays on the caller's stack borrows that pipeline and therefore cannot itself
be made 'static.
The composed future is an unnameable impl Future, so that Send bound cannot
be written directly. AsyncChainSend and TryAsyncChainSend restate the same
composition with Send promised in the return type, and spawn asks for them.
Concrete pipelines get them automatically, but a builder that hides its type
must say so:
use ;
+
Without the second bound the builder's pipeline still runs and awaits; only
spawn refuses it.
For a non-Send stage, use Tokio's
LocalSet::spawn_local
with the same ownership pattern:
use ;
let result = local.run_until.await;
One stateful pipeline processes runs sequentially. To handle jobs concurrently,
move a distinct pipeline value into each task, or keep one pipeline in a
long-lived task and send jobs to that task. Aborting a task drops its active
run future; already-polled FnMut state changes are not rolled back.
TryAsyncPipe provides the same static composition for futures that resolve
to Result<T, E>. It stops before calling any stage after the first error:
use TryAsyncPipe;
async
async
# async
Its returned future likewise keeps a mutable borrow until completion or drop.
Dropping a pending run permits a later run, but state changes already made by
polled FnMut stages are retained.
Long async chains and embedded stacks
All four pipeline variants are compiled and executed with 100 stages on the
declared Rust 1.86 MSRV without requiring callers to raise rustc's default
recursion limit. Async chains put each group of sixteen stages into one async
block, and rustc overlaps a group's stage futures into a single slot, so the
run future stops growing once a group is full.
Past 127 stages that no longer holds: the calling crate has to raise
#![recursion_limit] itself. The wide feature widens a group to
thirty-two, which shrinks the run future further — a 100-stage chain goes from
120 B to 72 B — but does not move that 127-stage ceiling.
This is a supported compilation and behavior boundary, not a promise that a 100-stage future fits every firmware task stack. Pipeline future size grows with the number of stages, captured state, intermediate values, and the largest active stage future. Measure the concrete target before deployment:
# use AsyncPipe;
let mut pipeline = new;
let future = pipeline.run;
let bytes = size_of_val;
assert!;
On a constrained executor task, prefer shorter pipelines with explicit await boundaries over one 100-stage future. This lets each phase's run future finish before the next is created and gives the linker and stack analysis smaller, more useful units to inspect.
The crate contains no unsafe code at all, and #![forbid(unsafe_code)] keeps
it that way. Async sequencing is an ordinary async block per group of stages,
so rustc generates each state machine, its discriminant, its drop glue and its
pin projection, and only one stage future in a group is live at a time because
the compiler overlaps them. Callers never need unsafe code either.
API boundaries
A concrete pipeline type grows with every stage. Return an opaque static trait from a builder function when callers should not name that recursive type:
use ;
Step, TryStep, AsyncStep, and TryAsyncStep are public and open to
hand-written implementations for named stateful stages. Builder functions may
return the corresponding Chain, TryChain, AsyncChain, or TryAsyncChain
trait to hide their recursive concrete type. These execution traits are
Sized; the core deliberately offers no type-erased, boxed, or
runtime-configured pipeline. That keeps every stage connection statically
checked, allocation-free, and free of dynamic dispatch.
Alternatives
Several crates carry "pipeline" in their name while composing different things. Knowing which one you need settles most of the choice:
| Composes | Result is | |
|---|---|---|
pipe-trait, pipeline, pipeop, apply |
a value through functions | evaluated on the spot |
futures combinators |
futures | a chain one await consumes |
tower |
request/response services | a Service with readiness |
skid-pipe |
functions | a value you run repeatedly |
x.pipe(f).pipe(g) runs immediately and leaves nothing behind, so those crates
are not alternatives to this one despite the shared vocabulary. Use tower when
the problem is readiness, backpressure, retry, timeout, or HTTP middleware;
skid-pipe models none of those and should not be bent into them. tower needs
std.
futures is the real overlap: it is no_std-capable and its combinators chain
async stages. The difference is that it composes futures, so a caller running
the same computation twice builds the chain twice. benches/vs_futures.rs
measures that on identical stage bodies, payloads, and Ready futures:
| Group | plain async fn |
skid-pipe |
futures |
|---|---|---|---|
| async, 3 stages | 12.750 ns | 23.518 ns | 41.611 ns |
try async, 3 stages |
35.221 ns | 43.561 ns | 49.326 ns |
try async, 3 stages, first error |
11.715 ns | 19.292 ns | 25.322 ns |
| async, 10 stages | 44.015 ns | 57.716 ns | 153.390 ns |
try async, 10 stages, first error |
11.464 ns | 19.583 ns | 74.135 ns |
skid-pipe is 1.1x to 1.8x faster than the combinators at three stages and
2.7x to 3.8x at ten, the gap widening because the rebuild scales with the chain
while run only issues a future for a pipeline that already exists.
The last column is also the answer to a question this file raises elsewhere:
first-error short-circuiting is TryAsyncPipe's worst result against direct
calls, and and_then on the same shape costs more of it. That overhead is what
static async composition costs, not something this crate does badly.
A plain async fn beats both crates in every group, by 24% to 85% against
skid-pipe. It is also reusable — you can call it as often as you like. What it
cannot do is be assembled: its stages are fixed where it is written, it cannot
be built conditionally or returned from a builder as one typed value, and each
connection is checked only inside its own body. That is what skid-pipe sells,
and it is not speed. When the chain is short and lives in one place, write the
async fn.
Neither does skid-pipe fix the one reuse problem an async fn does have:
state across calls needs a Cell either way, as
Stateful pipelines shows.
Tower is the closest reusable abstraction with a different purpose. Its
services have a readiness protocol and address server/client middleware; it is
not no_std. A separate benchmark uses the same fallible Ready stages in a
three-stage ServiceBuilder::and_then stack and invokes it through Tower's
normal ready().await.call() path:
| Group | plain async fn |
skid-pipe |
Tower ready + call |
|---|---|---|---|
| try async, 3 stages, success | 11.913 ns | 20.050 ns | 30.783 ns |
That is a 1.54x Tower/skid-pipe ratio in this machine-local run. It does not
make Tower a poor choice: the measured difference is the cost of a service
protocol this crate intentionally does not implement. Use Tower for readiness,
backpressure, timeout, retry, and request/response middleware; use
skid-pipe for a local, typed computation chain.
Task/channel pipeline crates (async-pipes, pumps, and pipelines),
type-keyed workflow kits (pipeline-toolkit), and scratchpad executors
(pipexec) are also adjacent rather than direct nanosecond competitors. Their
fair comparison is a multi-item throughput, p99 latency, memory, and
backpressure workload; BENCHMARKS.md records the exact
boundary rather than presenting a misleading single-item ranking.
See BENCHMARKS.md for the full comparison and its method.
What this crate is not
skid-pipe is deliberately not:
- an HTTP middleware stack;
- an async runtime or executor;
- a retry, timeout, or authentication framework;
- a global-state or dependency-injection container;
- a parallel stream processor;
- a persistent workflow engine;
- a state-machine DSL;
- a plugin loader;
- a replacement for straightforward local variables and
?.
If you need readiness, backpressure, timeout, retry, or network middleware, use a service abstraction such as Tower. If the computation is local and one-shot, ordinary procedural Rust is usually clearer.
Platform validation
CI checks the static core on stable Rust and the declared MSRV (Rust 1.86), including representative targets:
wasm32-unknown-unknownwasm32v1-nonethumbv6m-none-eabithumbv7em-none-eabihfriscv32imac-unknown-none-elf
The core stays ecosystem-neutral. Integrations that require a HAL, executor, logging framework, or model runtime belong in separate adapter crates.
Versioning and compatibility
The minimum supported Rust version (MSRV) is Rust 1.86. CI checks both the MSRV and stable Rust. An MSRV increase is treated as a semver-minor change and is recorded in the changelog.
While the crate is below 1.0, a minor release may change public APIs. Patch releases are reserved for fixes, documentation, and compatible performance improvements; they do not intentionally break existing code. When practical, an API replacement is deprecated before removal. Any required migration and its replacement API are called out in the changelog for the release.
The core compatibility boundary remains no_std, allocation-free, statically
dispatched composition. HTTP clients, retry, timeout, authentication, and
global state management belong to applications or separate transport/service
layers.
License
Licensed under the MIT License.
Validation
RUSTDOCFLAGS="-D warnings"