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

compact_waitgroup/
lib.rs
