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