Trait async_local::AsyncLocal
source · 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>;
}
Expand description
LocalKey extension for creating thread-safe pointers to thread-local Context
Required Methods§
sourcefn 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_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
sourcefn 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,
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,
tokio-runtime
only.A wrapper around tokio::task::spawn_blocking
that safely extends and constrains the lifetime of RefGuard
sourceunsafe fn local_ref(&'static self) -> LocalRef<T::Target>
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 astokio::spawn
,std::future::Future::poll
, an async fn/block or within theDrop
of a pinnedstd::future::Future
that createdLocalRef
prior while pinned and polling. -
ensure that moves into
std::thread
cannot occur unless managed bytokio::task::spawn_blocking
sourceunsafe fn guarded_ref<'a>(&'static self) -> RefGuard<'a, T::Target>
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 astokio::spawn
,std::future::Future::poll
, or an async fn/block or within theDrop
of a pinnedstd::future::Future
that createdRefGuard
prior while pinned and polling. -
constrain to a non-
'static
lifetime as to preventRefGuard
from being freely movable into blocking threads. Runtime managed threads spawned bytokio::task::spawn_blocking
can be safely used by re-assigning lifetimes withstd::mem::transmute
-
future returning closures must be boxed, pinned and generic over an arbitrary lifetime as expressed by using Higher-Rank Trait Bounds (see
HRTBs
); other lifetimes will escape to ’static
F: for<'a> FnOnce(RefGuard<'a, T::Target>) -> Pin<Box<dyn Future<Output = R> + Send + 'a>>
- for async trait fns using
async_t
orasync_trait
, the lifetime'async_trait
is suitable to constrainRefGuard
from escaping to'static
Implementations on Foreign Types§
source§impl<T> AsyncLocal<T> for LocalKey<T>where
T: AsContext,
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>>,
source§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,
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,
tokio-runtime
only.