maitake/
lib.rs

1#![cfg_attr(docsrs, doc = include_str!("../README.md"))]
2#![cfg_attr(docsrs, feature(doc_cfg, doc_auto_cfg, doc_cfg_hide))]
3#![cfg_attr(docsrs, doc(cfg_hide(docsrs, loom)))]
4#![cfg_attr(not(test), no_std)]
5#![allow(unused_unsafe)]
6
7#[cfg(feature = "alloc")]
8extern crate alloc;
9
10#[macro_use]
11pub(crate) mod util;
12#[macro_use]
13pub(crate) mod trace;
14pub(crate) mod loom;
15
16pub mod future;
17pub mod scheduler;
18pub mod task;
19pub mod time;
20
21pub mod sync {
22    //! Asynchronous synchronization primitives
23    //!
24    //! [_Synchronization primitives_][primitives] are tools for implementing
25    //! synchronization between [tasks]: to control which tasks can run at any given
26    //! time, and in what order, and to coordinate tasks' access to shared
27    //! resources. Typically, this synchronization involves some form of _waiting_.
28    //! In asynchronous systems, synchronization primitives allow tasks to wait by
29    //! yielding to the runtime scheduler, so that other tasks may run while they
30    //! are waiting. This module provides asynchronous implementations of common
31    //! synchronization primitives.
32    //!
33    //! The following synchronization primitives are provided:
34    //!
35    //! - [`Mutex`]: a fairly queued, asynchronous [mutual exclusion lock], for
36    //!   protecting shared data
37    //! - [`RwLock`]: a fairly queued, asynchronous [readers-writer lock], which
38    //!   allows concurrent read access to shared data while ensuring write
39    //!   access is exclusive
40    //! - [`Semaphore`]: an asynchronous [counting semaphore], for limiting the
41    //!   number of tasks which may run concurrently
42    //! - [`WaitCell`], a cell that stores a *single* waiting task's [`Waker`], so
43    //!   that the task can be woken by another task,
44    //! - [`WaitQueue`], a queue of waiting tasks, which are woken in first-in,
45    //!   first-out order
46    //! - [`WaitMap`], a set of waiting tasks associated with keys, in which a task
47    //!   can be woken by its key
48    //!
49    //! **Note**: `maitake`'s synchronization primitives *do not* require the
50    //! `maitake` runtime, and can be used with any async executor. Therefore,
51    //! they are provided by a separate [`maitake-sync`] crate, which can be
52    //! used without depending on the rest of the `maitake` runtime. This module
53    //! re-exports these APIs from [`maitake-sync`].
54    //!
55    //! [primitives]: https://wiki.osdev.org/Synchronization_Primitives
56    //! [tasks]: crate::task
57    //! [mutual exclusion lock]: https://en.wikipedia.org/wiki/Mutual_exclusion
58    //! [readers-writer lock]: https://en.wikipedia.org/wiki/Readers%E2%80%93writer_lock
59    //! [counting semaphore]: https://en.wikipedia.org/wiki/Semaphore_(programming)
60    //! [`Waker`]: core::task::Waker
61    //! [`maitake-sync`]: https://crates.io/crates/maitake-sync
62    pub use maitake_sync::*;
63}