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
: 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`.