conquer_util/lib.rs
1//! Common utilities for lock-free and concurrent programming.
2//!
3//! This crate provides fine-grained control over its contents through cargo
4//! feature flags:
5//!
6//! # `#![no_std]` Compatibility
7//!
8//! By default, `conquer-utils` enables the `std` feature, which links against
9//! the standard library and requires e.g. OS support.
10//! Disabling this feature allows this crate to be used in `#![no_std]`
11//! environments.
12//! If the targeted environment does not allow using `std` features but provides
13//! the means for dynamic memory allocation, the `alloc` feature can be used to
14//! enable additional functionality.
15//! Note that the `std` feature implicitly activates all `alloc` features as
16//! well.
17//!
18//! # Features
19//!
20//! The following utilities are provided when compiling this crate with the
21//! appropriate feature flags:
22//!
23//! ## Alignment
24//!
25//! When the `align` feature is enabled, the same-named module can be used,
26//! which provides generic thin wrapper types for specifying the alignment for
27//! instances of the respective type.
28//! Particularly useful is the [`CacheAligned`][crate::align::CacheAligned]
29//! type, which forces an alignment to the size of a cache-line.
30//! This helps to avoid *false sharing*.
31//! The provided types can be used in their entirety in a `#![no_std]`
32//! environment.
33//!
34//! ## Back-Off
35//!
36//! By enabling the `back-off` feature, this crate provides the
37//! [`BackOff`][crate::BackOff] type, which can be used to perform exponential
38//! back-off in e.g. spin-loops.
39//! This type is `#![no_std]` compatible, but provides additional features when
40//! the `std` feature is also enabled.
41//!
42//! ### Randomized Exponential Back-Off
43//!
44//! Enabling the `random` feature in addition to the `back-off` feature pulls in
45//! the `rand` dependency and additionally adds `#![no_std]` compatible
46//! randomized exponential back-off, which adds some slight variations the time
47//! each thread spends spinning.
48//! This may help avoid issues such as *convoying*.
49//!
50//! ## TLS
51//!
52//! Enabling the `tls` feature makes the
53//! [`BoundedThreadLocal`][crate::BoundedThreadLocal] available, which is useful
54//! for iterable per-object thread local storage for bounded numbers of threads.
55
56#![cfg_attr(not(feature = "std"), no_std)]
57#![warn(missing_docs)]
58
59#[cfg(all(feature = "alloc", not(feature = "std")))]
60extern crate alloc;
61
62#[cfg(feature = "align")]
63pub mod align;
64
65#[cfg(feature = "back-off")]
66mod backoff;
67#[cfg(feature = "tls")]
68mod local;
69
70#[cfg(feature = "back-off")]
71pub use crate::backoff::BackOff;
72#[cfg(feature = "tls")]
73pub use crate::local::{BoundedThreadLocal, BoundsError, IntoIter, Local, Token};