Trait async_local::AsyncLocal

pub trait AsyncLocal<T>where
    T: 'static + AsContext,{
    type impl_trait_with_async_0<'async_trait, F, R: 'async_trait, Fut>: Future<Output = R> + 'async_trait + Send
    where
        F: FnOnce(RefGuard<'async_trait, T::Target>) -> Fut + Send + 'async_trait,
        Fut: Future<Output = R> + Send + 'async_trait,
        T: 'async_trait,
        Self: 'static;

    fn with_async<'async_trait, F, R: 'async_trait, Fut>(
        &'static self,
        f: F
    ) -> Self::impl_trait_with_async_0<'async_trait, F, R, Fut>
    where
        F: FnOnce(RefGuard<'async_trait, T::Target>) -> Fut + Send + 'async_trait,
        Fut: Future<Output = R> + Send + 'async_trait;
    fn with_blocking<F, R>(&'static self, f: F) -> JoinHandle<R>
    where
        F: for<'a> FnOnce(RefGuard<'a, T::Target>) -> R + Send + 'static,
        R: Send + 'static;
    unsafe fn local_ref(&'static self) -> LocalRef<T::Target>;
    unsafe fn guarded_ref<'a>(&'static self) -> RefGuard<'a, T::Target>;
}

LocalKey extension for creating thread-safe pointers to thread-local Context

Required Associated Types

type impl_trait_with_async_0<'async_trait, F, R: 'async_trait, Fut>: Future<Output = R> + 'async_trait + Send
where
    F: FnOnce(RefGuard<'async_trait, T::Target>) -> Fut + Send + 'async_trait,
    Fut: Future<Output = R> + Send + 'async_trait,
    T: 'async_trait,
    Self: 'static

Required Methods

fn with_async<'async_trait, F, R: 'async_trait, Fut>(
    &'static self,
    f: F
) -> Self::impl_trait_with_async_0<'async_trait, F, R, Fut>where
    F: FnOnce(RefGuard<'async_trait, T::Target>) -> Fut + Send + 'async_trait,
    Fut: Future<Output = R> + Send + 'async_trait,

The async counterpart of LocalKey::with

fn with_blocking<F, R>(&'static self, f: F) -> JoinHandle<R>where
    F: for<'a> FnOnce(RefGuard<'a, T::Target>) -> R + Send + 'static,
    R: Send + 'static,

Available on crate features tokio-runtime or async-std-runtime only.

A wrapper around spawn_blocking that appropriately constrains the lifetime of RefGuard

Use the tokio-runtime feature flag for tokio::task::spawn_blocking or async-std-runtime for async_std::task::spawn_blocking

unsafe fn local_ref(&'static self) -> LocalRef<T::Target>

Create a thread-safe pointer to a thread local Context

Safety

The only safe way to use LocalRef is within the context of an async runtime:

• ensure that LocalRef refers only to thread locals owned by runtime worker threads by creating within an async context such as tokio::spawn, std::future::Future::poll, an async fn/block or within the Drop of a pinned std::future::Future that created LocalRef prior while pinned and polling.

• ensure that moves into std::thread cannot occur unless managed by tokio::task::spawn_blocking or async_std::task::spawn_blocking

unsafe fn guarded_ref<'a>(&'static self) -> RefGuard<'a, T::Target>

Create a lifetime-constrained thread-safe pointer to a thread local Context

Safety

The only safe way to use RefGuard is within the context of an async runtime:

• ensure that RefGuard can only refer to thread locals owned by runtime worker threads by runtime worker threads by creating within an async context such as tokio::spawn, std::future::Future::poll, or an async fn/block or within the Drop of a pinned std::future::Future that created RefGuard prior while pinned and polling.

• Use borrows of any non-'static lifetime such as 'async_trait as a way of contraining the lifetime as to prevent RefGuard from being freely movable into blocking threads. Runtime managed threads spawned by tokio::task::spawn_blocking or async_std::task::spawn_blocking can be safely used by re-assigning lifetimes with std::mem::transmute

Implementations on Foreign Types

impl<T> AsyncLocal<T> for LocalKey<T>where
    T: AsContext + 'static,

fn with_async<'async_trait, F, R: 'async_trait, Fut>(
    &'static self,
    f: F
) -> Self::impl_trait_with_async_0<'async_trait, F, R, Fut>where
    F: FnOnce(RefGuard<'async_trait, T::Target>) -> Fut + Send + 'async_trait,
    Fut: Future<Output = R> + Send + 'async_trait,

fn with_blocking<F, R>(&'static self, f: F) -> JoinHandle<R>where
    F: for<'a> FnOnce(RefGuard<'a, T::Target>) -> R + Send + 'static,
    R: Send + 'static,

Available on crate features tokio-runtime or async-std-runtime only.

unsafe fn local_ref(&'static self) -> LocalRef<T::Target>

unsafe fn guarded_ref<'a>(&'static self) -> RefGuard<'a, T::Target>

type impl_trait_with_async_0<'async_trait, F, R: 'async_trait, Fut>
where
    F: FnOnce(RefGuard<'async_trait, T::Target>) -> Fut + Send + 'async_trait,
    Fut: Future<Output = R> + Send + 'async_trait,
    Self: 'static,
    T: 'async_trait = impl Future<Output = R> + Send + 'async_trait

Implementors