Crate lazy_static

A macro for declaring lazily evaluated statics.

Using this macro, it is possible to have statics 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.

Syntax

lazy_static! {
    [pub] static ref NAME_1: TYPE_1 = EXPR_1;
    [pub] static ref NAME_2: TYPE_2 = EXPR_2;
    ...
    [pub] static ref NAME_N: TYPE_N = EXPR_N;
}

Metadata (such as doc comments) is allowed on each ref.

Semantic

For a given static ref NAME: TYPE = EXPR;, the macro generates a unique type that implements Deref<TYPE> and stores it in a static with name NAME. (Metadata ends up attaching to this type.)

On first deref, EXPR gets evaluated and stored internally, such that all further derefs can return a reference to the same object.

Like regular static muts, this macro only works for types that fulfill the Sync trait.

Example

Using the macro:

#[macro_use]
extern crate lazy_static;

use std::collections::HashMap;

lazy_static! {
    static ref HASHMAP: HashMap<u32, &'static str> = {
        let mut m = HashMap::new();
        m.insert(0, "foo");
        m.insert(1, "bar");
        m.insert(2, "baz");
        m
    };
    static ref COUNT: usize = HASHMAP.len();
    static ref NUMBER: u32 = times_two(21);
}

fn times_two(n: u32) -> u32 { n * 2 }

fn main() {
    println!("The map has {} entries.", *COUNT);
    println!("The entry for `0` is \"{}\".", HASHMAP.get(&0).unwrap());
    println!("A expensive calculation on a static results in: {}.", *NUMBER);
}

Implementation details

The Deref implementation uses a hidden static mut that is guarded by a atomic check using the sync::Once abstraction. All lazily evaluated values are currently put in a heap allocated box, due to the Rust language currently not providing any way to define uninitialized static mut values.

Macros

lazy_static!