Trait async_local::AsyncLocal

source · 
pub trait AsyncLocal<T, Ref>where
    T: 'static + AsRef<Context<Ref>>,
    Ref: Sync,{
    unsafe fn local_ref(&'static self) -> LocalRef<Ref>;
    unsafe fn guarded_ref<'a>(&'static self) -> RefGuard<'a, Ref>;
}
Expand description

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

Required Methods§

Create a thread-safe reference to a thread local Context

Safety

The only safe way to use LocalRef is as created from and used within the context of the Tokio 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 Tokio 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 Tokio 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 reference to a thread local Context

Safety

The only safe way to use RefGuard is as created from and used within the context of the Tokio 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 Tokio 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 Tokio 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§