std::thread::LocalKey - Rust
Description: API documentation for the Rust `LocalKey` struct in crate `std`.
Keywords: rust, rustlang, rust-lang, LocalKey

# 1.0.0[−][src]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 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`.

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

Run

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

## Implementations

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

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

#### `pub fn try_with<F, R>(&'static self, f: F) -> Result<R, AccessError> where
F: FnOnce(&T) -> R,` 1.26.0[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 an `AccessError`.

# Panics

This function will still `panic!()` if the key is uninitialized and the key's initializer panics.

## Trait Implementations

### `impl<T: 'static> Debug for LocalKey<T>`1.16.0[src]

#### `fn fmt(&self, f: &mut Formatter<'_>) -> Result`[src]

Formats the value using the given formatter. Read more

## Auto Trait Implementations

### `impl<T> RefUnwindSafe for LocalKey<T>`

### `impl<T> Send for LocalKey<T>`

### `impl<T> Sync for LocalKey<T>`

### `impl<T> Unpin for LocalKey<T>`

### `impl<T> UnwindSafe for LocalKey<T>`

## Blanket Implementations

### `impl<T> Any for T where
T: 'static + ?Sized,` [src]

#### `pub fn type_id(&self) -> TypeId`[src]

Gets the `TypeId` of `self`. Read more

### `impl<T> Borrow<T> for T where
T: ?Sized,` [src]

#### `pub fn borrow(&self) -> &Tⓘ

### Notable traits for &'_ mut I

`impl<'_, I> Iterator for &'_ mut I where
I: Iterator + ?Sized, type Item = <I as Iterator>::Item;impl<'_, F> Future for &'_ mut F where
F: Unpin + Future + ?Sized, type Output = <F as Future>::Output;impl<R: Read + ?Sized, '_> Read for &'_ mut Rimpl<W: Write + ?Sized, '_> Write for &'_ mut W`
`[src]

Immutably borrows from an owned value. Read more

### `impl<T> BorrowMut<T> for T where
T: ?Sized,` [src]

#### `pub fn borrow_mut(&mut self) -> &mut Tⓘ

### Notable traits for &'_ mut I

`impl<'_, I> Iterator for &'_ mut I where
I: Iterator + ?Sized, type Item = <I as Iterator>::Item;impl<'_, F> Future for &'_ mut F where
F: Unpin + Future + ?Sized, type Output = <F as Future>::Output;impl<R: Read + ?Sized, '_> Read for &'_ mut Rimpl<W: Write + ?Sized, '_> Write for &'_ mut W`
`[src]

Mutably borrows from an owned value. Read more

### `impl<T> From<T> for T`[src]

#### `pub fn from(t: T) -> T`[src]

Performs the conversion.

### `impl<T, U> Into<U> for T where
U: From<T>,` [src]

#### `pub fn into(self) -> U`[src]

Performs the conversion.

### `impl<T, U> TryFrom<U> for T where
U: Into<T>,` [src]

#### `type Error = Infallible`

The type returned in the event of a conversion error.

#### `pub fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>`[src]

Performs the conversion.

### `impl<T, U> TryInto<U> for T where
U: TryFrom<T>,` [src]

#### `type Error = <U as TryFrom<T>>::Error`

The type returned in the event of a conversion error.

#### `pub fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>`[src]

Performs the conversion.