compact_waitgroup/lib.rs
1//! A compact asynchronous `WaitGroup` synchronization primitive.
2//!
3//! This crate is designed to be lightweight and executor-agnostic. It works
4//! with any `async` runtime and supports `no_std` environments (requires
5//! `alloc`).
6//!
7//! # Usage
8//!
9//! ## [`MonoWaitGroup`]
10//!
11//! ```rust
12//! # use compact_waitgroup::MonoWaitGroup;
13//! # futures_executor::block_on(async {
14//! let (wg, token) = MonoWaitGroup::new();
15//! assert!(!wg.is_done());
16//! std::thread::spawn(move || {
17//! // Long-running task
18//! token.release();
19//! });
20//! // Wait for the task to complete
21//! wg.await;
22//! # });
23//! ```
24//!
25//! ## [`WaitGroup`]
26//!
27//! ```rust
28//! # use compact_waitgroup::WaitGroup;
29//! # futures_executor::block_on(async {
30//! let (wg, factory) = WaitGroup::new();
31//! factory.scope(|token| {
32//! let token_cloned = token.clone();
33//! assert!(!wg.is_done());
34//! std::thread::spawn(move || {
35//! // Long-running task
36//! token_cloned.release();
37//! });
38//! std::thread::spawn(move || {
39//! // Another long-running task
40//! token.release();
41//! });
42//! });
43//! // Wait for all tasks to complete
44//! wg.await;
45//! # });
46//! ```
47//!
48//! ## With `async` Runtime
49//!
50//! ```rust
51//! # use core::{iter::repeat_n, mem::drop as spawn, time::Duration};
52//! # use compact_waitgroup::{GroupTokenExt, WaitGroup};
53//! # let sleep = |_| async {};
54//! # futures_executor::block_on(async {
55//! let (wg, factory) = WaitGroup::new();
56//! for (i, token) in repeat_n(factory.into_token(), 8).enumerate() {
57//! let task = async move {
58//! println!("Task {i} started");
59//! // Long-running task...
60//! sleep(Duration::from_secs(1)).await;
61//! println!("Task {i} finished");
62//! }
63//! .release_on_ready(token);
64//! spawn(task);
65//! }
66//! // Wait for all tasks to complete
67//! wg.await;
68//! # });
69//! ```
70//!
71//! # Memory Layout
72//!
73//! This crate is designed to be extremely lightweight. The memory footprint
74//! depends on the architecture and the enabled features.
75//!
76//! By default, [`MonoWaitGroup`] shares the same underlying memory structure as
77//! [`WaitGroup`]. However, this means [`MonoWaitGroup`] carries a `usize` field
78//! for reference counting of workers, which is redundant for the singly-owned
79//! [`MonoGroupToken`].
80//!
81//! Enabling the `compact-mono` feature changes the internal definition of
82//! [`MonoWaitGroup`]. It switches to a dedicated, stripped-down layout that
83//! removes the reference counter.
84//!
85//! | Component | Default (64-bit) | With `compact-mono` | Saving |
86//! | ------------------- | ---------------- | ------------------- | ----------- |
87//! | **`WaitGroup`** | 32 bytes | 32 bytes | 0 bytes |
88//! | **`MonoWaitGroup`** | **32 bytes** | **24 bytes** | **8 bytes** |
89#![no_std]
90extern crate alloc;
91
92mod ext;
93mod group;
94mod layout;
95mod sync;
96mod twin_ref;
97mod utils;
98
99pub use crate::{
100 ext::{GroupTokenExt, GroupTokenReleaseOnDrop, GroupTokenReleaseOnReady},
101 group::{GroupToken, MonoGroupToken, MonoWaitGroup, WaitGroup},
102};
103
104#[cfg(test)]
105mod tests;