pub struct LocalKey<T: 'static> { /* private fields */ }
Expand description
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
outlive the current thread or escape the given closure.
Initialization and Destruction
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. Using a
LocalKey
in this way may cause panics, aborts or infinite recursion on
the first call to with
.
Examples
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
let t = thread::spawn(move|| {
FOO.with(|f| {
assert_eq!(*f.borrow(), 1);
*f.borrow_mut() = 3;
});
});
// wait for the thread to complete and bail out on panic
t.join().unwrap();
// we retain our original value of 2 despite the child thread
FOO.with(|f| {
assert_eq!(*f.borrow(), 2);
});
RunPlatform-specific behavior
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:
- On Unix systems when pthread-based TLS is being used, destructors will not be run for TLS values on the main thread when it exits. Note that the application will exit immediately after the main thread exits as well.
- On all platforms it’s possible for TLS to re-initialize other TLS slots during destruction. Some platforms ensure that this cannot happen infinitely by preventing re-initialization of any slot that has been destroyed, but not all platforms have this guard. Those platforms that do not guard typically have a synthetic limit after which point no more destructors are run.
- When the process exits on Windows systems, TLS destructors may only be run on the thread that causes the process to exit. This is because the other threads may be forcibly terminated.
Synchronization in thread-local destructors
On Windows, synchronization operations (such as JoinHandle::join
) in
thread local destructors are prone to deadlocks and so should be avoided.
This is because the loader lock is held while a destructor is run. The
lock is acquired whenever a thread starts or exits or when a DLL is loaded
or unloaded. Therefore these events are blocked for as long as a thread
local destructor is running.
Implementations§
source§impl<T: 'static> LocalKey<T>
impl<T: 'static> LocalKey<T>
sourcepub fn with<F, R>(&'static self, f: F) -> R
pub fn with<F, R>(&'static self, f: F) -> 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!()
if the key currently has its
destructor running, and it may panic if the destructor has
previously been run for this thread.
1.26.0 · sourcepub fn try_with<F, R>(&'static self, f: F) -> Result<R, AccessError>
pub fn try_with<F, R>(&'static self, f: F) -> Result<R, AccessError>
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 an AccessError
.
Panics
This function will still panic!()
if the key is uninitialized and the
key’s initializer panics.
source§impl<T: 'static> LocalKey<Cell<T>>
impl<T: 'static> LocalKey<Cell<T>>
1.73.0 · sourcepub fn set(&'static self, value: T)
pub fn set(&'static self, value: T)
Sets or initializes the contained value.
Unlike the other methods, this will not run the lazy initializer of the thread local. Instead, it will be directly initialized with the given value if it wasn’t initialized yet.
Panics
Panics if the key currently has its destructor running, and it may panic if the destructor has previously been run for this thread.
Examples
use std::cell::Cell;
thread_local! {
static X: Cell<i32> = panic!("!");
}
// Calling X.get() here would result in a panic.
X.set(123); // But X.set() is fine, as it skips the initializer above.
assert_eq!(X.get(), 123);
Run1.73.0 · sourcepub fn get(&'static self) -> Twhere
T: Copy,
pub fn get(&'static self) -> Twhere
T: Copy,
Returns a copy of the contained value.
This will lazily initialize the value if this thread has not referenced this key yet.
Panics
Panics if the key currently has its destructor running, and it may panic if the destructor has previously been run for this thread.
Examples
use std::cell::Cell;
thread_local! {
static X: Cell<i32> = Cell::new(1);
}
assert_eq!(X.get(), 1);
Run1.73.0 · sourcepub fn take(&'static self) -> Twhere
T: Default,
pub fn take(&'static self) -> Twhere
T: Default,
Takes the contained value, leaving Default::default()
in its place.
This will lazily initialize the value if this thread has not referenced this key yet.
Panics
Panics if the key currently has its destructor running, and it may panic if the destructor has previously been run for this thread.
Examples
use std::cell::Cell;
thread_local! {
static X: Cell<Option<i32>> = Cell::new(Some(1));
}
assert_eq!(X.take(), Some(1));
assert_eq!(X.take(), None);
Run1.73.0 · sourcepub fn replace(&'static self, value: T) -> T
pub fn replace(&'static self, value: T) -> T
Replaces the contained value, returning the old value.
This will lazily initialize the value if this thread has not referenced this key yet.
Panics
Panics if the key currently has its destructor running, and it may panic if the destructor has previously been run for this thread.
Examples
use std::cell::Cell;
thread_local! {
static X: Cell<i32> = Cell::new(1);
}
assert_eq!(X.replace(2), 1);
assert_eq!(X.replace(3), 2);
Runsource§impl<T: 'static> LocalKey<RefCell<T>>
impl<T: 'static> LocalKey<RefCell<T>>
1.73.0 · sourcepub fn with_borrow<F, R>(&'static self, f: F) -> R
pub fn with_borrow<F, R>(&'static self, f: F) -> R
Acquires a reference to the contained value.
This will lazily initialize the value if this thread has not referenced this key yet.
Panics
Panics if the value is currently mutably borrowed.
Panics if the key currently has its destructor running, and it may panic if the destructor has previously been run for this thread.
Example
use std::cell::RefCell;
thread_local! {
static X: RefCell<Vec<i32>> = RefCell::new(Vec::new());
}
X.with_borrow(|v| assert!(v.is_empty()));
Run1.73.0 · sourcepub fn with_borrow_mut<F, R>(&'static self, f: F) -> R
pub fn with_borrow_mut<F, R>(&'static self, f: F) -> R
Acquires a mutable reference to the contained value.
This will lazily initialize the value if this thread has not referenced this key yet.
Panics
Panics if the value is currently borrowed.
Panics if the key currently has its destructor running, and it may panic if the destructor has previously been run for this thread.
Example
use std::cell::RefCell;
thread_local! {
static X: RefCell<Vec<i32>> = RefCell::new(Vec::new());
}
X.with_borrow_mut(|v| v.push(1));
X.with_borrow(|v| assert_eq!(*v, vec![1]));
Run1.73.0 · sourcepub fn set(&'static self, value: T)
pub fn set(&'static self, value: T)
Sets or initializes the contained value.
Unlike the other methods, this will not run the lazy initializer of the thread local. Instead, it will be directly initialized with the given value if it wasn’t initialized yet.
Panics
Panics if the value is currently borrowed.
Panics if the key currently has its destructor running, and it may panic if the destructor has previously been run for this thread.
Examples
use std::cell::RefCell;
thread_local! {
static X: RefCell<Vec<i32>> = panic!("!");
}
// Calling X.with() here would result in a panic.
X.set(vec![1, 2, 3]); // But X.set() is fine, as it skips the initializer above.
X.with_borrow(|v| assert_eq!(*v, vec![1, 2, 3]));
Run1.73.0 · sourcepub fn take(&'static self) -> Twhere
T: Default,
pub fn take(&'static self) -> Twhere
T: Default,
Takes the contained value, leaving Default::default()
in its place.
This will lazily initialize the value if this thread has not referenced this key yet.
Panics
Panics if the value is currently borrowed.
Panics if the key currently has its destructor running, and it may panic if the destructor has previously been run for this thread.
Examples
use std::cell::RefCell;
thread_local! {
static X: RefCell<Vec<i32>> = RefCell::new(Vec::new());
}
X.with_borrow_mut(|v| v.push(1));
let a = X.take();
assert_eq!(a, vec![1]);
X.with_borrow(|v| assert!(v.is_empty()));
Run1.73.0 · sourcepub fn replace(&'static self, value: T) -> T
pub fn replace(&'static self, value: T) -> T
Replaces the contained value, returning the old value.
Panics
Panics if the value is currently borrowed.
Panics if the key currently has its destructor running, and it may panic if the destructor has previously been run for this thread.
Examples
use std::cell::RefCell;
thread_local! {
static X: RefCell<Vec<i32>> = RefCell::new(Vec::new());
}
let prev = X.replace(vec![1, 2, 3]);
assert!(prev.is_empty());
X.with_borrow(|v| assert_eq!(*v, vec![1, 2, 3]));
Run