Trait async_local::AsyncLocal

pub trait AsyncLocal<T>where
    T: AsContext,{
    // Required methods
    fn with_async<F, R>(&'static self, f: F) -> WithLocal<T, F, R> 
       where F: for<'a> FnOnce(RefGuard<'a, T::Target>) -> Pin<Box<dyn Future<Output = R> + Send + 'a>>;
    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 Methods

fn with_async<F, R>(&'static self, f: F) -> WithLocal<T, F, R> where F: for<'a> FnOnce(RefGuard<'a, T::Target>) -> Pin<Box<dyn Future<Output = R> + Send + 'a>>,

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 barrier-protected-runtime only.

A wrapper around tokio::task::spawn_blocking that safely extends and constrains the lifetime of RefGuard

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 a barrier-protected Tokio 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 and constrained therein

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 a barrier-protected Tokio 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.

• constrain to a non-'static lifetime as to prevent RefGuard from being freely movable into blocking threads. Runtime managed threads spawned by tokio::task::spawn_blocking can be safely used by re-assigning lifetimes with std::mem::transmute

• closures can only adequately constrain the lifetime by using Higher-Rank Trait Bounds (see HRTBs); futures returned must be boxed, pinned and generic over an arbitrary lifetime

F: for<'a> FnOnce(RefGuard<'a, T::Target>) -> Pin<Box<dyn Future<Output = R> + Send + 'a>>

• for async trait fns using async_t or async_trait, the lifetime 'async_trait is suitable to constrain RefGuard from escaping to 'static

Implementations on Foreign Types

impl<T> AsyncLocal<T> for LocalKey<T>where T: AsContext,

fn with_async<F, R>(&'static self, f: F) -> WithLocal<T, F, R> where F: for<'a> FnOnce(RefGuard<'a, T::Target>) -> Pin<Box<dyn Future<Output = R> + Send + 'a>>,

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 barrier-protected-runtime only.

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

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

Implementors