Module maitake::sync::spin

Synchronous spinning-based synchronization primitives.

The synchronization primitives in maitake-sync are asynchronous. They are designed to be used with core::task and core::future, and when it is necessary to wait for another task to complete some work for the current task to proceed, maitake’s synchronization primitives wait by yielding to the asynchronous task scheduler to allow another task to proceed.

This module, on the other hand, provides synchronous (or blocking) synchronization primitives. Rather than yielding to the runtime, these synchronization primitives will block the current CPU core (or thread, if running in an environment with threads) until they are woken by other cores. This is performed by spinning: issuing yield or pause instructions in a loop until some value changes. These synchronization primitives are, in some cases, necessary to implement the async synchronization primitives that form maitake-sync’s core APIs. They are also exposed publicly so they can be used in other projects, when a spinlock-based synchronization primitive is needed.

This module provides the following APIs:

• Mutex: a synchronous [mutual exclusion] spinlock.
• RwLock: a synchronous [reader-writer] spinlock.
• InitOnce: a cell storing a MaybeUninit value which must be manually initialized prior to use.
• Lazy: an InitOnce cell coupled with an initializer function. The Lazy cell ensures the initializer is called to initialize the value the first time it is accessed.

Modules

• once
  Cells storing a value which must be initialized prior to use.

Structs

• InitOnce
  A cell which may be initialized a single time after it is created.
• Lazy
  A cell which will be lazily initialized by the provided function the first time it is accessed.
• Mutex
  A spinlock-based mutual exclusion lock for protecting shared data
• MutexGuard
  An RAII implementation of a “scoped lock” of a mutex. When this structure is dropped (falls out of scope), the lock will be unlocked.
• RwLock
  A spinlock-based readers-writer lock.
• RwLockReadGuard
  An RAII implementation of a “scoped read lock” of a RwLock. When this structure is dropped (falls out of scope), the lock will be unlocked.
• RwLockWriteGuard
  An RAII implementation of a “scoped write lock” of a RwLock. When this structure is dropped (falls out of scope), the lock will be unlocked.