# Struct std::thread::LocalKey [−] [src]

    pub struct LocalKey<T: 'static> {
        // 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` 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

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!()` 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`

Unstable (`thread_local_state` #27716)

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

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

# Help

## Keyboard Shortcuts

?
  Show this help dialog
S
  Focus the search field
⇤
  Move up in search results
⇥
  Move down in search results
⏎
  Go to active search result

## Search Tricks

Prefix searches with a type followed by a colon (e.g. `fn:`) to restrict the search to a given type.

Accepted types are: `fn`, `mod`, `struct`, `enum`, `trait`, `type`, `macro`, and `const`.

Search functions by type signature (e.g. `vec -> usize`)