187 lines
8.6 KiB
Rust
187 lines
8.6 KiB
Rust
#![cfg_attr(all(not(feature = "std"), not(test)), no_std)]
|
|
#![cfg_attr(docsrs, feature(doc_cfg))]
|
|
#![deny(missing_docs)]
|
|
|
|
//! This crate provides [spin-based](https://en.wikipedia.org/wiki/Spinlock) versions of the
|
|
//! primitives in `std::sync` and `std::lazy`. Because synchronization is done through spinning,
|
|
//! the primitives are suitable for use in `no_std` environments.
|
|
//!
|
|
//! # Features
|
|
//!
|
|
//! - `Mutex`, `RwLock`, `Once`/`SyncOnceCell`, and `SyncLazy` equivalents
|
|
//!
|
|
//! - Support for `no_std` environments
|
|
//!
|
|
//! - [`lock_api`](https://crates.io/crates/lock_api) compatibility
|
|
//!
|
|
//! - Upgradeable `RwLock` guards
|
|
//!
|
|
//! - Guards can be sent and shared between threads
|
|
//!
|
|
//! - Guard leaking
|
|
//!
|
|
//! - Ticket locks
|
|
//!
|
|
//! - Different strategies for dealing with contention
|
|
//!
|
|
//! # Relationship with `std::sync`
|
|
//!
|
|
//! While `spin` is not a drop-in replacement for `std::sync` (and
|
|
//! [should not be considered as such](https://matklad.github.io/2020/01/02/spinlocks-considered-harmful.html))
|
|
//! an effort is made to keep this crate reasonably consistent with `std::sync`.
|
|
//!
|
|
//! Many of the types defined in this crate have 'additional capabilities' when compared to `std::sync`:
|
|
//!
|
|
//! - Because spinning does not depend on the thread-driven model of `std::sync`, guards ([`MutexGuard`],
|
|
//! [`RwLockReadGuard`], [`RwLockWriteGuard`], etc.) may be sent and shared between threads.
|
|
//!
|
|
//! - [`RwLockUpgradableGuard`] supports being upgraded into a [`RwLockWriteGuard`].
|
|
//!
|
|
//! - Guards support [leaking](https://doc.rust-lang.org/nomicon/leaking.html).
|
|
//!
|
|
//! - [`Once`] owns the value returned by its `call_once` initializer.
|
|
//!
|
|
//! - [`RwLock`] supports counting readers and writers.
|
|
//!
|
|
//! Conversely, the types in this crate do not have some of the features `std::sync` has:
|
|
//!
|
|
//! - Locks do not track [panic poisoning](https://doc.rust-lang.org/nomicon/poisoning.html).
|
|
//!
|
|
//! ## Feature flags
|
|
//!
|
|
//! The crate comes with a few feature flags that you may wish to use.
|
|
//!
|
|
//! - `lock_api` enables support for [`lock_api`](https://crates.io/crates/lock_api)
|
|
//!
|
|
//! - `ticket_mutex` uses a ticket lock for the implementation of `Mutex`
|
|
//!
|
|
//! - `std` enables support for thread yielding instead of spinning
|
|
|
|
#[cfg(any(test, feature = "std"))]
|
|
extern crate core;
|
|
|
|
#[cfg(feature = "barrier")]
|
|
#[cfg_attr(docsrs, doc(cfg(feature = "barrier")))]
|
|
pub mod barrier;
|
|
#[cfg(feature = "lazy")]
|
|
#[cfg_attr(docsrs, doc(cfg(feature = "lazy")))]
|
|
pub mod lazy;
|
|
#[cfg(feature = "mutex")]
|
|
#[cfg_attr(docsrs, doc(cfg(feature = "mutex")))]
|
|
pub mod mutex;
|
|
#[cfg(feature = "once")]
|
|
#[cfg_attr(docsrs, doc(cfg(feature = "once")))]
|
|
pub mod once;
|
|
#[cfg(feature = "rwlock")]
|
|
#[cfg_attr(docsrs, doc(cfg(feature = "rwlock")))]
|
|
pub mod rwlock;
|
|
pub mod relax;
|
|
|
|
#[cfg(feature = "mutex")]
|
|
#[cfg_attr(docsrs, doc(cfg(feature = "mutex")))]
|
|
pub use mutex::MutexGuard;
|
|
#[cfg(feature = "rwlock")]
|
|
#[cfg_attr(docsrs, doc(cfg(feature = "rwlock")))]
|
|
pub use rwlock::RwLockReadGuard;
|
|
pub use relax::{Spin, RelaxStrategy};
|
|
#[cfg(feature = "std")]
|
|
#[cfg_attr(docsrs, doc(cfg(feature = "std")))]
|
|
pub use relax::Yield;
|
|
|
|
// Avoid confusing inference errors by aliasing away the relax strategy parameter. Users that need to use a different
|
|
// relax strategy can do so by accessing the types through their fully-qualified path. This is a little bit horrible
|
|
// but sadly adding a default type parameter is *still* a breaking change in Rust (for understandable reasons).
|
|
|
|
/// A primitive that synchronizes the execution of multiple threads. See [`barrier::Barrier`] for documentation.
|
|
///
|
|
/// A note for advanced users: this alias exists to avoid subtle type inference errors due to the default relax
|
|
/// strategy type parameter. If you need a non-default relax strategy, use the fully-qualified path.
|
|
#[cfg(feature = "barrier")]
|
|
#[cfg_attr(docsrs, doc(cfg(feature = "barrier")))]
|
|
pub type Barrier = crate::barrier::Barrier;
|
|
|
|
/// A value which is initialized on the first access. See [`lazy::Lazy`] for documentation.
|
|
///
|
|
/// A note for advanced users: this alias exists to avoid subtle type inference errors due to the default relax
|
|
/// strategy type parameter. If you need a non-default relax strategy, use the fully-qualified path.
|
|
#[cfg(feature = "lazy")]
|
|
#[cfg_attr(docsrs, doc(cfg(feature = "lazy")))]
|
|
pub type Lazy<T, F = fn() -> T> = crate::lazy::Lazy<T, F>;
|
|
|
|
/// A primitive that synchronizes the execution of multiple threads. See [`mutex::Mutex`] for documentation.
|
|
///
|
|
/// A note for advanced users: this alias exists to avoid subtle type inference errors due to the default relax
|
|
/// strategy type parameter. If you need a non-default relax strategy, use the fully-qualified path.
|
|
#[cfg(feature = "mutex")]
|
|
#[cfg_attr(docsrs, doc(cfg(feature = "mutex")))]
|
|
pub type Mutex<T> = crate::mutex::Mutex<T>;
|
|
|
|
/// A primitive that provides lazy one-time initialization. See [`once::Once`] for documentation.
|
|
///
|
|
/// A note for advanced users: this alias exists to avoid subtle type inference errors due to the default relax
|
|
/// strategy type parameter. If you need a non-default relax strategy, use the fully-qualified path.
|
|
#[cfg(feature = "once")]
|
|
#[cfg_attr(docsrs, doc(cfg(feature = "once")))]
|
|
pub type Once<T = ()> = crate::once::Once<T>;
|
|
|
|
/// A lock that provides data access to either one writer or many readers. See [`rwlock::RwLock`] for documentation.
|
|
///
|
|
/// A note for advanced users: this alias exists to avoid subtle type inference errors due to the default relax
|
|
/// strategy type parameter. If you need a non-default relax strategy, use the fully-qualified path.
|
|
#[cfg(feature = "rwlock")]
|
|
#[cfg_attr(docsrs, doc(cfg(feature = "rwlock")))]
|
|
pub type RwLock<T> = crate::rwlock::RwLock<T>;
|
|
|
|
/// A guard that provides immutable data access but can be upgraded to [`RwLockWriteGuard`]. See
|
|
/// [`rwlock::RwLockUpgradableGuard`] for documentation.
|
|
///
|
|
/// A note for advanced users: this alias exists to avoid subtle type inference errors due to the default relax
|
|
/// strategy type parameter. If you need a non-default relax strategy, use the fully-qualified path.
|
|
#[cfg(feature = "rwlock")]
|
|
#[cfg_attr(docsrs, doc(cfg(feature = "rwlock")))]
|
|
pub type RwLockUpgradableGuard<'a, T> = crate::rwlock::RwLockUpgradableGuard<'a, T>;
|
|
|
|
/// A guard that provides mutable data access. See [`rwlock::RwLockWriteGuard`] for documentation.
|
|
///
|
|
/// A note for advanced users: this alias exists to avoid subtle type inference errors due to the default relax
|
|
/// strategy type parameter. If you need a non-default relax strategy, use the fully-qualified path.
|
|
#[cfg(feature = "rwlock")]
|
|
#[cfg_attr(docsrs, doc(cfg(feature = "rwlock")))]
|
|
pub type RwLockWriteGuard<'a, T> = crate::rwlock::RwLockWriteGuard<'a, T>;
|
|
|
|
/// Spin synchronisation primitives, but compatible with [`lock_api`](https://crates.io/crates/lock_api).
|
|
#[cfg(feature = "lock_api")]
|
|
#[cfg_attr(docsrs, doc(cfg(feature = "lock_api")))]
|
|
pub mod lock_api {
|
|
/// A lock that provides mutually exclusive data access (compatible with [`lock_api`](https://crates.io/crates/lock_api)).
|
|
#[cfg(feature = "mutex")]
|
|
#[cfg_attr(docsrs, doc(cfg(feature = "mutex")))]
|
|
pub type Mutex<T> = lock_api_crate::Mutex<crate::Mutex<()>, T>;
|
|
|
|
/// A guard that provides mutable data access (compatible with [`lock_api`](https://crates.io/crates/lock_api)).
|
|
#[cfg(feature = "mutex")]
|
|
#[cfg_attr(docsrs, doc(cfg(feature = "mutex")))]
|
|
pub type MutexGuard<'a, T> = lock_api_crate::MutexGuard<'a, crate::Mutex<()>, T>;
|
|
|
|
/// A lock that provides data access to either one writer or many readers (compatible with [`lock_api`](https://crates.io/crates/lock_api)).
|
|
#[cfg(feature = "rwlock")]
|
|
#[cfg_attr(docsrs, doc(cfg(feature = "rwlock")))]
|
|
pub type RwLock<T> = lock_api_crate::RwLock<crate::RwLock<()>, T>;
|
|
|
|
/// A guard that provides immutable data access (compatible with [`lock_api`](https://crates.io/crates/lock_api)).
|
|
#[cfg(feature = "rwlock")]
|
|
#[cfg_attr(docsrs, doc(cfg(feature = "rwlock")))]
|
|
pub type RwLockReadGuard<'a, T> = lock_api_crate::RwLockReadGuard<'a, crate::RwLock<()>, T>;
|
|
|
|
/// A guard that provides mutable data access (compatible with [`lock_api`](https://crates.io/crates/lock_api)).
|
|
#[cfg(feature = "rwlock")]
|
|
#[cfg_attr(docsrs, doc(cfg(feature = "rwlock")))]
|
|
pub type RwLockWriteGuard<'a, T> = lock_api_crate::RwLockWriteGuard<'a, crate::RwLock<()>, T>;
|
|
|
|
/// A guard that provides immutable data access but can be upgraded to [`RwLockWriteGuard`] (compatible with [`lock_api`](https://crates.io/crates/lock_api)).
|
|
#[cfg(feature = "rwlock")]
|
|
#[cfg_attr(docsrs, doc(cfg(feature = "rwlock")))]
|
|
pub type RwLockUpgradableReadGuard<'a, T> =
|
|
lock_api_crate::RwLockUpgradableReadGuard<'a, crate::RwLock<()>, T>;
|
|
}
|