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