Traditionally the downside of thread-locals has been that usage is constrained to the LocalKey::with closure with no lifetime escapement thus preventing immutable references and limiting usability in async context. This makes a lot of sense: the lifetime of unscoped threads is indeterminate, and references may dangle should threads outlive what they reference. There is however an escape hatch to these limitations: by utilizing a synchronization barrier across all runtime worker threads as a guard to protect the destruction of thread local data, runtime shutdowns can be sequenced in a way that guarantees no task be dropped after this barrier, and in doing so it can be ensured that so long as the pin drop guarantee is upheld, pointers to thread local data created within an async context and held therein will never dangle. This crate provides safe abstractions such as AsyncLocal::with_async, the async counterpart of LocalKey::with, 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.
The only requirement for async runtimes to be compatible with async-local is that pending async tasks aren't dropped by thread local destructors. The Tokio runtime ensures this by sequencing shutdowns.
| Runtime | Support | Shutdown Behavior | | --------- | ------------- | -------------------------------------- | | Tokio | Supported | Tasks dropped during shutdown sequence | | async-std | Supported | Tasks forgotten | | smol | Not Supported | Tasks dropped by TLS destructors |
See doomsday-clock for runtime shutdown safety tests.
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 used to downgrade asynct::asynctrait to asynctrait::asynctrait.