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}