proxima_primitives/sync/
mod.rs

1//! `proxima::sync` — runtime-agnostic concurrency primitives shaped like
2//! `tokio::sync`. Users get the API surface they expect (`use
3//! proxima_primitives::sync::Mutex;`) without pulling tokio. Backing crates are
4//! `futures` (channels, lock::Mutex), `async-lock` (RwLock, Semaphore),
5//! `event-listener` (Notify), and `async-broadcast` (watch, broadcast).
6//!
7//! The trait set re-exported here is *concurrency-defining*; runtime
8//! coupling (spawn, timers, per-core context) stays on the
9//! `Runtime` trait. See the proxima-tokio-elimination-library plan (P1.3).
10//!
11//! Tier: `notify`, `oneshot`, `shutdown`, and `AsyncMutex` (the
12//! `async-mutex` feature) compile under `no_std + alloc` (each backing
13//! crate has a no_std + alloc path; see DC-SYNC). The `watch` primitive
14//! uses `std::sync::RwLock<T>` for its value cache and is gated behind
15//! the `std` feature, as are the other remaining primitives (mpsc,
16//! mutex, once_cell, rwlock, semaphore, broadcast) — full no_std + alloc
17//! landing for those is deferred per DC-SYNC.
18//!
19//! [`blocking`] and [`task`] fold in the former `proxima-lock` and
20//! `proxima-task` crates (Workstream F, RISC-dedup) — one runtime-agnostic
21//! concurrency/task crate instead of three.
22
23// Backing crates (async-*, event-listener, futures) expose no_std + alloc
24// surfaces but the cliff requires per-crate feature-flag analysis to make
25// the proxima-sync API surface available under no_std. `notify` + `oneshot`
26// have made that crossing (see their `alloc` gates below); the remaining
27// primitives still gate behind `std` pending the same per-crate analysis.
28// Full no_std + alloc landing for those is deferred per DC-SYNC.
29#[cfg(feature = "async-mutex")]
30mod async_mutex;
31#[cfg(feature = "atomic-permits")]
32pub mod atomic_permits;
33pub mod blocking;
34#[cfg(feature = "std")]
35pub mod broadcast;
36// alloc-tier (not std): only notify's AtomicBool/Ordering re-exports are
37// reachable here without std; watch.rs is the sole consumer of this module's
38// std-only RwLock re-export, and stays std-gated internally (see below).
39#[cfg(feature = "alloc")]
40mod loom_atomic;
41#[cfg(feature = "std")]
42pub mod mpsc;
43#[cfg(feature = "std")]
44mod mutex;
45// re-gated from std to alloc: both event-listener and the AtomicBool it
46// backs support no_std + alloc, so prime can depend on Notify without
47// pulling proxima-primitives/std (and its tokio dependency) at all.
48#[cfg(feature = "alloc")]
49mod notify;
50#[cfg(feature = "std")]
51mod once_cell;
52// re-gated from std to alloc: futures::channel::oneshot has no runtime
53// coupling and compiles no_std + alloc.
54#[cfg(feature = "alloc")]
55pub mod oneshot;
56// not part of the Notify/watch loom protocol; its regular
57// proxima-runtime `tokio` feature dependency pulls tokio, which the loom
58// build keeps tokio-free.
59#[cfg(all(feature = "runtime-shaped-mutex", not(loom)))]
60pub mod runtime_shaped;
61#[cfg(feature = "std")]
62mod rwlock;
63#[cfg(feature = "alloc")]
64mod semaphore;
65// cross-core graceful shutdown (folded in from the former proxima-shutdown
66// satellite crate) — its ResourceRegistry primitive is no_std + alloc; the
67// ambient std convenience and ShutdownBarrier gate on `std` internally.
68#[cfg(feature = "alloc")]
69pub mod shutdown;
70pub mod task;
71#[cfg(feature = "std")]
72pub mod watch;
73
74/// Multi-party rendezvous, shape-compatible with `tokio::sync::Barrier`.
75/// Direct re-export of `async_lock::Barrier`. `wait()` resolves once
76/// `N` tasks have called it. Useful for staged pipeline startup
77/// (every worker reaches a barrier together) and integration tests.
78#[cfg(feature = "std")]
79pub use async_lock::Barrier;
80
81#[cfg(feature = "async-mutex")]
82pub use async_mutex::{AsyncMutex, AsyncMutexGuard};
83#[cfg(feature = "atomic-permits")]
84pub use atomic_permits::{AtomicPermit, AtomicPermitPool};
85#[cfg(feature = "std")]
86pub use mutex::{Mutex, MutexGuard, MutexLockFuture, TryLockError};
87#[cfg(feature = "alloc")]
88pub use notify::{Notified, Notify};
89#[cfg(feature = "std")]
90pub use once_cell::OnceCell;
91#[cfg(feature = "std")]
92pub use rwlock::{RwLock, RwLockReadGuard, RwLockWriteGuard};
93#[cfg(feature = "alloc")]
94pub use semaphore::{
95    AcquireError, Semaphore, SemaphoreGuard, SemaphoreGuardArc, SemaphorePermit, TryAcquireError,
96};
proxima_primitives/sync/mod.rs

proxima_primitives/sync/
mod.rs
