Traditionally the downside of thread-locals has been that usage is constrained to the LocalKey::with closure with no lifetime escapement thus making usage within an async context limited to calls between await points with no guarantee of reference stability. This makes a lot of sense for a number of reasons: there is no clear way to express the lifetime of a thread, the lifetime's of threads are never equivalent and extending the lifetime to 'static can result in dangling pointers during shutdown should references outlive the referenced thread local. Despite all these constraints however, it is yet possible to safely hold pointers to thread locals beyond the standard lifetime of thread locals and across await points by logically constraining usage to exclusively be within an async context. This crate provides safe abstractions such as AsyncLocal::with_async as well as the unsafe pointer types and safety considerations for creating narrowly-tailored safe abstractions for using pointers to thread locals soundly in an async context and across await points.
Exclusively during the async runtime shutdown sequence there exists potential for LocalRef and RefGuard to dereference dangling pointers while dropping unless the runtime itself sequences shutdown in a way that prevents this as described below. This can be avoided by never dereferencing these pointers during drop, or by using a supported runtime such as Tokio or async-std. All single-threaded runtimes are inherently safe to use.
| Runtime | Shutdown drop safety | Shutdown Behavior | | ------------ | ---------------------- | ----------------------------- | | Tokio | Safe; no dangling refs | Drops safely sequenced | | async-std | Safe; no dangling refs | Safe; tasks are not dropped | | smol | Unsafe; deref unsound | Unsequenced; refs may dangle |
The Tokio runtime sequences shutdowns such that worker threads will block until the shutdown operation as completed. This ensures that all tasks will be dropped before any worker thread is dropped, and by virtue of this pointers to TLS variables upholding the pin drop guarantee and held within an async context are valid for all lifetimes except 'static without risk of dangling pointers.
The async-std runtime doesn't drop pending tasks when shutting down and hence avoids the possibility of dangling references occuring during drop altogether.
The Smol runtime should not be used in conjunction with async_local because pointers may dangle during drop when shutting down the runtime and cause undefined behavior.
This crate conditionally makes use of the nightly only feature typealiasimpltrait to allow AsyncLocal::withasync to be unboxed. To compile on stable the boxed feature flag can be be used to downgrade async_t::async_trait to async_trait::async_trait.