| 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 |
/*! |
| 9 |
A macro for declaring lazily evaluated statics. |
| 10 |
|
| 11 |
Using this macro, it is possible to have `static`s that require code to be |
| 12 |
executed at runtime in order to be initialized. |
| 13 |
This includes anything requiring heap allocations, like vectors or hash maps, |
| 14 |
as well as anything that requires function calls to be computed. |
| 15 |
|
| 16 |
# Syntax |
| 17 |
|
| 18 |
```ignore |
| 19 |
lazy_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 |
|
| 27 |
Attributes (including doc comments) are supported as well: |
| 28 |
|
| 29 |
```rust |
| 30 |
# #[macro_use] |
| 31 |
# extern crate lazy_static; |
| 32 |
# fn main() { |
| 33 |
lazy_static! { |
| 34 |
/// This is an example for using doc comment attributes |
| 35 |
static ref EXAMPLE: u8 = 42; |
| 36 |
} |
| 37 |
# } |
| 38 |
``` |
| 39 |
|
| 40 |
# Semantics |
| 41 |
|
| 42 |
For a given `static ref NAME: TYPE = EXPR;`, the macro generates a unique type that |
| 43 |
implements `Deref<TYPE>` and stores it in a static with name `NAME`. (Attributes end up |
| 44 |
attaching to this type.) |
| 45 |
|
| 46 |
On first deref, `EXPR` gets evaluated and stored internally, such that all further derefs |
| 47 |
can return a reference to the same object. Note that this can lead to deadlocks |
| 48 |
if you have multiple lazy statics that depend on each other in their initialization. |
| 49 |
|
| 50 |
Apart from the lazy initialization, the resulting "static ref" variables |
| 51 |
have 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 |
|
| 58 |
Using the macro: |
| 59 |
|
| 60 |
```rust |
| 61 |
#[macro_use] |
| 62 |
extern crate lazy_static; |
| 63 |
|
| 64 |
use std::collections::HashMap; |
| 65 |
|
| 66 |
lazy_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 |
|
| 78 |
fn times_two(n: u32) -> u32 { n * 2 } |
| 79 |
|
| 80 |
fn 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 |
|
| 89 |
The `Deref` implementation uses a hidden static variable that is guarded by an atomic check on each access. |
| 90 |
|
| 91 |
# Cargo features |
| 92 |
|
| 93 |
This 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)] |
| 105 |
pub mod lazy; |
| 106 |
|
| 107 |
#[cfg(test)] |
| 108 |
#[macro_use] |
| 109 |
extern crate doc_comment; |
| 110 |
|
| 111 |
#[cfg(test)] |
| 112 |
doctest!("../README.md"); |
| 113 |
|
| 114 |
#[cfg(feature = "spin_no_std")] |
| 115 |
#[path="core_lazy.rs"] |
| 116 |
#[doc(hidden)] |
| 117 |
pub mod lazy; |
| 118 |
|
| 119 |
#[doc(hidden)] |
| 120 |
pub use core::ops::Deref as __Deref; |
| 121 |
|
| 122 |
#[macro_export(local_inner_macros)] |
| 123 |
#[doc(hidden)] |
| 124 |
macro_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)] |
| 167 |
macro_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. |
| 185 |
pub 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 |
/// ``` |
| 213 |
pub fn initialize<T: LazyStatic>(lazy: &T) { |
| 214 |
LazyStatic::initialize(lazy); |
| 215 |
} |