skid_pipe/lib.rs
1#![no_std]
2#![cfg_attr(docsrs, feature(doc_cfg))]
3#![forbid(unsafe_code)]
4
5//! Reusable, stateful computation pipelines for embedded, Wasm, and native Rust.
6//!
7//! Build computation modules as values and compose them with
8//! [`Pipe::from_chain`] and [`Pipe::then_chain`]. Composition uses no allocation;
9//! user-provided stages remain responsible for their own resource use.
10//!
11//! `skid-pipe`'s default feature set is dependency-free and uses only [`core`].
12//! It adds no allocator, dynamic dispatch, runtime, or executor requirement,
13//! so the same pipeline types work on native targets, WebAssembly, and
14//! `no_std` firmware. The opt-in `tokio` feature adds task-spawning adapters
15//! for Tokio applications without changing the default core.
16//! The crate contains no `unsafe` code at all: async sequencing is ordinary
17//! `async` blocks, so the compiler generates every state machine, its drop
18//! glue, and its pin projection.
19//!
20//! # Synchronous pipeline
21//!
22//! ```
23//! use skid_pipe::Pipe;
24//!
25//! let mut pipeline = Pipe::new(|value: u8| value + 1)
26//! .then(|value| value * 2);
27//!
28//! assert_eq!(pipeline.run(4), 10);
29//! ```
30//!
31//! # Fallible pipeline
32//!
33//! ```
34//! use skid_pipe::TryPipe;
35//!
36//! fn decode(value: u8) -> Result<u16, &'static str> {
37//! if value == 0 { Err("empty") } else { Ok(u16::from(value)) }
38//! }
39//!
40//! fn classify(value: u16) -> Result<bool, &'static str> {
41//! Ok(value > 10)
42//! }
43//!
44//! let mut pipeline = TryPipe::new(decode).try_then(classify);
45//! assert_eq!(pipeline.run(12), Ok(true));
46//! ```
47//!
48//! # Fallible asynchronous pipeline
49//!
50//! [`TryAsyncPipe`] composes asynchronous `Result`-returning functions and
51//! stops at the first error, without selecting an executor or allocating.
52//!
53//! ```
54//! use skid_pipe::TryAsyncPipe;
55//!
56//! async fn fetch(value: u8) -> Result<u16, &'static str> {
57//! Ok(u16::from(value))
58//! }
59//!
60//! async fn validate(value: u16) -> Result<bool, &'static str> {
61//! Ok(value > 10)
62//! }
63//!
64//! # async fn example() {
65//! let mut pipeline = TryAsyncPipe::new(fetch).try_then(validate);
66//! assert_eq!(pipeline.run(12).await, Ok(true));
67//! # }
68//! ```
69//!
70//! # Asynchronous pipeline
71//!
72//! [`AsyncPipe`] composes functions that return [`core::future::Future`]. It
73//! does not poll the future itself or select an executor.
74//!
75//! ```
76//! use skid_pipe::AsyncPipe;
77//!
78//! async fn increment(value: u8) -> u8 {
79//! value + 1
80//! }
81//!
82//! async fn double(value: u8) -> u8 {
83//! value * 2
84//! }
85//!
86//! # async fn example() {
87//! let mut pipeline = AsyncPipe::new(increment).then(double);
88//! assert_eq!(pipeline.run(4).await, 10);
89//! # }
90//! ```
91//!
92//! # Branching
93//!
94//! Branching is an ordinary `if` or `match` inside a stage, so this crate
95//! adds no combinator for it. `match` dispatches over any number of arms,
96//! and the compiler already requires every arm to produce the same type.
97//!
98//! ```
99//! use skid_pipe::Pipe;
100//!
101//! let mut pipeline = Pipe::new(|value: i32| value)
102//! .then(|value: i32| match value.signum() {
103//! 1 => value * 2,
104//! -1 => -value,
105//! _ => 0,
106//! })
107//! .then(|value: i32| value + 1);
108//!
109//! assert_eq!(pipeline.run(4), 9);
110//! assert_eq!(pipeline.run(-4), 5);
111//! ```
112//!
113//! The same holds for [`AsyncPipe`], where only the selected arm is awaited.
114//! A [`FnMut`] stage can update captured state before returning its future.
115//! To update state inside the future, use shared state such as a
116//! [`Cell`](core::cell::Cell), or implement [`AsyncStep`] for a named stage
117//! whose future borrows its mutable state.
118//!
119//! # Type names
120//!
121//! A pipeline's concrete type nests with every step
122//! (`Pipe<F3, Pipe<F2, Pipe<F1, End>>>`). Builder functions can hide that
123//! name without changing the static pipeline:
124//!
125//! Return `impl Chain<Input, Output = O>` (or `impl TryChain`,
126//! `impl AsyncChain`, or `impl TryAsyncChain`) from a builder function. This
127//! remains zero-cost and preserves compile-time validation of every
128//! connection.
129//!
130//! ```
131//! use skid_pipe::{Chain, Pipe};
132//!
133//! fn build() -> impl Chain<u16, Output = bool> {
134//! Pipe::new(|value: u16| value as f32 / 4095.0).then(|value: f32| value > 0.5)
135//! }
136//!
137//! let mut pipeline = build();
138//! assert!(pipeline.run(3000));
139//! ```
140//!
141//! The crate deliberately has no type-erased or runtime-configured pipeline.
142//! [`AsyncChain`] also returns a concrete future, so it remains allocation-free.
143//!
144//! # Type checking
145//!
146//! ```compile_fail
147//! use skid_pipe::Pipe;
148//!
149//! fn decode(_: u8) -> u16 { 0 }
150//! fn needs_boolean(_: bool) -> u32 { 0 }
151//!
152//! let mut pipeline = Pipe::new(decode).then(needs_boolean);
153//! let _ = pipeline.run(1_u8);
154//! ```
155//!
156//! ```compile_fail
157//! use skid_pipe::TryPipe;
158//!
159//! let mut pipeline = TryPipe::new(|value: u8| Ok::<_, u8>(value))
160//! .try_then(|value| Ok::<_, bool>(value));
161//! let _ = pipeline.run(1_u8);
162//! ```
163//!
164//! ```compile_fail
165//! use skid_pipe::AsyncPipe;
166//!
167//! async fn decode(_: u8) -> u16 { 0 }
168//! async fn needs_boolean(_: bool) -> u32 { 0 }
169//!
170//! let mut pipeline = AsyncPipe::new(decode).then(needs_boolean);
171//! let _ = pipeline.run(1_u8);
172//! ```
173//!
174//! ```compile_fail
175//! use skid_pipe::TryAsyncPipe;
176//!
177//! async fn decode(_: u8) -> Result<u16, ()> { Ok(0) }
178//! async fn needs_boolean(_: bool) -> Result<u32, ()> { Ok(0) }
179//!
180//! let mut pipeline = TryAsyncPipe::new(decode).try_then(needs_boolean);
181//! let _ = pipeline.run(1_u8);
182//! ```
183
184#[macro_use]
185mod ladder;
186
187mod async_pipe;
188mod pipe;
189#[cfg(feature = "tokio")]
190mod tokio;
191mod try_async_pipe;
192mod try_pipe;
193
194pub use async_pipe::{AsyncChain, AsyncChainSend, AsyncPipe, AsyncStep};
195pub use pipe::{Chain, ChainStage, End, Pipe, Step};
196#[cfg(feature = "tokio")]
197#[cfg_attr(docsrs, doc(cfg(feature = "tokio")))]
198pub use tokio::{TokioAsyncChainExt, TokioTryAsyncChainExt};
199pub use try_async_pipe::{TryAsyncChain, TryAsyncChainSend, TryAsyncPipe, TryAsyncStep};
200pub use try_pipe::{TryChain, TryPipe, TryStep};