conquer_once/lib.rs
1//! This crate provides a set of synchronized initialization primitives, which
2//! are primarily useful for lazy and one-time initialization of static
3//! variables.
4//!
5//! All types exported through the [`noblock`] and [`spin`] modules are fully
6//! `#[no_std]` compatible.
7//!
8//! # Synchronization Primitives
9//!
10//! With the `std` cargo feature enabled (which is the default setting), this
11//! crate provides the [`Once`], [`OnceCell`] and [`Lazy`] types and the
12//! equivalents of these types using spin-locks in the `spin` sub-module.
13//!
14//! ## Lazy
15//!
16//! The [`Lazy`] type has the same functionality as the `lazy_static!` macro,
17//! but works without any macros.
18//!
19//! ## Once
20//!
21//! This type is very similar to the `std::sync::Once` type in the standard
22//! library, but features a richer API.
23//!
24//! ## OnceCell
25//!
26//! A cell type with interior mutability that can be only written to once and
27//! only allows read access to the contained data after initialization.
28//!
29//! # Credits
30//!
31//! Inspiration for this crate is heavily drawn from
32//! [`once_cell`](https://crates.io/crates/once_cell),
33//! but features clear distinctions between blocking and non-blocking operations
34//! and support for `#[no_std]` environments out of the box, by offering
35//! additional synchronization primitives using spin-locks instead of OS reliant
36//! blocking mechanisms.
37//! Unlike many other crates, support for the `#[no_std]` compatible types is
38//! not mutually exclusive with using the types relying on the presence of the
39//! standard library.
40//!
41//! The idea for the implementation of the [`Once`]/[`OnceCell`] types is also
42//! directly inspired by the implementation in the standard library.
43//! The reasoning behind re-implementing [`Once`] is the fairly restricted and
44//! partly unstable API of the version in the standard library.
45
46#![cfg_attr(all(not(test), not(feature = "std")), no_std)]
47#![deny(missing_docs)]
48#![forbid(clippy::undocumented_unsafe_blocks)]
49
50#[cfg(test)]
51#[macro_use]
52mod tests;
53
54pub mod noblock;
55pub mod spin;
56
57/// Re-exports of internal generic type for the purpose of accessing their
58/// documentation.
59pub mod doc {
60 pub use crate::cell::OnceCell;
61 pub use crate::lazy::Lazy;
62}
63
64mod cell;
65mod lazy;
66mod state;
67
68#[cfg(feature = "std")]
69mod park;
70
71pub use crate::cell::{TryGetError, TryInitError};
72
73#[cfg(feature = "std")]
74pub use crate::park::Lazy;
75#[cfg(feature = "std")]
76pub use crate::park::Once;
77#[cfg(feature = "std")]
78pub use crate::park::OnceCell;
79
80const POISON_PANIC_MSG: &str = "OnceCell instance has been poisoned.";