Module sync 

proxima::sync — runtime-agnostic concurrency primitives shaped like tokio::sync. Users get the API surface they expect (use proxima_primitives::sync::Mutex;) without pulling tokio. Backing crates are futures (channels, lock::Mutex), async-lock (RwLock, Semaphore), event-listener (Notify), and async-broadcast (watch, broadcast).

The trait set re-exported here is concurrency-defining; runtime coupling (spawn, timers, per-core context) stays on the Runtime trait. See the proxima-tokio-elimination-library plan (P1.3).

Tier: notify, oneshot, shutdown, and AsyncMutex (the async-mutex feature) compile under no_std + alloc (each backing crate has a no_std + alloc path; see DC-SYNC). The watch primitive uses std::sync::RwLock<T> for its value cache and is gated behind the std feature, as are the other remaining primitives (mpsc, mutex, once_cell, rwlock, semaphore, broadcast) — full no_std + alloc landing for those is deferred per DC-SYNC.

blocking and task fold in the former proxima-lock and proxima-task crates (Workstream F, RISC-dedup) — one runtime-agnostic concurrency/task crate instead of three.

Modules

blocking

proxima_primitives::sync::blocking — canonical tier-resolved BLOCKING mutex.

broadcast

proxima::sync::broadcast — multi-producer multi-consumer broadcast channel, shape-compatible with tokio::sync::broadcast. Backed by async_broadcast configured for overflow semantics: producers never block; if the buffer fills, the oldest message is dropped and the affected receivers see RecvError::Lagged(skipped) on their next recv.

mpsc

proxima::sync::mpsc — multi-producer single-consumer channel, shape-compatible with tokio::sync::mpsc. Backed by async-channel because tokio’s Sender::send(&self, T) shape — async send without a &mut borrow — requires interior synchronization that async-channel provides directly. futures::channel::mpsc’s capacity-per-clone semantics inflate buffers unexpectedly when used the same way, so we route through async-channel instead.

oneshot

proxima::sync::oneshot — single-value channel, shape-compatible with tokio::sync::oneshot. Backed by futures::channel::oneshot (no runtime coupling). The receiver’s await resolves to Result<T, Canceled> rather than tokio’s RecvError; callers that only care about success/failure (.ok(), .is_err()) port verbatim. Code that explicitly matches on RecvError must adapt to Canceled.

shutdown

Cross-core graceful shutdown with per-core resource ordering.

task

proxima_primitives::sync::task — runtime-agnostic task primitives shaped like tokio::task. Folded from the former proxima-task crate (Workstream F, RISC-dedup) so other proxima leaf crates (proxima-middleware, proxima-listeners-*, prime, etc.) reach it via the same crate as the rest of proxima’s concurrency surface, without circling back through the top-level proxima crate.

watch

proxima::sync::watch — single-producer, multi-consumer latest-value channel. Shape-compatible with tokio::sync::watch: each receiver tracks whether it has observed the current value; slow receivers don’t block fast ones; back-to-back sends collapse to the last value if the consumer hasn’t called changed() in between.

Structs

AcquireError

Error returned by acquire().await when the semaphore is closed.

Barrier

Multi-party rendezvous, shape-compatible with tokio::sync::Barrier. Direct re-export of async_lock::Barrier. wait() resolves once N tasks have called it. Useful for staged pipeline startup (every worker reaches a barrier together) and integration tests. A counter to synchronize multiple tasks at the same time.

Mutex

Async mutex matching tokio::sync::Mutex’s API shape, backed by futures::lock::Mutex.

MutexGuard

An RAII guard returned by the lock and try_lock methods. When this structure is dropped (falls out of scope), the lock will be unlocked.

MutexLockFuture

A future which resolves when the target mutex has been successfully acquired.

Notified

Future returned by Notify::notified. Can be explicitly registered without polling via Notified::enable to close lost-wakeup races between state check and park.

Notify

OnceCell

A memory location that can be written to at most once.

RwLock

Async reader-writer lock matching tokio::sync::RwLock’s shape.

RwLockReadGuard

A guard that releases the read lock when dropped.

RwLockWriteGuard

A guard that releases the write lock when dropped.

Semaphore

Counted async semaphore.

SemaphoreGuard

A guard that releases the acquired permit.

SemaphoreGuardArc

An owned guard that releases the acquired permit.

SemaphorePermit

Acquired permit. Releases back into the pool on drop.

TryLockError

Error returned by Mutex::try_lock when the lock would block. Matches tokio::sync::TryLockError’s shape (unit-payload).

Enums

TryAcquireError

Error returned by try_acquire().