grafos_pipeline/
lib.rs

1//! Relocatable stage edges with generation-tracked handoff and durable
2//! checkpoints for grafOS pipelines.
3//!
4//! This crate provides the core primitives for building pipelines whose
5//! inter-stage edges can relocate transparently on failure. The key pattern:
6//!
7//! 1. A **producer** pushes items into a
8//!    [`grafos_collections::queue::FabricQueue`] via a
9//!    [`RelocatableQueueEdge`].
10//! 2. When the queue's lease expires or the connection drops, the producer
11//!    allocates a new queue, publishes the new
12//!    [`grafos_locator::locator::QueueLocator`] via a
13//!    [`grafos_locator::handoff::HandoffWriter`], and resumes pushing.
14//! 3. A **consumer** polls a [`grafos_locator::handoff::HandoffReader`] to detect the generation
15//!    bump, rebinds to the new queue, and resumes popping.
16//!
17//! Stage state can be durably checkpointed to block storage via
18//! [`CheckpointedStageState`], enabling at-least-once delivery with
19//! idempotent sinks.
20//!
21//! # Feature flags
22//!
23//! | Feature | Default | Effect |
24//! |---------|---------|--------|
25//! | `std` | Yes | Enables `std` across all grafos dependencies |
26//! | `observe` | No | Enables `grafos-observe` integration |
27
28#![cfg_attr(not(feature = "std"), no_std)]
29
30extern crate alloc;
31
32mod checkpoint;
33mod edge;
34mod error;
35mod stage_id;
36
37pub use checkpoint::CheckpointedStageState;
38pub use edge::RelocatableQueueEdge;
39pub use error::EdgeError;
40pub use stage_id::StageId;
41
42/// Alias for [`grafos_fence::FenceEpoch`] used as the edge generation counter.
43pub type EdgeGeneration = grafos_fence::FenceEpoch;
44
45/// Checkpoint recording how far a stage has progressed through its
46/// input and output queues.
47#[derive(Clone, Debug, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
48pub struct EdgeCheckpoint {
49    /// How far we read from the input queue.
50    pub input_offset: u64,
51    /// How far we committed to the output queue.
52    pub output_commit: u64,
53}
grafos_pipeline/lib.rs

grafos_pipeline/
lib.rs
