Traditionally the downside of thead-locals has been that usage is constrainted to the LocalKey::with closure with no lifetime escapement, the rationale being that anything beyond this is of an indeterminate lifetime. There is however a way around this limitation: by using a barrier to guard against thread local destruction until worker threads shutting down can rendezvous, no tasks will outlive thread local data belonging to any worker thread, and all pointers to thread locals created within an async context and held therein will be of a valid lifetime. Utilizing this barrier mechanism, this crate introduces AsyncLocal::with_async, the async counterpart of LocalKey::with, as well as the unsafe pointer types and safety considerations foundational for using thread local data within an async context and across await points.
The only requirement for async runtimes to be compatible with async-local is that upon shutdown pending async tasks aren't dropped by thread local destructors.
| Runtime | Feature Flag | Shutdown Behavior |
| --------- | ------------------- | -------------------------------------- |
| Tokio | tokio-runtime | Tasks dropped during shutdown sequence |
| async-std | async-std-runtime | 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.