Expand description
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 obligationsRwLock: Read-write lock with cancel-aware acquisitionSemaphore: Counting semaphore with permit obligationsPool: Resource pooling with obligation-based return semanticsBarrier: N-way rendezvous with leader electionNotify: 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)
Re-exports§
pub use semaphore::AcquireError;pub use semaphore::OwnedSemaphorePermit;pub use semaphore::Semaphore;pub use semaphore::SemaphorePermit;pub use semaphore::TryAcquireError;
Modules§
- semaphore
- Two-phase semaphore with permit obligations.
Structs§
- Barrier
- Barrier for N-way rendezvous.
- Barrier
Wait Result - Result of a barrier wait.
- Contended
Mutex - Zero-cost mutex wrapper (metrics disabled).
- Contended
Mutex Guard - Zero-cost guard wrapper (metrics disabled).
- Generic
Pool - A generic resource pool with configurable behavior.
- Lock
Metrics Snapshot - Snapshot of lock contention metrics.
- Mutex
- An async mutex for mutual exclusion.
- Mutex
Guard - A guard that releases the mutex when dropped.
- Notified
- Future returned by
Notify::notified. - Notify
- A notify primitive for signaling events.
- Once
Cell - A cell that can be initialized exactly once.
- Owned
Mutex Guard - An owned guard that releases the mutex when dropped.
- Owned
RwLock Read Guard - Owned read guard that can be moved between tasks.
- Owned
RwLock Write Guard - Owned write guard that can be moved between tasks.
- Pool
Config - Configuration for a generic resource pool.
- Pool
Stats - Pool usage statistics.
- Pooled
Resource - A resource acquired from a pool.
- RwLock
- A cancel-aware read-write lock with writer-preference fairness.
- RwLock
Read Guard - Guard for a read lock.
- RwLock
Write Guard - Guard for a write lock.
Enums§
- Barrier
Wait Error - Error returned when waiting on a barrier fails.
- Destroy
Reason - Reason why a resource was destroyed.
- Lock
Error - Error returned when mutex locking fails.
- Once
Cell Error - Error returned when a OnceCell operation fails.
- Pool
Error - Error type for GenericPool operations.
- Pool
Return - Return messages sent from
PooledResourceback to a pool implementation. - RwLock
Error - Error returned when acquiring a read or write lock fails.
- TryLock
Error - Error returned when trying to lock without waiting.
- TryRead
Error - Error returned when trying to read without waiting.
- TryWrite
Error - Error returned when trying to write without waiting.
- Warmup
Strategy - Strategy for handling partial warmup failures.
Traits§
- Async
Resource Factory - Trait for async resource creation and destruction.
- Pool
- Trait for resource pools with cancel-safe acquisition.
Type Aliases§
- Pool
Future - Boxed future helper for async trait-like APIs.
- Pool
Return Receiver - Receiver used to observe resources returning to a pool.
- Pool
Return Sender - Sender used to return resources back to a pool.