Trait async_local::AsyncLocal
source · pub trait AsyncLocal<T, Ref>where
T: 'static + AsContext<Ref>,
Ref: Sync + 'static,{
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, Ref>) -> Fut + Send + 'async_trait,
Fut: Future<Output = R> + Send + 'async_trait,
T: 'async_trait,
Ref: '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, Ref>) -> Fut + Send + 'async_trait,
Fut: Future<Output = R> + Send + 'async_trait;
unsafe fn local_ref(&'static self) -> LocalRef<Ref>;
unsafe fn guarded_ref<'a>(&'static self) -> RefGuard<'a, Ref>;
}
Expand description
LocalKey extension for creating thread-safe pointers to thread-local Context
Required Associated Types§
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, Ref>) -> Fut + Send + 'async_trait,
Fut: Future<Output = R> + Send + 'async_trait,
T: 'async_trait,
Ref: 'async_trait,
Self: 'static
Required Methods§
sourcefn 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, Ref>) -> Fut + Send + 'async_trait,
Fut: Future<Output = R> + Send + 'async_trait,
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, Ref>) -> Fut + Send + 'async_trait,
Fut: Future<Output = R> + Send + 'async_trait,
The async counterpart of LocalKey::with
sourceunsafe fn local_ref(&'static self) -> LocalRef<Ref>
unsafe fn local_ref(&'static self) -> LocalRef<Ref>
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:
-
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 withintokio::spawn
,std::future::Future::poll
, an async fn or block or within the drop of a pinnedstd::future::Future
that createdLocalRef
prior while pinned and polling. -
ensure that
LocalRef
cannot be dereferenced outside of the async runtime context or any thread scoped therein -
use
pin_project::pinned_drop
to ensure the safety of dereferencingLocalRef
on the drop impl of a pinned future that createdLocalRef
while polling. -
ensure that a move into
std::thread
cannot occur or otherwise thatLocalRef
cannot be created nor derefenced outside of an async context by constraining use exclusively to within a pinnedstd::future::Future
being polled or dropped and otherwise usingRefGuard
explicitly over any non-'static
lifetime such as'async_trait
to allow more flexible usage combined with async traits -
only use
std::thread::scope
with validly createdLocalRef
sourceunsafe fn guarded_ref<'a>(&'static self) -> RefGuard<'a, Ref>
unsafe fn guarded_ref<'a>(&'static self) -> RefGuard<'a, Ref>
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:
-
ensure that
RefGuard
can only refer to a thread local within the context of the async runtime by creating within an async context such astokio::spawn
,std::future::Future::poll
, or an async fn or block or within the drop of a pinnedstd::future::Future
that createdRefGuard
prior while pinned and polling. -
Use borrows of any non-
'static
lifetime such as'async_trait
as a way of constraining the lifetime and preventingRefGuard
from being movable into a blocking thread.