pub struct Context { /* private fields */ }Expand description
A type-keyed store of at most one value per type, shared across the
steps of a running Pipeline.
Values are stored and retrieved by their Rust type rather than by name:
insert stores at most one T at a time, and
get/get_mut/take
retrieve it by inferring T from the call site.
While a Pipeline is running, Context also enforces
the active step’s AccessSpec: a get/get_mut/insert/take/
contains call for a type the step didn’t declare returns None/false
instead of the real value, and records an AccessViolation that
Pipeline::run turns into an error. Used
directly, outside of a pipeline, a fresh Context has no active step and
every access is unrestricted.
Implementations§
Source§impl Context
impl Context
Sourcepub fn new() -> Self
pub fn new() -> Self
Creates an empty context with no stored values and no active step.
§Examples
use pipeline_toolkit::Context;
let mut ctx = Context::new();
assert!(!ctx.contains::<i32>());Sourcepub fn get<T: Send + Sync + 'static>(&self) -> Option<&T>
pub fn get<T: Send + Sync + 'static>(&self) -> Option<&T>
Reads a value of type T from the context.
Returns None both when no value of type T has been inserted and
when the active step’s AccessSpec doesn’t grant it read access —
the two cases are indistinguishable from the return value alone.
Takes &self (unlike Self::get_mut/Self::take, which need
exclusive access to mutate or remove the entry) so that a step can
read several distinct types without the borrow checker forcing it to
finish with one reference before requesting another.
§Examples
use pipeline_toolkit::Context;
struct Marker(i32);
let mut ctx = Context::new();
ctx.insert(Marker(7));
assert_eq!(ctx.get::<Marker>().map(|m| m.0), Some(7));Sourcepub fn get_mut<T: Send + Sync + 'static>(&mut self) -> Option<&mut T>
pub fn get_mut<T: Send + Sync + 'static>(&mut self) -> Option<&mut T>
Mutably borrows a value of type T from the context, for in-place
mutation.
Returns None both when no value of type T is present and when
the active step’s AccessSpec doesn’t grant it both read and
write access — get_mut needs both, since it lets the caller
observe the prior value as well as replace it. Pair this with
AccessSpec::reads_writes, not AccessSpec::writes alone.
§Examples
use pipeline_toolkit::Context;
struct Counter(i32);
let mut ctx = Context::new();
ctx.insert(Counter(1));
ctx.get_mut::<Counter>().unwrap().0 += 1;
assert_eq!(ctx.get::<Counter>().map(|c| c.0), Some(2));Sourcepub fn insert<T: Send + Sync + 'static>(&mut self, value: T) -> Option<T>
pub fn insert<T: Send + Sync + 'static>(&mut self, value: T) -> Option<T>
Stores value, replacing any existing value of type T.
Returns the replaced value — but only if the active step’s
AccessSpec also grants read access to T. Insert itself only
requires write access; handing back the overwritten value would let
a write-only step observe data it never declared reading, so that
case returns None even though the overwrite still happens.
§Examples
use pipeline_toolkit::Context;
struct Marker(i32);
let mut ctx = Context::new();
assert!(ctx.insert(Marker(1)).is_none());
let previous = ctx.insert(Marker(2));
assert_eq!(previous.map(|m| m.0), Some(1));Sourcepub fn take<T: Send + Sync + 'static>(&mut self) -> Option<T>
pub fn take<T: Send + Sync + 'static>(&mut self) -> Option<T>
Removes and returns the value of type T, if present.
Requires the active step’s AccessSpec to have granted
AccessSpec::consumes specifically, not just
AccessSpec::reads_writes: the latter only promises in-place
mutation via Self::get_mut, so
PipelineBuilder::build still
treats the type as written afterward. Accepting reads_writes here
too would let a step remove a value that build-time validation
believes is still present for downstream readers.
§Examples
use pipeline_toolkit::Context;
struct Payload(i32);
let mut ctx = Context::new();
ctx.insert(Payload(5));
assert_eq!(ctx.take::<Payload>().map(|p| p.0), Some(5));
assert!(!ctx.contains::<Payload>());Sourcepub fn contains<T: Send + Sync + 'static>(&mut self) -> bool
pub fn contains<T: Send + Sync + 'static>(&mut self) -> bool
Reports whether a value of type T is currently stored.
Like Self::get, returns false both when T is absent and when
the active step’s AccessSpec doesn’t grant it read access.
§Examples
use pipeline_toolkit::Context;
struct Marker;
let mut ctx = Context::new();
assert!(!ctx.contains::<Marker>());
ctx.insert(Marker);
assert!(ctx.contains::<Marker>());