grafos_sync/lib.rs
1//! Distributed synchronization primitives backed by fabric memory leases.
2//!
3//! This crate provides sync primitives where **holding a lock means holding a
4//! memory lease**. If the holder crashes, the lease expires and the lock
5//! auto-releases. No heartbeats, no manual timeout tuning.
6//!
7//! # Primitives
8//!
9//! | Type | Purpose |
10//! |------|---------|
11//! | [`FabricMutex`] | Distributed mutual exclusion with RAII guard |
12//! | [`FabricBarrier`] | Multi-party phase synchronization |
13//! | [`FabricOnce`] | One-time initialization of shared state |
14//! | [`watch()`] | Single-producer multi-consumer broadcast channel |
15//!
16//! # Memory layout
17//!
18//! Each primitive stores a control header followed by optional data in leased
19//! fabric memory at a configurable `base_offset`. The offset partitioning lets
20//! multiple primitives coexist in the same arena without overlap.
21//!
22//! # Quick start
23//!
24//! ```rust,no_run
25//! use grafos_sync::{FabricMutex, FabricBarrier, FabricOnce, watch};
26//! use grafos_std::mem::MemBuilder;
27//!
28//! // Acquire a memory lease from the fabric
29//! let lease = MemBuilder::new().acquire().unwrap();
30//!
31//! // Protect a shared counter with a distributed mutex
32//! let mtx = FabricMutex::new(lease, 0, 0u64).unwrap();
33//! {
34//! let mut guard = mtx.lock(1, 100).unwrap();
35//! *guard += 1;
36//! // guard drops here, releasing the lock
37//! }
38//! ```
39//!
40//! # Crash safety
41//!
42//! The key insight: crash = lease expires = lock auto-releases. Every
43//! primitive wraps a [`grafos_std::mem::MemLease`]. When a node crashes
44//! without explicitly unlocking, the fabric reclaims the lease after its
45//! TTL expires, which implicitly releases any locks held in that memory.
46
47#![cfg_attr(not(feature = "std"), no_std)]
48
49extern crate alloc;
50
51mod barrier;
52mod mutex;
53mod once;
54mod watch;
55
56pub use barrier::FabricBarrier;
57pub use mutex::{FabricMutex, FabricMutexGuard};
58pub use once::FabricOnce;
59pub use watch::{watch, WatchReceiver, WatchSender};