Struct state::LocalStorage

A single storage location for global access to thread-local values.

A LocalStorage instance allows global access to a n per-thread values, all of which are initialized in the same manner when the value is first retrieved from a thread. The initialization function for values in LocalStorage is specified via the set method. The initialization function must be set before a value is attempted to be retrieved via the get method. The try_get can be used to determine whether the LocalStorage has been initialized before attempting to retrieve a value.

For safety reasons, values stored in LocalStorage must be Send + 'static.

Comparison with Storage

When the use-case allows, there are two primary advantages to using a LocalStorage instance over a Storage instance:

• Values stored in LocalStorage do not need to implement Sync.
• There is no synchronization overhead when setting a value.

The primary disadvantages are:

• Values are recomputed once per thread on get() where Storage never recomputes values.
• Values need to be 'static where Storage imposes no such restriction.

Values LocalStorage are not the same across different threads. Any modifications made to the stored value in one thread are not visible in another. Furthermore, because Rust reuses thread IDs, a new thread is not guaranteed to receive a newly initialized value on its first call to get.

Usage

This type is only available when the "tls" feature is enabled. To enable the feature, include the state dependency in your Cargo.toml as follows:

[dependencies]
state = { version = "0.5", features = ["tls"] }

Example

The following example uses LocalStorage to store a per-thread count:

static COUNT: LocalStorage<Cell<usize>> = LocalStorage::new();

fn check_count() {
    let count = COUNT.get();

    // initialize the state, in case we reuse thread IDs
    count.set(0);

    // increment it, non-atomically
    count.set(count.get() + 1);

    // The count should always be 1 since the state is thread-local.
    assert_eq!(count.get(), 1);
}

fn main() {
    // setup the initializer for thread-local state
    COUNT.set(|| Cell::new(0));

    // spin up many threads that call `check_count`.
    let mut threads = vec![];
    for i in 0..10 {
        threads.push(thread::spawn(|| check_count()));
    }

    // Wait for all of the thread to finish.
    for thread in threads {
        thread.join().expect("correct count");
    }
}