grafos_fence/lib.rs
1//! Typed epoch/fencing helpers for stale-write rejection and leader fencing.
2//!
3//! This crate provides lightweight primitives for tracking monotonic epochs and
4//! rejecting operations that carry a stale generation number. No I/O, `no_std`
5//! compatible.
6//!
7//! # Core types
8//!
9//! | Type | Purpose |
10//! |------|---------|
11//! | [`FenceEpoch`] | Monotonic epoch counter |
12//! | [`Fenced<T>`] | A value tagged with the epoch it was produced in |
13//! | [`FenceGuard`] | Stateful checker that rejects stale epochs |
14//! | [`StaleEpochError`] | Error returned when an epoch is behind the current one |
15//!
16//! # Quick start
17//!
18//! ```rust
19//! use grafos_fence::{FenceEpoch, Fenced, FenceGuard};
20//!
21//! let mut guard = FenceGuard::new(FenceEpoch::zero());
22//!
23//! // First write at epoch 0 — accepted
24//! let msg = Fenced::at_zero("hello");
25//! assert!(guard.check(msg.epoch()).is_ok());
26//!
27//! // Leader failover bumps the epoch
28//! let new_epoch = guard.advance();
29//!
30//! // Old-epoch write is now rejected
31//! assert!(guard.check(msg.epoch()).is_err());
32//!
33//! // New-epoch write succeeds
34//! let msg2 = Fenced::new(new_epoch, "world");
35//! assert!(guard.check(msg2.epoch()).is_ok());
36//! ```
37
38#![cfg_attr(not(feature = "std"), no_std)]
39
40mod epoch;
41mod error;
42mod fenced;
43mod guard;
44
45pub use epoch::{bump_epoch, FenceEpoch};
46pub use error::StaleEpochError;
47pub use fenced::Fenced;
48pub use guard::FenceGuard;