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, handle) = MonoWaitGroup::new();
15//! assert!(!wg.is_done());
16//! std::thread::spawn(move || {
17//! // Long-running task
18//! handle.done();
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, handle) = WaitGroup::new();
31//! let handle_cloned = handle.clone();
32//! assert!(!wg.is_done());
33//! std::thread::spawn(move || {
34//! // Long-running task
35//! handle_cloned.done();
36//! });
37//! std::thread::spawn(move || {
38//! // Another long-running task
39//! handle.done();
40//! });
41//! // Wait for all tasks to complete
42//! wg.await;
43//! # });
44//! ```
45//!
46//! # Memory Layout
47//!
48//! This crate is designed to be extremely lightweight. The memory footprint
49//! depends on the architecture and the enabled features.
50//!
51//! By default, [`MonoWaitGroup`] shares the same underlying memory structure as
52//! [`WaitGroup`]. However, this means [`MonoWaitGroup`] carries a `usize` field
53//! for reference counting of workers, which is redundant for the singly-owned
54//! [`MonoWorkerHandle`].
55//!
56//! Enabling the `compact-mono` feature changes the internal definition of
57//! [`MonoWaitGroup`]. It switches to a dedicated, stripped-down layout that
58//! removes the reference counter.
59//!
60//! | Component | Default (64-bit) | With `compact-mono` | Saving |
61//! | ------------------- | ---------------- | ------------------- | ----------- |
62//! | **`WaitGroup`** | 32 bytes | 32 bytes | 0 bytes |
63//! | **`MonoWaitGroup`** | **32 bytes** | **24 bytes** | **8 bytes** |
64#![no_std]
65extern crate alloc;
66
67mod core_impl;
68mod state;
69mod twin_ref;
70mod utils;
71mod wait_group;
72mod with_worker_handle;
73
74pub use crate::{
75 wait_group::{MonoWaitGroup, MonoWorkerHandle, WaitGroup, WorkerHandle},
76 with_worker_handle::{WithWorkerHandle, WithWorkerHandleFuture},
77};
78
79#[cfg(test)]
80mod tests;