Struct LocalKey

pub struct LocalKey<T: 'static> { /* private fields */ }

Available on crate feature rt only.

A key for task-local data.

This type is generated by the task_local! macro.

Unlike std::thread::LocalKey, tokio::task::LocalKey will not lazily initialize the value on first access. Instead, the value is first initialized when the future containing the task-local is first polled by a futures executor, like Tokio.

Examples

tokio::task_local! {
    static NUMBER: u32;
}

NUMBER.scope(1, async move {
    assert_eq!(NUMBER.get(), 1);
}).await;

NUMBER.scope(2, async move {
    assert_eq!(NUMBER.get(), 2);

    NUMBER.scope(3, async move {
        assert_eq!(NUMBER.get(), 3);
    }).await;
}).await;

Implementations

impl<T: 'static> LocalKey<T>

pub fn scope<F>(&'static self, value: T, f: F) -> TaskLocalFuture<T, F>

where F: Future,

Sets a value T as the task-local value for the future F.

On completion of scope, the task-local will be dropped.

Panics

If you poll the returned future inside a call to with or try_with on the same LocalKey, then the call to poll will panic.

Examples

tokio::task_local! {
    static NUMBER: u32;
}

NUMBER.scope(1, async move {
    println!("task local value: {}", NUMBER.get());
}).await;

pub fn sync_scope<F, R>(&'static self, value: T, f: F) -> R

where F: FnOnce() -> R,

Sets a value T as the task-local value for the closure F.

On completion of sync_scope, the task-local will be dropped.

Panics

This method panics if called inside a call to with or try_with on the same LocalKey.

Examples

tokio::task_local! {
    static NUMBER: u32;
}

NUMBER.sync_scope(1, || {
    println!("task local value: {}", NUMBER.get());
});

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

where F: FnOnce(&T) -> R,

Accesses the current task-local and runs the provided closure.

Panics

This function will panic if the task local doesn’t have a value set.

pub fn try_with<F, R>(&'static self, f: F) -> Result<R, AccessError>

where F: FnOnce(&T) -> R,

Accesses the current task-local and runs the provided closure.

If the task-local with the associated key is not present, this method will return an AccessError. For a panicking variant, see with.

impl<T: Clone + 'static> LocalKey<T>

pub fn get(&'static self) -> T

Returns a copy of the task-local value if the task-local value implements Clone.

Panics

This function will panic if the task local doesn’t have a value set.

Trait Implementations

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

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

Formats the value using the given formatter.

Layout

Note: Most layout information is completely unstable and may even differ between compilations. The only exception is types with certain repr(...) attributes. Please see the Rust Reference's “Type Layout” chapter for details on type layout guarantees.

Size: 8 bytes