Trait async_local::AsyncLocal

source · 
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;
    unsafe fn local_ref(&'static self) -> LocalRef<T::Target>;
    unsafe fn guarded_ref<'a>(&'static self) -> RefGuard<'a, T::Target>;
}
Expand description

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

Required Associated Types§

Required Methods§

The async counterpart of LocalKey::with

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

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 within tokio::spawn, std::future::Future::poll, an async fn or block or within the drop of a pinned std::future::Future that created LocalRef prior while pinned and polling.

  2. ensure that LocalRef cannot be dereferenced outside of the async runtime context or any thread scoped therein

  3. use pin_project::pinned_drop to ensure the safety of dereferencing LocalRef on the 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 within the context of an 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 or block or within the drop of a pinned std::future::Future that created RefGuard prior while pinned and polling.

  2. Use borrows of any non-'static lifetime such as'async_trait as a way of constraining the lifetime and preventing RefGuard from being movable into a blocking thread.

Implementations on Foreign Types§

Implementors§