Trait async_local::AsyncLocal
source · pub trait AsyncLocal<T, Ref>where
T: 'static + AsRef<Context<Ref>>,
Ref: Sync + 'static,{
type impl_trait_with_async_0<'async_trait, F: 'async_trait, R: 'async_trait, Fut: 'async_trait>: Future<Output = R> + 'async_trait + Send
where
F: FnOnce(RefGuard<'async_trait, Ref>) -> Fut + Send,
Fut: Future<Output = R> + 'async_trait + Send,
T: 'async_trait,
Ref: 'async_trait,
Self: 'static;
unsafe fn local_ref(&'static self) -> LocalRef<Ref>;
unsafe fn guarded_ref<'a>(&'static self) -> RefGuard<'a, Ref>;
fn with_async<'async_trait, F: 'async_trait, R: 'async_trait, Fut: 'async_trait>(
&'static self,
f: F
) -> Self::impl_trait_with_async_0<'async_trait, F, R, Fut>
where
F: FnOnce(RefGuard<'async_trait, Ref>) -> Fut + Send,
Fut: Future<Output = R> + 'async_trait + Send;
}
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 Associated Types§
type impl_trait_with_async_0<'async_trait, F: 'async_trait, R: 'async_trait, Fut: 'async_trait>: Future<Output = R> + 'async_trait + Send
where
F: FnOnce(RefGuard<'async_trait, Ref>) -> Fut + Send,
Fut: Future<Output = R> + 'async_trait + Send,
T: 'async_trait,
Ref: 'async_trait,
Self: 'static
Required Methods§
sourceunsafe fn local_ref(&'static self) -> LocalRef<Ref>
unsafe fn local_ref(&'static self) -> LocalRef<Ref>
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:
-
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 astokio::spawn
,std::future::Future::poll
, async fn, async block or within the drop of a pinnedstd::future::Future
that createdLocalRef
prior while pinned and polling. -
limit public usage and ensure that
LocalRef
cannot be dereferenced outside of the Tokio runtime context -
use
pin_project::pinned_drop
to ensure the safety of dereferencingLocalRef
on 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 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:
-
ensure that
RefGuard
can only refer to a thread local within the context of the Tokio runtime by creating within an async context such astokio::spawn
,std::future::Future::poll
, or an async fn -
explicitly constrain the lifetime to any non-’static lifetime such as `async_trait