asupersync 0.3.1

Spec-first, cancel-correct, capability-secure async runtime for Rust.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67

//! Synchronization primitives with two-phase semantics.
//!
//! This module provides cancel-safe synchronization primitives where
//! guards and permits are tracked as obligations that must be released.
//!
//! # Primitives
//!
//! - [`Mutex`]: Mutual exclusion with guard obligations
//! - [`RwLock`]: Read-write lock with cancel-aware acquisition
//! - [`Semaphore`]: Counting semaphore with permit obligations
//! - [`Pool`]: Resource pooling with obligation-based return semantics
//! - [`Barrier`]: N-way rendezvous with leader election
//! - [`Notify`]: Event signaling (one-shot or broadcast)
//! - [`OnceCell`]: Lazy initialization cell
//!
//! # Two-Phase Pattern
//!
//! All primitives in this module follow a two-phase pattern:
//!
//! - **Phase 1 (Wait)**: Wait for the resource to become available.
//!   This phase is cancel-safe - cancellation during wait is clean.
//! - **Phase 2 (Hold)**: Hold the resource (guard/permit). The guard
//!   is an obligation that must be released (via drop).
//!
//! # Cancel Safety
//!
//! - Cancellation during wait: Clean abort, no resource held
//! - Cancellation while holding: Guard dropped, resource released
//! - Panic while holding: Guard dropped via unwind (unwind safety)

mod barrier;
mod contended_mutex;
mod mutex;
mod notify;

mod once_cell;
#[cfg(test)]
mod once_cell_metamorphic;
mod pool;
mod rwlock;
#[cfg(test)]
mod rwlock_lost_wakeup_test;
pub mod semaphore;

pub use barrier::{Barrier, BarrierWaitError, BarrierWaitResult};
pub use contended_mutex::{ContendedMutex, ContendedMutexGuard, LockMetricsSnapshot};
pub use mutex::{LockError, Mutex, MutexGuard, OwnedMutexGuard, TryLockError};
pub use notify::{Notified, Notify};
pub use once_cell::{OnceCell, OnceCellError};
pub use pool::{
    AsyncResourceFactory, DestroyReason, GenericPool, Pool, PoolConfig, PoolError, PoolFuture,
    PoolReturn, PoolReturnReceiver, PoolReturnSender, PoolStats, PooledResource, WarmupStrategy,
};
#[cfg(feature = "metrics")]
pub use pool::{PoolMetrics, PoolMetricsHandle, PoolMetricsState};
pub use rwlock::{
    OwnedRwLockReadGuard, OwnedRwLockWriteGuard, RwLock, RwLockError, RwLockReadGuard,
    RwLockWriteGuard, TryReadError, TryWriteError,
};
pub use semaphore::{
    AcquireError, OwnedSemaphorePermit, Semaphore, SemaphorePermit, TryAcquireError,
};
#[cfg(test)]
mod barrier_metamorphic;
mod mutex_deadlock_test;
#[cfg(test)]
mod mutex_metamorphic;