2024-07-26 09:42:18 +00:00
<!DOCTYPE html> < html lang = "en" > < head > < meta charset = "utf-8" > < meta name = "viewport" content = "width=device-width, initial-scale=1.0" > < meta name = "generator" content = "rustdoc" > < meta name = "description" content = "A macro for declaring lazily evaluated statics." > < title > lazy_static - Rust< / title > < script > if ( window . location . protocol !== "file:" ) document . head . insertAdjacentHTML ( "beforeend" , "SourceSerif4-Regular-46f98efaafac5295.ttf.woff2,FiraSans-Regular-018c141bf0843ffd.woff2,FiraSans-Medium-8f9a781e4970d388.woff2,SourceCodePro-Regular-562dcc5011b6de7d.ttf.woff2,SourceCodePro-Semibold-d899c5a5c4aeb14a.ttf.woff2" . split ( "," ) . map ( f => ` <link rel="preload" as="font" type="font/woff2" crossorigin href="../static.files/ ${ f } "> ` ) . join ( "" ) ) < / script > < link rel = "stylesheet" href = "../static.files/normalize-76eba96aa4d2e634.css" > < link rel = "stylesheet" href = "../static.files/rustdoc-dd39b87e5fcfba68.css" > < meta name = "rustdoc-vars" data-root-path = "../" data-static-root-path = "../static.files/" data-current-crate = "lazy_static" data-themes = "" data-resource-suffix = "" data-rustdoc-version = "1.80.0 (051478957 2024-07-21)" data-channel = "1.80.0" data-search-js = "search-d52510db62a78183.js" data-settings-js = "settings-4313503d2e1961c2.js" > < script src = "../static.files/storage-118b08c4c78b968e.js" > < / script > < script defer src = "../crates.js" > < / script > < script defer src = "../static.files/main-20a3ad099b048cf2.js" > < / script > < noscript > < link rel = "stylesheet" href = "../static.files/noscript-df360f571f6edeae.css" > < / noscript > < link rel = "alternate icon" type = "image/png" href = "../static.files/favicon-32x32-422f7d1d52889060.png" > < link rel = "icon" type = "image/svg+xml" href = "../static.files/favicon-2c020d218678b618.svg" > < / head > < body class = "rustdoc mod crate" > <!-- [if lte IE 11]><div class="warning">This old browser is unsupported and will most likely display funky things.</div><![endif] --> < nav class = "mobile-topbar" > < button class = "sidebar-menu-toggle" title = "show sidebar" > < / button > < / nav > < nav class = "sidebar" > < div class = "sidebar-crate" > < h2 > < a href = "../lazy_static/index.html" > lazy_static< / a > < span class = "version" > 1.5.0< / span > < / h2 > < / div > < div class = "sidebar-elems" > < ul class = "block" > < li > < a id = "all-types" href = "all.html" > All Items< / a > < / li > < / ul > < section > < ul class = "block" > < li > < a href = "#macros" > Macros< / a > < / li > < li > < a href = "#traits" > Traits< / a > < / li > < li > < a href = "#functions" > Functions< / a > < / li > < / ul > < / section > < / div > < / nav > < div class = "sidebar-resizer" > < / div > < main > < div class = "width-limiter" > < rustdoc-search > < / rustdoc-search > < section id = "main-content" class = "content" > < div class = "main-heading" > < h1 > Crate < a class = "mod" href = "#" > lazy_static< / a > < button id = "copy-path" title = "Copy item path to clipboard" > Copy item path< / button > < / h1 > < span class = "out-of-band" > < a class = "src" href = "../src/lazy_static/lib.rs.html#8-208" > source< / a > · < button id = "toggle-all-docs" title = "collapse all docs" > [< span > − < / span > ]< / button > < / span > < / div > < details class = "toggle top-doc" open > < summary class = "hideme" > < span > Expand description< / span > < / summary > < div class = "docblock" > < p > A macro for declaring lazily evaluated statics.< / p >
2024-02-13 06:38:44 +00:00
< p > Using this macro, it is possible to have < code > static< / code > 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.< / p >
2024-03-27 11:12:16 +00:00
< h2 id = "syntax" > < a class = "doc-anchor" href = "#syntax" > §< / a > Syntax< / h2 >
2024-05-05 09:43:20 +00:00
< div class = "example-wrap ignore" > < a href = "#" class = "tooltip" title = "This example is not tested" > ⓘ< / a > < pre class = "rust rust-example-rendered" > < code > < span class = "macro" > lazy_static!< / span > {
2024-02-13 06:38:44 +00:00
[< span class = "kw" > pub< / span > ] < span class = "kw" > static < / span > < span class = "kw-2" > ref < / span > NAME_1: TYPE_1 = EXPR_1;
[< span class = "kw" > pub< / span > ] < span class = "kw" > static < / span > < span class = "kw-2" > ref < / span > NAME_2: TYPE_2 = EXPR_2;
...
[< span class = "kw" > pub< / span > ] < span class = "kw" > static < / span > < span class = "kw-2" > ref < / span > NAME_N: TYPE_N = EXPR_N;
}< / code > < / pre > < / div >
< p > Attributes (including doc comments) are supported as well:< / p >
2024-07-26 09:42:18 +00:00
< div class = "example-wrap" > < pre class = "rust rust-example-rendered" > < code > < span class = "kw" > use < / span > lazy_static::lazy_static;
< span class = "macro" > lazy_static!< / span > {
2024-02-13 06:38:44 +00:00
< span class = "doccomment" > /// This is an example for using doc comment attributes
< / span > < span class = "kw" > static < / span > < span class = "kw-2" > ref < / span > EXAMPLE: u8 = < span class = "number" > 42< / span > ;
}< / code > < / pre > < / div >
2024-03-27 11:12:16 +00:00
< h2 id = "semantics" > < a class = "doc-anchor" href = "#semantics" > §< / a > Semantics< / h2 >
2024-02-13 06:38:44 +00:00
< p > For a given < code > static ref NAME: TYPE = EXPR;< / code > , the macro generates a unique type that
implements < code > Deref< TYPE> < / code > and stores it in a static with name < code > NAME< / code > . (Attributes end up
attaching to this type.)< / p >
< p > On first deref, < code > EXPR< / code > 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.< / p >
< p > Apart from the lazy initialization, the resulting “static ref” variables
have generally the same properties as regular “static” variables:< / p >
< ul >
< li > Any type in them needs to fulfill the < code > Sync< / code > trait.< / li >
< li > If the type has a destructor, then it will not run when the process exits.< / li >
< / ul >
2024-03-27 11:12:16 +00:00
< h2 id = "example" > < a class = "doc-anchor" href = "#example" > §< / a > Example< / h2 >
2024-02-13 06:38:44 +00:00
< p > Using the macro:< / p >
2024-07-26 09:42:18 +00:00
< div class = "example-wrap" > < pre class = "rust rust-example-rendered" > < code > < span class = "kw" > use < / span > lazy_static::lazy_static;
2024-02-13 06:38:44 +00:00
< span class = "kw" > use < / span > std::collections::HashMap;
2024-05-05 09:43:20 +00:00
< span class = "macro" > lazy_static!< / span > {
2024-02-13 06:38:44 +00:00
< span class = "kw" > static < / span > < span class = "kw-2" > ref < / span > HASHMAP: HashMap< u32, < span class = "kw-2" > & < / span > < span class = "lifetime" > 'static < / span > str> = {
< span class = "kw" > let < / span > < span class = "kw-2" > mut < / span > m = HashMap::new();
m.insert(< span class = "number" > 0< / span > , < span class = "string" > "foo"< / span > );
m.insert(< span class = "number" > 1< / span > , < span class = "string" > "bar"< / span > );
m.insert(< span class = "number" > 2< / span > , < span class = "string" > "baz"< / span > );
m
};
< span class = "kw" > static < / span > < span class = "kw-2" > ref < / span > COUNT: usize = HASHMAP.len();
< span class = "kw" > static < / span > < span class = "kw-2" > ref < / span > NUMBER: u32 = times_two(< span class = "number" > 21< / span > );
}
< span class = "kw" > fn < / span > times_two(n: u32) -> u32 { n * < span class = "number" > 2 < / span > }
< span class = "kw" > fn < / span > main() {
< span class = "macro" > println!< / span > (< span class = "string" > "The map has {} entries."< / span > , < span class = "kw-2" > *< / span > COUNT);
< span class = "macro" > println!< / span > (< span class = "string" > "The entry for `0` is \"{}\"."< / span > , HASHMAP.get(< span class = "kw-2" > & < / span > < span class = "number" > 0< / span > ).unwrap());
< span class = "macro" > println!< / span > (< span class = "string" > "A expensive calculation on a static results in: {}."< / span > , < span class = "kw-2" > *< / span > NUMBER);
}< / code > < / pre > < / div >
2024-03-27 11:12:16 +00:00
< h2 id = "implementation-details" > < a class = "doc-anchor" href = "#implementation-details" > §< / a > Implementation details< / h2 >
2024-02-13 06:38:44 +00:00
< p > The < code > Deref< / code > implementation uses a hidden static variable that is guarded by an atomic check on each access.< / p >
2024-03-27 11:12:16 +00:00
< h2 id = "cargo-features" > < a class = "doc-anchor" href = "#cargo-features" > §< / a > Cargo features< / h2 >
2024-02-13 06:38:44 +00:00
< p > This crate provides one cargo feature:< / p >
< ul >
< li > < code > spin_no_std< / code > : This allows using this crate in a no-std environment, by depending on the standalone < code > spin< / code > crate.< / li >
< / ul >
2024-03-27 11:12:16 +00:00
< / div > < / details > < h2 id = "macros" class = "section-header" > Macros< a href = "#macros" class = "anchor" > §< / a > < / h2 > < ul class = "item-table" > < li > < div class = "item-name" > < a class = "macro" href = "macro.lazy_static.html" title = "macro lazy_static::lazy_static" > lazy_static< / a > < / div > < / li > < / ul > < h2 id = "traits" class = "section-header" > Traits< a href = "#traits" class = "anchor" > §< / a > < / h2 > < ul class = "item-table" > < li > < div class = "item-name" > < a class = "trait" href = "trait.LazyStatic.html" title = "trait lazy_static::LazyStatic" > LazyStatic< / a > < / div > < div class = "desc docblock-short" > Support trait for enabling a few common operation on lazy static values.< / div > < / li > < / ul > < h2 id = "functions" class = "section-header" > Functions< a href = "#functions" class = "anchor" > §< / a > < / h2 > < ul class = "item-table" > < li > < div class = "item-name" > < a class = "fn" href = "fn.initialize.html" title = "fn lazy_static::initialize" > initialize< / a > < / div > < div class = "desc docblock-short" > Takes a shared reference to a lazy static and initializes
2024-02-13 06:38:44 +00:00
it if it has not been already.< / div > < / li > < / ul > < / section > < / div > < / main > < / body > < / html >
