Struct LocalKey

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

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

# async fn dox() {
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>

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

# async fn dox() {
tokio::task_local! {
    static NUMBER: u32;
}

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

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

# async fn dox() {
tokio::task_local! {
    static NUMBER: u32;
}

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

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.

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>

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.

fn try_get(&'static self) -> Result<T, AccessError>

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

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

Trait Implementations

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

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

Auto Trait Implementations

impl<T> Freeze for LocalKey<T> where LocalKey<RefCell<Option<T>>>: Freeze,

impl<T> RefUnwindSafe for LocalKey<T> where LocalKey<RefCell<Option<T>>>: RefUnwindSafe,

impl<T> Send for LocalKey<T> where LocalKey<RefCell<Option<T>>>: Send,

impl<T> Sync for LocalKey<T> where LocalKey<RefCell<Option<T>>>: Sync,

impl<T> Unpin for LocalKey<T> where LocalKey<RefCell<Option<T>>>: Unpin,

impl<T> UnsafeUnpin for LocalKey<T> where LocalKey<RefCell<Option<T>>>: UnsafeUnpin,

impl<T> UnwindSafe for LocalKey<T> where LocalKey<RefCell<Option<T>>>: UnwindSafe,

Blanket Implementations

impl<T> Any for LocalKey<T> where T: 'static + ?Sized,

fn type_id(&self) -> TypeId

impl<T> Borrow<T> for LocalKey<T> where T: ?Sized,

fn borrow(&self) -> &T

impl<T> BorrowMut<T> for LocalKey<T> where T: ?Sized,

fn borrow_mut(&mut self) -> &mut T

impl<T> From<T> for LocalKey<T>

fn from(t: T) -> T

Returns the argument unchanged.

impl<T, U> Into<U> for LocalKey<T> where U: From<T>,

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of [From]<T> for U chooses to do.

impl<T, U> TryFrom<U> for LocalKey<T> where U: Into<T>,

type Error = never;
fn try_from(value: U) -> Result<T, never>

impl<T, U> TryInto<U> for LocalKey<T> where U: TryFrom<T>,

type Error = <U as TryFrom<T>>::Error;
fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>