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