]>
git.proxmox.com Git - rustc.git/blob - vendor/lazy_static-0.2.11/src/lib.rs
1 // Copyright 2016 lazy-static.rs Developers
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.
9 A macro for declaring lazily evaluated statics.
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.
20 [pub] static ref NAME_1: TYPE_1 = EXPR_1;
21 [pub] static ref NAME_2: TYPE_2 = EXPR_2;
23 [pub] static ref NAME_N: TYPE_N = EXPR_N;
27 Attributes (including doc comments) are supported as well:
31 # extern crate lazy_static;
34 /// This is an example for using doc comment attributes
35 static ref EXAMPLE: u8 = 42;
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.)
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.
50 Apart from the lazy initialization, the resulting "static ref" variables
51 have generally the same properties as regular "static" variables:
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.
62 extern crate lazy_static;
64 use std::collections::HashMap;
67 static ref HASHMAP: HashMap<u32, &'static str> = {
68 let mut m = HashMap::new();
74 static ref COUNT: usize = HASHMAP.len();
75 static ref NUMBER: u32 = times_two(21);
78 fn times_two(n: u32) -> u32 { n * 2 }
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);
87 # Implementation details
89 The `Deref` implementation uses a hidden static variable that is guarded by a atomic check on each access. On stable Rust, the macro may need to allocate each static on the heap.
93 #![cfg_attr(feature= "spin_no_std" , feature(const_fn))]
94 #![cfg_attr(feature= "nightly" , feature(unreachable))]
96 #![doc(html_root_url = "https://docs.rs/lazy_static/0.2.11" )]
99 #[cfg(not(feature= "nightly" ))]
103 #[cfg(all(feature= "nightly" , not(feature= "spin_no_std" )))]
104 #[path= "nightly_lazy.rs" ]
108 #[cfg(all(feature= "nightly" , feature= "spin_no_std" ))]
109 #[path= "core_lazy.rs" ]
114 pub use core
:: ops
:: Deref
as __Deref
;
118 macro_rules
! __lazy_static_internal
{
119 // optional visibility restrictions are wrapped in `()` to allow for
120 // explicitly passing otherwise implicit information about private items
121 ( $
( #[$attr:meta])* ($($vis:tt)*) static ref $N:ident : $T:ty = $e:expr; $($t:tt)*) => {
122 __lazy_static_internal
!( @MAKE TY
, $
( #[$attr])*, ($($vis)*), $N);
123 __lazy_static_internal
!( @TAIL
, $N
: $T
= $e
);
124 lazy_static
!( $
( $t
)*);
126 ( @TAIL
, $N
: ident
: $T
: ty
= $e
: expr
) => {
127 impl $
crate :: __Deref
for $N
{
129 #[allow(unsafe_code)]
130 fn deref (& self ) -> & $T
{
133 fn __static_ref_initialize () -> $T { $e }
136 unsafe fn __stability () -> & '
static $T
{
137 __lazy_static_create
!( LAZY
, $T
);
138 LAZY
. get ( __static_ref_initialize
)
144 impl $
crate :: LazyStatic
for $N
{
145 fn initialize ( lazy
: & Self ) {
150 // `vis` is wrapped in `()` to prevent parsing ambiguity
151 ( @MAKE TY
, $
( #[$attr:meta])*, ($($vis:tt)*), $N:ident) => {
152 #[allow(missing_copy_implementations)]
153 #[allow(non_camel_case_types)]
156 $
( $vis
)* struct $N {__private_field: ()}
158 $
( $vis
)* static $N
: $N
= $N {__private_field: ()}
;
164 macro_rules
! lazy_static
{
165 ( $
( #[$attr:meta])* static ref $N:ident : $T:ty = $e:expr; $($t:tt)*) => {
166 // use `()` to explicitly forward the information about private items
167 __lazy_static_internal
!( $
( #[$attr])* () static ref $N : $T = $e; $($t)*);
169 ( $
( #[$attr:meta])* pub static ref $N:ident : $T:ty = $e:expr; $($t:tt)*) => {
170 __lazy_static_internal
!( $
( #[$attr])* (pub) static ref $N : $T = $e; $($t)*);
172 ( $
( #[$attr:meta])* pub ($($vis:tt)+) static ref $N:ident : $T:ty = $e:expr; $($t:tt)*) => {
173 __lazy_static_internal
!( $
( #[$attr])* (pub ($($vis)+)) static ref $N : $T = $e; $($t)*);
178 /// Support trait for enabling a few common operation on lazy static values.
180 /// This is implemented by each defined lazy static, and
181 /// used by the free functions in this crate.
182 pub trait LazyStatic
{
184 fn initialize ( lazy
: & Self );
187 /// Takes a shared reference to a lazy static and initializes
188 /// it if it has not been already.
190 /// This can be used to control the initialization point of a lazy static.
196 /// extern crate lazy_static;
199 /// static ref BUFFER: Vec<u8> = (0..65537).collect();
203 /// lazy_static::initialize(&BUFFER);
206 /// work_with_initialized_data(&BUFFER);
208 /// # fn work_with_initialized_data(_: &[u8]) {}
210 pub fn initialize
< T
: LazyStatic
>( lazy
: & T
) {
211 LazyStatic
:: initialize ( lazy
);