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//! # let spawn = |_| {};
57//! # let sleep = |_| async {};
58//!
59//! use compact_waitgroup::{GroupTokenExt, WaitGroup};
60//!
61//! let (wg, factory) = WaitGroup::new();
62//!
63//! for (i, token) in std::iter::repeat_n(factory.into_token(), 8).enumerate() {
64//! let task = async move {
65//! println!("Task {i} started");
66//! // Long-running task...
67//! sleep(std::time::Duration::from_secs(1)).await;
68//! println!("Task {i} finished");
69//! };
70//! spawn(task.release_on_ready(token));
71//! }
72//!
73//! // Wait for all tasks to complete
74//! # futures_executor::block_on(async {
75//! wg.await;
76//! # });
77//! ```
78//!
79//! # Memory Layout
80//!
81//! This crate is designed to be extremely lightweight. The memory footprint
82//! depends on the architecture and the enabled features.
83//!
84//! By default, [`MonoWaitGroup`] shares the same underlying memory structure as
85//! [`WaitGroup`]. However, this means [`MonoWaitGroup`] carries a `usize` field
86//! for reference counting of workers, which is redundant for the singly-owned
87//! [`MonoGroupToken`].
88//!
89//! Enabling the `compact-mono` feature changes the internal definition of
90//! [`MonoWaitGroup`]. It switches to a dedicated, stripped-down layout that
91//! removes the reference counter.
92//!
93//! | Component | Default (64-bit) | With `compact-mono` | Saving |
94//! | ------------------- | ---------------- | ------------------- | ----------- |
95//! | **[`WaitGroup`]** | 32 bytes | 32 bytes | 0 bytes |
96//! | **[`MonoWaitGroup`]** | **32 bytes** | **24 bytes** | **8 bytes** |
97#![no_std]
98extern crate alloc;
99
100mod ext;
101mod group;
102mod layout;
103mod sync;
104mod twin_ref;
105mod utils;
106
107pub use crate::{
108 ext::{GroupTokenExt, GroupTokenFuncExt, GroupTokenReleaseOnDrop, GroupTokenReleaseOnReady},
109 group::{GroupToken, GroupTokenFactory, MonoGroupToken, MonoWaitGroup, WaitGroup},
110};
111
112#[cfg(test)]
113mod tests;