1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80

//! This crate provides a set of synchronized initialization primitives, which
//! are primarily useful for lazy and one-time initialization of static
//! variables.
//!
//! All types exported through the [`noblock`] and [`spin`] modules are fully
//! `#[no_std]` compatible.
//!
//! # Synchronization Primitives
//!
//! With the `std` cargo feature enabled (which is the default setting), this
//! crate provides the [`Once`], [`OnceCell`] and [`Lazy`] types and the
//! equivalents of these types using spin-locks in the `spin` sub-module.
//!
//! ## Lazy
//!
//! The [`Lazy`] type has the same functionality as the `lazy_static!` macro,
//! but works without any macros.
//!
//! ## Once
//!
//! This type is very similar to the `std::sync::Once` type in the standard
//! library, but features a richer API.
//!
//! ## OnceCell
//!
//! A cell type with interior mutability that can be only written to once and
//! only allows read access to the contained data after initialization.
//!
//! # Credits
//!
//! Inspiration for this crate is heavily drawn from [`once_cell`](https://crates.io/crates/once_cell),
//! but features clear distinctions between blocking and non-blocking operations
//! and support for `#[no_std]` environments out of the box, by offering
//! additional synchronization primitives using spin-locks instead of OS reliant
//! blocking mechanisms.
//! Unlike many other crates, support for the `#[no_std]` compatible types is
//! not mutually exclusive with using the types relying on the presence of the
//! standard library.
//!
//! The idea for the implementation of the [`Once`]/[`OnceCell`] types is also
//! directly inspired by the implementation in the standard library.
//! The reasoning behind re-implementing [`Once`] is the fairly restricted and
//! partly unstable API of the version in the standard library.

#![cfg_attr(all(not(test), not(doctest), not(feature = "std")), no_std)]
#![deny(missing_docs)]

#[cfg(test)]
#[macro_use]
mod tests;

pub mod noblock;
pub mod spin;

/// Re-exports of internal generic type for the purpose of accessing their
/// documentation.
pub mod doc {
    pub use crate::cell::OnceCell;
    pub use crate::lazy::Lazy;
}

mod cell;
mod lazy;
mod state;

#[cfg(feature = "std")]
mod park;

pub use crate::cell::{TryGetError, TryInitError};

#[cfg(feature = "std")]
pub use crate::park::Lazy;
#[cfg(feature = "std")]
pub use crate::park::Once;
#[cfg(feature = "std")]
pub use crate::park::OnceCell;

/// Whenever a poisoned [`OnceCell`] is encountered, the panic is propagated
/// with this message.
const POISON_PANIC_MSG: &str = "OnceCell instance has been poisoned.";