|0.1.0||Sep 4, 2023|
#150 in Concurrency
366 downloads per month
Used in 2 crates
what is it?
This library is a collection of synchronization primitives for asynchronous Rust
software based on
core::future, with a focus on
#![no_std] projects. It was initially developed as part of
maitake, an "async runtime construction kit" intended for use in the
mycelium and mnemOS operating systems, but it may be useful for other
projects as well.
This is a hobby project. I'm working on it in my spare time, for my own personal use. I'm very happy to share it with the broader Rust community, and contributions and bug reports are always welcome. However, please remember that I'm working on this library for fun, and if it stops being fun...well, you get the idea.
Anyway, feel free to use and enjoy this crate, and to contribute back as much as you want to!
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.
a tour of
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
In addition, the
util module contains a collection of general-purpose
utilities for implementing synchronization primitives, and the
contains implementations of non-async, spinning-based synchronization
maitake-sync is intended primarily for use in bare-metal projects, such as
operating systems, operating system components, and embedded systems. These
bare-metal systems typically do not use the Rust standard library, so
#![no_std] by default, and the use of
feature-flagged for systems where
liballoc is unavailable.
support for atomic operations
maitake-sync is a platform-agnostic library. It does not interact
directly with the underlying hardware, or use platform-specific features.
However, one aspect of
maitake-sync's implementation may differ slightly
across different target architectures:
maitake-sync relies on atomic
operations integers. Sometimes, atomic operations on integers of specific widths
are needed (e.g.,
AtomicU64), which may not be available on all architectures.
In order to work on architectures which lack atomic operations on 64-bit
maitake-sync uses the
portable-atomic crate by Taiki Endo. This
crate crate polyfills atomic operations on integers larger than the platform's
pointer width, when these are not supported in hardware.
In most cases, users of
maitake-sync don't need to be aware of
maitake-sync's use of
portable-atomic. If compiling
maitake-sync for a target architecture that has
native support for 64-bit atomic operations (such as
native atomics are used automatically. Similarly, if compiling
maitake for any
target that has atomic compare-and-swap operations on any size integer, but
lacks 64-bit atomics (i.e., 32-bit x86 targets like
i686, or 32-bit ARM
targets with atomic operations), the
portable-atomic polyfill is used
automatically. Finally, when compiling for target architectures which lack
atomic operations because they are always single-core, such as MSP430 or AVR
portable-atomic simply uses unsynchronized operations with
interrupts temporarily disabled.
The only case where the user must be aware of
portable-atomic is when
compiling for targets which lack atomic operations but are not guaranteed to
always be single-core. This includes ARMv6-M (
thumbv6m), pre-v6 ARM (e.g.,
thumbv5te), and RISC-V targets without the A extension. On these
architectures, the user must manually enable the
--cfg portable_atomic_unsafe_assume_single_core if (and only
if) the specific target hardware is known to be single-core. Enabling this cfg
is unsafe, as it will cause unsound behavior on multi-core systems using these
Additional configurations for some single-core systems, which determine the
specific sets of interrupts that
portable-atomic will disable when entering a
critical section, are described here.
The following features are available (this list is incomplete; you can help by expanding it.)
||Inhibits cache padding for the
||Enables support for
||Enables implementations of the