Trait async_local::AsyncLocal

source · 
pub trait AsyncLocal<T, Ref>where
    T: 'static + AsRef<Context<Ref>>,
    Ref: Sync + 'static,{
    type impl_trait_with_async_0<'async_trait, F: 'async_trait, R: 'async_trait, Fut: 'async_trait>: Future<Output = R> + 'async_trait + Send
    where
        F: FnOnce(RefGuard<'async_trait, Ref>) -> Fut + Send,
        Fut: Future<Output = R> + Send,
        T: 'async_trait,
        Ref: 'async_trait,
        Self: 'static;

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

LocalKey extension for creating stable thread-safe pointers to thread-local Contexts that are valid for the lifetime of the async runtime and usable within an async context across await points

Required Associated Types§

Required Methods§

Create a thread-safe pointer to a thread local Context

Safety

The only safe way to use LocalRef is as created from and used within the context of the async runtime or a thread scoped therein. All behavior must ensure that it is not possible for LocalRef to be created within nor dereferenced on a thread outside of the async runtime.

The well-known way of safely accomplishing these guarantees is to:

  1. ensure that LocalRef can only refer to a thread local within the context of the runtime by creating and using only within an async context such as [tokio::spawn], std::future::Future::poll, async fn, async block or within the drop of a pinned std::future::Future that created LocalRef prior while pinned and polling.

  2. limit public usage and ensure that LocalRef cannot be dereferenced outside of the async runtime context

  3. use pin_project::pinned_drop to ensure the safety of dereferencing LocalRef on drop impl of a pinned future that created LocalRef while polling.

  4. ensure that a move into std::thread cannot occur or otherwise that LocalRef cannot be created nor derefenced outside of an async context by constraining use exclusively to within a pinned std::future::Future being polled or dropped and otherwise using RefGuard explicitly over any non-`static lifetime such as ’async_trait to allow more flexible usage combined with async traits

  5. only use std::thread::scope with validly created LocalRef

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

Safety

The only safe way to use RefGuard is as created from and used within the context of the async runtime or a thread scoped therein. All behavior must ensure that it is not possible for RefGuard to be created within nor dereferenced on a thread outside of the async runtime.

The well-known way of safely accomplishing these guarantees is to:

  1. ensure that RefGuard can only refer to a thread local within the context of the async runtime by creating within an async context such as [tokio::spawn], std::future::Future::poll, or an async fn

  2. explicitly constrain the lifetime to any non-’static lifetime such as `async_trait

Implementations on Foreign Types§

Implementors§