Struct std::thread::LocalKey [] [src]

pub struct LocalKey<T> {
    // some fields omitted
}

A thread local storage key which owns its contents.

This key uses the fastest possible implementation available to it for the target platform. It is instantiated with the thread_local!`thread_local!macro and the primary method is the` macro and the primary method is the with`with` method.

The with`with` method yields a reference to the contained value which cannot be sent across threads or escape the given closure.

Initialization and Destruction

Initialization is dynamically performed on the first call to with()`with()` within a thread, and values support destructors which will be run when a thread exits.

Examples

fn main() { use std::cell::RefCell; use std::thread; thread_local!(static FOO: RefCell<u32> = RefCell::new(1)); FOO.with(|f| { assert_eq!(*f.borrow(), 1); *f.borrow_mut() = 2; }); // each thread starts out with the initial value of 1 thread::spawn(move|| { FOO.with(|f| { assert_eq!(*f.borrow(), 1); *f.borrow_mut() = 3; }); }); // we retain our original value of 2 despite the child thread FOO.with(|f| { assert_eq!(*f.borrow(), 2); }); }
use std::cell::RefCell;
use std::thread;

thread_local!(static FOO: RefCell<u32> = RefCell::new(1));

FOO.with(|f| {
    assert_eq!(*f.borrow(), 1);
    *f.borrow_mut() = 2;
});

// each thread starts out with the initial value of 1
thread::spawn(move|| {
    FOO.with(|f| {
        assert_eq!(*f.borrow(), 1);
        *f.borrow_mut() = 3;
    });
});

// we retain our original value of 2 despite the child thread
FOO.with(|f| {
    assert_eq!(*f.borrow(), 2);
});

Methods

impl<T: 'static> LocalKey<T>

fn with<F, R>(&'static self, f: F) -> R where F: FnOnce(&T) -> R

Acquires a reference to the value in this TLS key.

This will lazily initialize the value if this thread has not referenced this key yet.

Panics

This function will panic!()`panic!()` if the key currently has its destructor running, and it may panic if the destructor has previously been run for this thread.

fn state(&'static self) -> LocalKeyState

Unstable

: state querying was recently added

Query the current state of this key.

A key is initially in the Uninitialized`Uninitializedstate whenever a thread starts. It will remain in this state up until the first call to` state whenever a thread starts. It will remain in this state up until the first call to with`with` within a thread has run the initialization expression successfully.

Once the initialization expression succeeds, the key transitions to the Valid`Validstate which will guarantee that future calls to` state which will guarantee that future calls to with`with` will succeed within the thread.

When a thread exits, each key will be destroyed in turn, and as keys are destroyed they will enter the Destroyed`Destroyedstate just before the destructor starts to run. Keys may remain in the` state just before the destructor starts to run. Keys may remain in the Destroyed`Destroyedstate after destruction has completed. Keys without destructors (e.g. with types that are` state after destruction has completed. Keys without destructors (e.g. with types that are Copy`Copy), may never enter the`), may never enter the Destroyed`Destroyed` state.

Keys in the Uninitialized`Uninitializedcan be accessed so long as the initialization does not panic. Keys in the` can be accessed so long as the initialization does not panic. Keys in the Valid`Validstate are guaranteed to be able to be accessed. Keys in the` state are guaranteed to be able to be accessed. Keys in the Destroyed`Destroyedstate will panic on any call to` state will panic on any call to with`with`.