pub struct LocalKey<T: 'static> { /* 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 method.
The with method yields a reference to the contained value which cannot be sent across threads or escape the given closure.
Initialization is dynamically performed on the first call to with within a thread, and values that implement Drop get destructed when a thread exits. Some caveats apply, which are explained below.
A LocalKey's initializer cannot recursively depend on itself, and using a LocalKey in this way will cause the initializer to infinitely recurse on the first call to with.
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);
}); Note that a "best effort" is made to ensure that destructors for types stored in thread local storage are run, but not all platforms can guarantee that destructors will be run for all types in thread local storage. For example, there are a number of known caveats where destructors are not run:
impl<T: 'static> LocalKey<T>
[src]
pub fn with<F, R>(&'static self, f: F) -> R where
F: FnOnce(&T) -> R,
[src]
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.
This function will panic!() if the key currently has its destructor running, and it may panic if the destructor has previously been run for this thread.
pub fn state(&'static self) -> LocalKeyState
[src]
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 within a thread has run the initialization expression successfully.
Once the initialization expression succeeds, the key transitions to the Valid state which will guarantee that future calls to with will succeed within the thread. Some keys might skip the Uninitialized state altogether and start in the Valid state as an optimization (e.g. keys initialized with a constant expression), but no guarantees are made.
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), may never enter the Destroyed state.
Keys in the Uninitialized state can be accessed so long as the initialization does not panic. Keys in the Valid state are guaranteed to be able to be accessed. Keys in the Destroyed state will panic on any call to with.
pub fn try_with<F, R>(&'static self, f: F) -> Result<R, AccessError> where
F: FnOnce(&T) -> R,
[src]
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. If the key has been destroyed (which may happen if this is called in a destructor), this function will return a ThreadLocalError.
This function will still panic!() if the key is uninitialized and the key's initializer panics.
impl<T: 'static> Debug for LocalKey<T>
fn fmt(&self, f: &mut Formatter) -> Result
[src]
Formats the value using the given formatter. Read more
© 2010 The Rust Project Developers
Licensed under the Apache License, Version 2.0 or the MIT license, at your option.
https://doc.rust-lang.org/std/thread/struct.LocalKey.html