/rust/registry/src/index.crates.io-1949cf8c6b5b557f/lazy_static-1.5.1/src/lib.rs

Source
// Copyright 2016 lazy-static.rs Developers
//
// Licensed under the Apache License, Version 2.0, <LICENSE-APACHE or
// https://apache.org/licenses/LICENSE-2.0> or the MIT license <LICENSE-MIT or
// https://opensource.org/licenses/MIT>, at your option. This file may not be
// copied, modified, or distributed except according to those terms.

/*!
<div class="warning">

This crate has been replaced by the [`LazyLock`] type, which is stable since Rust 1.80.0 with a slightly different syntax. Barring breakages and security fixes, this crate will no longer be updated.

[`LazyLock`]: https://doc.rust-lang.org/std/sync/struct.LazyLock.html

</div>

A macro for declaring lazily evaluated statics.

Using this macro, it is possible to have `static`s that require code to be
executed at runtime in order to be initialized.
This includes anything requiring heap allocations, like vectors or hash maps,
as well as anything that requires function calls to be computed.

# Syntax

```ignore
lazy_static! {
    [pub] static ref NAME_1: TYPE_1 = EXPR_1;
    [pub] static ref NAME_2: TYPE_2 = EXPR_2;
    ...
    [pub] static ref NAME_N: TYPE_N = EXPR_N;
}
```

Attributes (including doc comments) are supported as well:

```rust
use lazy_static::lazy_static;

# fn main() {
lazy_static! {
    /// This is an example of using doc comment attributes
    static ref EXAMPLE: u8 = 42;
}
# }
```

# Semantics

For a given `static ref NAME: TYPE = EXPR;`, the macro generates a unique type that
implements `Deref<TYPE>` and stores it in a static with name `NAME`. (Attributes end up
attaching to this type.)

On first deref, `EXPR` gets evaluated and stored internally, such that all further derefs
can return a reference to the same object. Note that this can lead to deadlocks
if you have multiple lazy statics that depend on each other in their initialization.

Apart from the lazy initialization, the resulting "static ref" variables
have generally the same properties as regular "static" variables:

- Any type in them needs to fulfill the `Sync` trait.
- If the type has a destructor, then it will not run when the process exits.

# Example

Using the macro:

```rust
use lazy_static::lazy_static;
use std::collections::HashMap;

lazy_static! {
    static ref HASHMAP: HashMap<u32, &'static str> = {
        let mut m = HashMap::new();
        m.insert(0, "foo");
        m.insert(1, "bar");
        m.insert(2, "baz");
        m
    };
    static ref COUNT: usize = HASHMAP.len();
    static ref NUMBER: u32 = times_two(21);
}

fn times_two(n: u32) -> u32 { n * 2 }

fn main() {
    println!("The map has {} entries.", *COUNT);
    println!("The entry for `0` is \"{}\".", HASHMAP.get(&0).unwrap());
    println!("A expensive calculation on a static results in: {}.", *NUMBER);
}
```

# Implementation details

The `Deref` implementation uses a hidden static variable that is guarded by an atomic check on each access.

# Cargo features

This crate provides one cargo feature:

- `spin_no_std`: This allows using this crate in a no-std environment, by depending on the standalone `spin` crate.

*/

#![doc(html_root_url = "https://docs.rs/lazy_static/1.5.1")]
#![no_std]

#[cfg(doctest)]
#[macro_use]
extern crate doc_comment;

#[cfg(doctest)]
doctest!("../README.md");

#[cfg_attr(feature = "spin_no_std", path = "core_lazy.rs")]
#[cfg_attr(not(feature = "spin_no_std"), path = "inline_lazy.rs")]
#[doc(hidden)]
pub mod lazy;

#[doc(hidden)]
pub use core::ops::Deref as __Deref;

