Module maitake::sync

Asynchronous synchronization primitives

Synchronization primitives are tools for implementing synchronization between tasks: to control which tasks can run at any given time, and in what order, and to coordinate tasks’ access to shared resources. Typically, this synchronization involves some form of waiting. In asynchronous systems, synchronization primitives allow tasks to wait by yielding to the runtime scheduler, so that other tasks may run while they are waiting. This module provides asynchronous implementations of common synchronization primitives.

The following synchronization primitives are provided:

• Mutex: a fairly queued, asynchronous mutual exclusion lock, for protecting shared data
• RwLock: a fairly queued, asynchronous readers-writer lock, which allows concurrent read access to shared data while ensuring write access is exclusive
• Semaphore: an asynchronous counting semaphore, for limiting the number of tasks which may run concurrently
• WaitCell, a cell that stores a single waiting task’s Waker, so that the task can be woken by another task,
• WaitQueue, a queue of waiting tasks, which are woken in first-in, first-out order
• WaitMap, a set of waiting tasks associated with keys, in which a task can be woken by its key

Note: maitake’s synchronization primitives do not require the maitake runtime, and can be used with any async executor. Therefore, they are provided by a separate maitake-sync crate, which can be used without depending on the rest of the maitake runtime. This module re-exports these APIs from maitake-sync.

Modules

• mutex
  An asynchronous mutual exclusion lock.
• rwlock
  An asynchronous readers-writer lock.
• semaphore
  An asynchronous counting semaphore.
• spin
  Synchronous spinning-based synchronization primitives.
• util
  Reusable utilities for synchronization primitives.
• wait_cell
  An atomically registered Waker, for waking a single task.
• wait_map
  A map of Wakers associated with keys, so that a task can be woken by key.
• wait_queue
  A queue of waiting tasks that can be woken in first-in, first-out order (or all at once).

Structs

• Closed
  An error indicating that a WaitCell, WaitQueue or Semaphore was closed while attempting to register a waiting task.
• Mutex
  An asynchronous 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.
• OwnedMutexGuardalloc
  An RAII implementation of a “scoped lock” of a Mutex. When this structure is dropped (falls out of scope), the lock will be unlocked.
• OwnedRwLockReadGuard
  Owned RAII structure used to release the shared read access of a RwLock when dropped.
• OwnedRwLockWriteGuard
  Owned RAII structure used to release the exclusive write access of a RwLock when dropped.
• RwLock
  An asynchronous readers-writer lock.
• RwLockReadGuard
  RAII structure used to release the shared read access of a RwLock when dropped.
• RwLockWriteGuard
  RAII structure used to release the exclusive write access of a RwLock when dropped.
• Semaphore
  An asynchronous counting semaphore.
• WaitCell
  An atomically registered Waker.
• WaitMap
  A map of Wakers associated with keys, allowing tasks to be woken by their key.
• WaitQueue
  A queue of waiting tasks which can be woken in first-in, first-out order, or all at once.

Type Aliases

• WaitResult
  The result of waiting on a WaitQueue or Semaphore.