Skip to main content

pipeline_toolkit/
lib.rs

1//! A small toolkit for building linear, async processing pipelines out of
2//! independently testable steps that communicate through a shared,
3//! type-keyed [`Context`].
4//!
5//! Each [`Step`] declares, via [`Step::access`], exactly which types it
6//! reads, writes, or consumes from the [`Context`]. [`PipelineBuilder::build`]
7//! uses those declarations to catch wiring mistakes — a step reading a type
8//! nothing upstream produces — before the pipeline ever runs, and
9//! [`Context`] enforces them again at run time, so a step that reads or
10//! writes something it didn't declare fails fast with
11//! [`PipelineError::AccessViolation`] instead of silently drifting from its
12//! declared contract.
13//!
14//! # Examples
15//!
16//! ```
17//! use pipeline_toolkit::{AccessSpec, Context, Flow, Pipeline, Step, StepError};
18//!
19//! struct LoadName;
20//!
21//! #[async_trait::async_trait]
22//! impl Step<String> for LoadName {
23//!     fn name(&self) -> &str {
24//!         "load_name"
25//!     }
26//!
27//!     fn access(&self) -> AccessSpec {
28//!         AccessSpec::new().writes::<String>()
29//!     }
30//!
31//!     async fn run(&self, ctx: &mut Context) -> Result<Flow<String>, StepError> {
32//!         ctx.insert("Ada".to_string());
33//!         Ok(Flow::Continue)
34//!     }
35//! }
36//!
37//! struct Greet;
38//!
39//! #[async_trait::async_trait]
40//! impl Step<String> for Greet {
41//!     fn name(&self) -> &str {
42//!         "greet"
43//!     }
44//!
45//!     fn access(&self) -> AccessSpec {
46//!         AccessSpec::new().reads::<String>()
47//!     }
48//!
49//!     async fn run(&self, ctx: &mut Context) -> Result<Flow<String>, StepError> {
50//!         let name = ctx.get::<String>().expect("declared as read").clone();
51//!         Ok(Flow::Done(format!("Hello, {name}!")))
52//!     }
53//! }
54//!
55//! # fn block_on<F: std::future::Future>(fut: F) -> F::Output {
56//! #     use std::task::{Context as TaskContext, Poll, Waker};
57//! #     let mut fut = std::pin::pin!(fut);
58//! #     let mut cx = TaskContext::from_waker(Waker::noop());
59//! #     loop {
60//! #         if let Poll::Ready(val) = fut.as_mut().poll(&mut cx) {
61//! #             return val;
62//! #         }
63//! #     }
64//! # }
65//! #
66//! let pipeline = Pipeline::<(), String>::builder()
67//!     .step(LoadName)
68//!     .step(Greet)
69//!     .build()?;
70//!
71//! let greeting = block_on(pipeline.run(()))?;
72//! assert_eq!(greeting, "Hello, Ada!");
73//! # Ok::<(), Box<dyn std::error::Error>>(())
74//! ```
75
76#![warn(missing_docs)]
77
78mod branch;
79mod context;
80mod iteration;
81mod pipeline;
82mod step;
83#[cfg(test)]
84mod test_support;
85
86pub use branch::{Arm, ArmBuilder, Branch, BranchBuilder};
87pub use context::{AccessKind, AccessSpec, AccessViolation, Context};
88pub use iteration::{Loop, LoopBuilder};
89pub use pipeline::{BuildError, Pipeline, PipelineBuilder, PipelineError};
90pub use step::{Flow, Step, StepError};