#[macro_export(local_inner_macros)]
#[doc(hidden)]
macro_rules! __lazy_static_internal {
    // optional visibility restrictions are wrapped in `()` to allow for
    // explicitly passing otherwise implicit information about private items
    ($(#[$attr:meta])* ($($vis:tt)*) static ref $N:ident : $T:ty = $e:expr; $($t:tt)*) => {
        __lazy_static_internal!(@MAKE TY, $(#[$attr])*, ($($vis)*), $N);
        __lazy_static_internal!(@TAIL, $N : $T = $e);
        lazy_static!($($t)*);
    };
    (@TAIL, $N:ident : $T:ty = $e:expr) => {
        impl $crate::__Deref for $N {
            type Target = $T;
            fn deref(&self) -> &$T {
                #[inline(always)]
                fn __static_ref_initialize() -> $T { $e }

                #[inline(always)]
                fn __stability() -> &'static $T {
                    __lazy_static_create!(LAZY, $T);
                    LAZY.get(__static_ref_initialize)
                }
                __stability()
            }
        }
        impl $crate::LazyStatic for $N {
            fn initialize(lazy: &Self) {
                let _ = &**lazy;
            }
        }
    };
    // `vis` is wrapped in `()` to prevent parsing ambiguity
    (@MAKE TY, $(#[$attr:meta])*, ($($vis:tt)*), $N:ident) => {
        #[allow(missing_copy_implementations)]
        #[allow(non_camel_case_types)]
        #[allow(dead_code)]
        $(#[$attr])*
        $($vis)* struct $N {__private_field: ()}
        #[doc(hidden)]
        #[allow(non_upper_case_globals)]
        $($vis)* static $N: $N = $N {__private_field: ()};
    };
    () => ()
}

#[macro_export(local_inner_macros)]
macro_rules! lazy_static {
    ($(#[$attr:meta])* static ref $N:ident : $T:ty = $e:expr; $($t:tt)*) => {
        // use `()` to explicitly forward the information about private items
        __lazy_static_internal!($(#[$attr])* () static ref $N : $T = $e; $($t)*);
    };
    ($(#[$attr:meta])* pub static ref $N:ident : $T:ty = $e:expr; $($t:tt)*) => {
        __lazy_static_internal!($(#[$attr])* (pub) static ref $N : $T = $e; $($t)*);
    };
    ($(#[$attr:meta])* pub ($($vis:tt)+) static ref $N:ident : $T:ty = $e:expr; $($t:tt)*) => {
        __lazy_static_internal!($(#[$attr])* (pub ($($vis)+)) static ref $N : $T = $e; $($t)*);
    };
    () => ()
}

/// Support trait for enabling a few common operations on lazy static values.
///
/// This is implemented by each defined lazy static, and
/// used by the free functions in this crate.
pub trait LazyStatic {
    #[doc(hidden)]
    fn initialize(lazy: &Self);
}

/// Takes a shared reference to a lazy static and initializes
/// it if it has not been already.
///
/// This can be used to control the initialization point of a lazy static.
///
/// Example:
///
/// ```rust
/// use lazy_static::lazy_static;
///
/// lazy_static! {
///     static ref BUFFER: Vec<u8> = (0..255).collect();
/// }
///
/// fn main() {
///     lazy_static::initialize(&BUFFER);
///
///     // ...
///     work_with_initialized_data(&BUFFER);
/// }
/// # fn work_with_initialized_data(_: &[u8]) {}
/// ```
pub fn initialize<T: LazyStatic>(lazy: &T) {
    LazyStatic::initialize(lazy);
}

Coverage Report

Created: 2026-10-28 06:24

Line	Count	Source
1		// Copyright 2016 lazy-static.rs Developers
2		//
3		// Licensed under the Apache License, Version 2.0, <LICENSE-APACHE or
4		// https://apache.org/licenses/LICENSE-2.0> or the MIT license <LICENSE-MIT or
5		// https://opensource.org/licenses/MIT>, at your option. This file may not be
6		// copied, modified, or distributed except according to those terms.
7
8		/*!
9		<div class="warning">
10
11		This crate has been replaced by the [`LazyLock`] type, which is stable since Rust 1.80.0 with a slightly different syntax. Barring breakages and security fixes, this crate will no longer be updated.
12
13		[`LazyLock`]: https://doc.rust-lang.org/std/sync/struct.LazyLock.html
14
15		</div>
16
17		A macro for declaring lazily evaluated statics.
18
19		Using this macro, it is possible to have `static`s that require code to be
20		executed at runtime in order to be initialized.
21		This includes anything requiring heap allocations, like vectors or hash maps,
22		as well as anything that requires function calls to be computed.
23
24		# Syntax
25
26		```ignore
27		lazy_static! {
28		[pub] static ref NAME_1: TYPE_1 = EXPR_1;
29		[pub] static ref NAME_2: TYPE_2 = EXPR_2;
30		...
31		[pub] static ref NAME_N: TYPE_N = EXPR_N;
32		}
33		```
34
35		Attributes (including doc comments) are supported as well:
36
37		```rust
38		use lazy_static::lazy_static;
39
40		# fn main() {
41		lazy_static! {
42		/// This is an example of using doc comment attributes
43		static ref EXAMPLE: u8 = 42;
44		}
45		# }
46		```
47
48		# Semantics
49
50		For a given `static ref NAME: TYPE = EXPR;`, the macro generates a unique type that
51		implements `Deref<TYPE>` and stores it in a static with name `NAME`. (Attributes end up
52		attaching to this type.)
53
54		On first deref, `EXPR` gets evaluated and stored internally, such that all further derefs
55		can return a reference to the same object. Note that this can lead to deadlocks
56		if you have multiple lazy statics that depend on each other in their initialization.
57
58		Apart from the lazy initialization, the resulting "static ref" variables
59		have generally the same properties as regular "static" variables:
60
61		- Any type in them needs to fulfill the `Sync` trait.
62		- If the type has a destructor, then it will not run when the process exits.
63
64		# Example
65
66		Using the macro:
67
68		```rust
69		use lazy_static::lazy_static;
70		use std::collections::HashMap;
71
72		lazy_static! {
73		static ref HASHMAP: HashMap<u32, &'static str> = {
74		let mut m = HashMap::new();
75		m.insert(0, "foo");
76		m.insert(1, "bar");
77		m.insert(2, "baz");
78		m
79		};
80		static ref COUNT: usize = HASHMAP.len();
81		static ref NUMBER: u32 = times_two(21);
82		}
83
84		fn times_two(n: u32) -> u32 { n * 2 }
85
86		fn main() {
87		println!("The map has {} entries.", *COUNT);
88		println!("The entry for `0` is \"{}\".", HASHMAP.get(&0).unwrap());
89		println!("A expensive calculation on a static results in: {}.", *NUMBER);
90		}
91		```
92
93		# Implementation details
94
95		The `Deref` implementation uses a hidden static variable that is guarded by an atomic check on each access.
96
97		# Cargo features
98
99		This crate provides one cargo feature:
100
101		- `spin_no_std`: This allows using this crate in a no-std environment, by depending on the standalone `spin` crate.
102
103		*/
104
105		#![doc(html_root_url = "https://docs.rs/lazy_static/1.5.1")]
106		#![no_std]
107
108		#[cfg(doctest)]
109		#[macro_use]
110		extern crate doc_comment;
111
112		#[cfg(doctest)]
113		doctest!("../README.md");
114
115		#[cfg_attr(feature = "spin_no_std", path = "core_lazy.rs")]
116		#[cfg_attr(not(feature = "spin_no_std"), path = "inline_lazy.rs")]
117		#[doc(hidden)]
118		pub mod lazy;
119
120		#[doc(hidden)]
121		pub use core::ops::Deref as __Deref;
122
123		#[macro_export(local_inner_macros)]
124		#[doc(hidden)]
125		macro_rules! __lazy_static_internal {
126		// optional visibility restrictions are wrapped in `()` to allow for
127		// explicitly passing otherwise implicit information about private items
128		($(#[$attr:meta])* ($($vis:tt)) static ref $N:ident : $T:ty = $e:expr; $($t:tt)) => {
129		__lazy_static_internal!(@MAKE TY, $(#[$attr]), ($($vis)), $N);
130		__lazy_static_internal!(@TAIL, $N : $T = $e);
131		lazy_static!($($t)*);
132		};
133		(@TAIL, $N:ident : $T:ty = $e:expr) => {
134		impl $crate::__Deref for $N {
135		type Target = $T;
136	0	fn deref(&self) -> &$T {
137		#[inline(always)]
138	0	fn __static_ref_initialize() -> $T { $e } Unexecuted instantiation: <vsock::stream::CONNECTION_PKT_QUEUES as core::ops::deref::Deref>::deref::__static_ref_initialize Unexecuted instantiation: <vsock::stream::BINDING_PKT_QUEUES as core::ops::deref::Deref>::deref::__static_ref_initialize Unexecuted instantiation: <vsock::transport::virtio_pci::VSOCK_DEVICE as core::ops::deref::Deref>::deref::__static_ref_initialize Unexecuted instantiation: <vsock::stream::UNUSED_PORT_COUNTER as core::ops::deref::Deref>::deref::__static_ref_initialize Unexecuted instantiation: <vsock::stream::USED_PORT as core::ops::deref::Deref>::deref::__static_ref_initialize Unexecuted instantiation: <pci::mmio::MMIO32 as core::ops::deref::Deref>::deref::__static_ref_initialize Unexecuted instantiation: <pci::mmio::MMIO64 as core::ops::deref::Deref>::deref::__static_ref_initialize Unexecuted instantiation: <td_payload::mm::MEMORY_MAP as core::ops::deref::Deref>::deref::__static_ref_initialize Unexecuted instantiation: <td_payload::arch::x86_64::cet::ISST as core::ops::deref::Deref>::deref::__static_ref_initialize Unexecuted instantiation: <td_payload::arch::x86_64::gdt::GDT as core::ops::deref::Deref>::deref::__static_ref_initialize Unexecuted instantiation: <td_payload::arch::x86_64::gdt::TSS as core::ops::deref::Deref>::deref::__static_ref_initialize Unexecuted instantiation: <td_exception::idt::INIT_IDT as core::ops::deref::Deref>::deref::__static_ref_initialize Unexecuted instantiation: <tdx_tdcall::tdx::SHARED_MASK as core::ops::deref::Deref>::deref::__static_ref_initialize
139
140		#[inline(always)]
141	0	fn __stability() -> &'static $T {
142		__lazy_static_create!(LAZY, $T);
143	0	LAZY.get(__static_ref_initialize)
144	0	} Unexecuted instantiation: <vsock::transport::virtio_pci::VSOCK_DEVICE as core::ops::deref::Deref>::deref::__stability Unexecuted instantiation: <vsock::stream::CONNECTION_PKT_QUEUES as core::ops::deref::Deref>::deref::__stability Unexecuted instantiation: <vsock::stream::BINDING_PKT_QUEUES as core::ops::deref::Deref>::deref::__stability Unexecuted instantiation: <vsock::stream::UNUSED_PORT_COUNTER as core::ops::deref::Deref>::deref::__stability Unexecuted instantiation: <vsock::stream::USED_PORT as core::ops::deref::Deref>::deref::__stability Unexecuted instantiation: <pci::mmio::MMIO32 as core::ops::deref::Deref>::deref::__stability Unexecuted instantiation: <pci::mmio::MMIO64 as core::ops::deref::Deref>::deref::__stability Unexecuted instantiation: <td_payload::mm::MEMORY_MAP as core::ops::deref::Deref>::deref::__stability Unexecuted instantiation: <td_payload::arch::x86_64::cet::ISST as core::ops::deref::Deref>::deref::__stability Unexecuted instantiation: <td_exception::idt::INIT_IDT as core::ops::deref::Deref>::deref::__stability Unexecuted instantiation: <tdx_tdcall::tdx::SHARED_MASK as core::ops::deref::Deref>::deref::__stability
145	0	__stability()
146	0	} Unexecuted instantiation: <vsock::transport::virtio_pci::VSOCK_DEVICE as core::ops::deref::Deref>::deref Unexecuted instantiation: <vsock::stream::CONNECTION_PKT_QUEUES as core::ops::deref::Deref>::deref Unexecuted instantiation: <vsock::stream::BINDING_PKT_QUEUES as core::ops::deref::Deref>::deref Unexecuted instantiation: <vsock::stream::UNUSED_PORT_COUNTER as core::ops::deref::Deref>::deref Unexecuted instantiation: <vsock::stream::USED_PORT as core::ops::deref::Deref>::deref Unexecuted instantiation: <pci::mmio::MMIO32 as core::ops::deref::Deref>::deref Unexecuted instantiation: <pci::mmio::MMIO64 as core::ops::deref::Deref>::deref Unexecuted instantiation: <td_payload::mm::MEMORY_MAP as core::ops::deref::Deref>::deref Unexecuted instantiation: <td_payload::arch::x86_64::cet::ISST as core::ops::deref::Deref>::deref Unexecuted instantiation: <td_exception::idt::INIT_IDT as core::ops::deref::Deref>::deref Unexecuted instantiation: <tdx_tdcall::tdx::SHARED_MASK as core::ops::deref::Deref>::deref
147		}
148		impl $crate::LazyStatic for $N {
149	0	fn initialize(lazy: &Self) {
150	0	let _ = &**lazy;
151	0	} Unexecuted instantiation: <vsock::transport::virtio_pci::VSOCK_DEVICE as lazy_static::LazyStatic>::initialize Unexecuted instantiation: <vsock::stream::CONNECTION_PKT_QUEUES as lazy_static::LazyStatic>::initialize Unexecuted instantiation: <vsock::stream::BINDING_PKT_QUEUES as lazy_static::LazyStatic>::initialize Unexecuted instantiation: <vsock::stream::UNUSED_PORT_COUNTER as lazy_static::LazyStatic>::initialize Unexecuted instantiation: <vsock::stream::USED_PORT as lazy_static::LazyStatic>::initialize Unexecuted instantiation: <pci::mmio::MMIO64 as lazy_static::LazyStatic>::initialize Unexecuted instantiation: <pci::mmio::MMIO32 as lazy_static::LazyStatic>::initialize Unexecuted instantiation: <td_payload::mm::MEMORY_MAP as lazy_static::LazyStatic>::initialize Unexecuted instantiation: <td_payload::arch::x86_64::cet::ISST as lazy_static::LazyStatic>::initialize Unexecuted instantiation: <td_exception::idt::INIT_IDT as lazy_static::LazyStatic>::initialize Unexecuted instantiation: <tdx_tdcall::tdx::SHARED_MASK as lazy_static::LazyStatic>::initialize
152		}
153		};
154		// `vis` is wrapped in `()` to prevent parsing ambiguity
155		(@MAKE TY, $(#[$attr:meta]), ($($vis:tt)), $N:ident) => {
156		#[allow(missing_copy_implementations)]
157		#[allow(non_camel_case_types)]
158		#[allow(dead_code)]
159		$(#[$attr])*
160		$($vis)* struct $N {__private_field: ()}
161		#[doc(hidden)]
162		#[allow(non_upper_case_globals)]
163		$($vis)* static $N: $N = $N {__private_field: ()};
164		};
165		() => ()
166		}
167
168		#[macro_export(local_inner_macros)]
169		macro_rules! lazy_static {
170		($(#[$attr:meta])* static ref $N:ident : $T:ty = $e:expr; $($t:tt)*) => {
171		// use `()` to explicitly forward the information about private items
172		__lazy_static_internal!($(#[$attr])* () static ref $N : $T = $e; $($t)*);
173		};
174		($(#[$attr:meta])* pub static ref $N:ident : $T:ty = $e:expr; $($t:tt)*) => {
175		__lazy_static_internal!($(#[$attr])* (pub) static ref $N : $T = $e; $($t)*);
176		};
177		($(#[$attr:meta])* pub ($($vis:tt)+) static ref $N:ident : $T:ty = $e:expr; $($t:tt)*) => {
178		__lazy_static_internal!($(#[$attr])* (pub ($($vis)+)) static ref $N : $T = $e; $($t)*);
179		};
180		() => ()
181		}
182
183		/// Support trait for enabling a few common operations on lazy static values.
184		///
185		/// This is implemented by each defined lazy static, and
186		/// used by the free functions in this crate.
187		pub trait LazyStatic {
188		#[doc(hidden)]
189		fn initialize(lazy: &Self);
190		}
191
192		/// Takes a shared reference to a lazy static and initializes
193		/// it if it has not been already.
194		///
195		/// This can be used to control the initialization point of a lazy static.
196		///
197		/// Example:
198		///
199		/// ```rust
200		/// use lazy_static::lazy_static;
201		///
202		/// lazy_static! {
203		/// static ref BUFFER: Vec<u8> = (0..255).collect();
204		/// }
205		///
206		/// fn main() {
207		/// lazy_static::initialize(&BUFFER);
208		///
209		/// // ...
210		/// work_with_initialized_data(&BUFFER);
211		/// }
212		/// # fn work_with_initialized_data(_: &[u8]) {}
213		/// ```
214		pub fn initialize<T: LazyStatic>(lazy: &T) {
215		LazyStatic::initialize(lazy);
216		}