Crate spin

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:

• 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.

• 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.

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

Re-exports

• pub use mutex::MutexGuard;
• pub use relax::RelaxStrategy;
• pub use relax::Spin;
• pub use rwlock::RwLockReadGuard;

Modules

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

Type Definitions

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