Struct std::thread::LocalKey

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 and Destruction

Initialization is dynamically performed on the first call to with() within a thread, and values support destructors which will be run when a thread exits.

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
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);
});

Platform-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:

1. 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.
2. 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.
3. On OSX, initializing TLS during destruction of other TLS slots can sometimes cancel all destructors for the current thread, whether or not the slots have already had their destructors run or not.

Methods

impl<T: 'static> LocalKey<T> [src]

fn with<F, R>(&'static self, f: F) -> R where F: FnOnce(&T) -> R

fn state(&'static self) -> LocalKeyState

Trait Implementations

impl<T: 'static> Debug for LocalKey<T>

1.15.0

[src]

fn fmt(&self, f: &mut Formatter) -> Result