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!
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
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
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
state just before the
destructor starts to run. Keys may remain in the Destroyed
state after
destruction has completed. Keys without destructors (e.g. with types
that are Copy
`Copy), may never enter the
Destroyed` state.
Keys in the Uninitialized
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
Destroyedstate will panic on any call to
with`.