diff --git a/library/std/src/sys/thread_local/guard/key.rs b/library/std/src/sys/thread_local/guard/key.rs index e235daf3cc9d9..ee9d55ddd5e8e 100644 --- a/library/std/src/sys/thread_local/guard/key.rs +++ b/library/std/src/sys/thread_local/guard/key.rs @@ -1,6 +1,6 @@ -//! A lot of UNIX platforms don't have a way to register TLS destructors. -//! Instead, we use one TLS key to register a callback which will run -//! iterate through the destructor list. +//! A lot of UNIX platforms don't have a specialized way to register TLS +//! destructors for native TLS. Instead, we use one TLS key with a destructor +//! that will run all native TLS destructors in the destructor list. use crate::ptr; use crate::sys::thread_local::destructors; diff --git a/library/std/src/sys/thread_local/key/racy.rs b/library/std/src/sys/thread_local/key/racy.rs index e2eaca197d403..eda8b83bc7f03 100644 --- a/library/std/src/sys/thread_local/key/racy.rs +++ b/library/std/src/sys/thread_local/key/racy.rs @@ -1,14 +1,10 @@ -//! An implementation of `const`-creatable TLS keys for non-Windows platforms. +//! A `StaticKey` implementation using racy initialization. //! -//! Most OSs without native TLS will provide a library-based way to create TLS -//! storage. For each TLS variable, we create a key, which can then be used to -//! reference an entry in a thread-local table. This then associates each key -//! with a pointer which we can get and set to store our data. -//! -//! Unfortunately, none of these platforms allows creating the key at compile-time, -//! which means we need a way to lazily create keys (`StaticKey`). Instead of -//! blocking API like `OnceLock`, we use racy initialization, which should be -//! more lightweight and avoids circular dependencies with the rest of `std`. +//! Unfortunately, none of the platforms currently supported by `std` allows +//! creating TLS keys at compile-time. Thus we need a way to lazily create keys. +//! Instead of blocking API like `OnceLock`, we use racy initialization, which +//! should be more lightweight and avoids circular dependencies with the rest of +//! `std`. use crate::sync::atomic::{self, AtomicUsize, Ordering}; diff --git a/library/std/src/sys/thread_local/mod.rs b/library/std/src/sys/thread_local/mod.rs index aa2dd48ab49c3..ef525dd632167 100644 --- a/library/std/src/sys/thread_local/mod.rs +++ b/library/std/src/sys/thread_local/mod.rs @@ -40,8 +40,13 @@ cfg_if::cfg_if! { } } -/// This module maintains a list of TLS destructors for the current thread, -/// all of which will be run on thread exit. +/// The native TLS implementation needs a way to register destructors for its data. +/// This module contains platform-specific implementations of that register. +/// +/// It turns out however that most platforms don't have a way to register a +/// destructor for each variable. On these platforms, we keep track of the +/// destructors ourselves and register (through the [`guard`] module) only a +/// single callback that runs all of the destructors in the list. #[cfg(all(target_thread_local, not(all(target_family = "wasm", not(target_feature = "atomics")))))] pub(crate) mod destructors { cfg_if::cfg_if! { @@ -91,7 +96,12 @@ mod guard { } } -/// This module provides the `StaticKey` abstraction over OS TLS keys. +/// `const`-creatable TLS keys. +/// +/// Most OSs without native TLS will provide a library-based way to create TLS +/// storage. For each TLS variable, we create a key, which can then be used to +/// reference an entry in a thread-local table. This then associates each key +/// with a pointer which we can get and set to store our data. pub(crate) mod key { cfg_if::cfg_if! { if #[cfg(any(