Struct tokio::task::LocalKey

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

A key for task-local data.

This type is generated by task_local! macro and unlike thread_local! it has no concept of lazily initialization. Instead, it is designed to provide task local storage the future that is passed to set.

Initialization and Destruction

Initialization is done via set which is an async fn that wraps another std::future::Future and will set the value on each Future::poll call. Once the set future is dropped the corresponding task local value is also dropped.

Examples

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

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

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

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

Methods

impl<T: 'static> LocalKey<T>

pub async fn scope<F>(&'static self, value: T, f: F) -> F::Output where
    F: Future, 

This is supported on feature="rt-util" only.

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

This will run the provided future to completion and set the provided value as the task local under this key. Once the returned future is dropped so will the value passed be dropped.

async fn dox() {

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

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

}

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

This is supported on feature="rt-util" only.

Access this task-local key, running the provided closure with a reference passed to the value.

Panics

This function will panic if not called within a future that has not been set via LocalKey::set.

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

This is supported on feature="rt-util" only.

Access this task-local key, running the provided closure with a reference passed to the value. Unlike with this function will return a Result<R, AccessError> instead of panicking.

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

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

This is supported on feature="rt-util" only.

Get a copy of the task-local value if it implements the Copy trait.

Trait Implementations

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

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

Formats the value using the given formatter.