Struct InheritableLocalKey

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

A key for inheritable task-local data.

This type is generated by the inheritable_task_local! macro.

Unlike std::thread::LocalKey, InheritableLocalKey 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

inheritable_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: Send + Sync> InheritableLocalKey<T>

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

where F: Future,

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

Once this future and all of its inheriting descendants have completed, the value will be dropped.

Panics

If you poll any future returned by this method inside a call to with or try_with then the call to poll will panic.

Examples

inheritable_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 inheritable task-local value for the closure F.

On completion of sync_scope, the task-local will be dropped, unless the closure spawned a task which inherited this value.

Panics

This method panics if called inside a call to with or try_with

Examples

inheritable_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 inheritable 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, InheritableAccessError>

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

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

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

impl<T: Clone + Send + Sync> InheritableLocalKey<T>

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

Returns a copy of the inheritable 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.