Crate spin

Source
Expand description

This crate provides spin-based 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 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) 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:

Conversely, the types in this crate do not have some of the features std::sync has:

§Feature flags

The crate comes with a few feature flags that you may wish to use.

  • lock_api enables support for lock_api

  • ticket_mutex uses a ticket lock for the implementation of Mutex

  • fair_mutex enables a fairer implementation of Mutex that uses eventual fairness to avoid starvation

  • std enables support for thread yielding instead of spinning

  • portable-atomic enables usage of the portable-atomic crate to support platforms without native atomic operations (Cortex-M0, etc.). See the documentation for the portable-atomic crate for more information with some requirements for no-std build: https://github.com/taiki-e/portable-atomic#optional-features

Re-exports§

pub use mutex::MutexGuard;mutex
pub use relax::Yield;std
pub use relax::RelaxStrategy;
pub use relax::Spin;
pub use rwlock::RwLockReadGuard;rwlock

Modules§

barrierbarrier
Synchronization primitive allowing multiple threads to synchronize the beginning of some computation.
lazylazy
Synchronization primitives for lazy evaluation.
lock_apilock_api
Spin synchronisation primitives, but compatible with lock_api.
mutexmutex
Locks that have the same behaviour as a mutex.
onceonce
Synchronization primitives for one-time evaluation.
relax
Strategies that determine the behaviour of locks when encountering contention.
rwlockrwlock
A lock that provides data access to either one writer or many readers.

Type Aliases§

Barrierbarrier
A primitive that synchronizes the execution of multiple threads. See barrier::Barrier for documentation.
Lazylazy
A value which is initialized on the first access. See lazy::Lazy for documentation.
Mutexmutex
A primitive that synchronizes the execution of multiple threads. See mutex::Mutex for documentation.
Onceonce
A primitive that provides lazy one-time initialization. See once::Once for documentation.
RwLockrwlock
A lock that provides data access to either one writer or many readers. See rwlock::RwLock for documentation.
RwLockUpgradableGuardrwlock
A guard that provides immutable data access but can be upgraded to RwLockWriteGuard. See rwlock::RwLockUpgradableGuard for documentation.
RwLockWriteGuardrwlock
A guard that provides mutable data access. See rwlock::RwLockWriteGuard for documentation.