std: update TLS module documentation · rust-lang/rust@35f050b (original) (raw)

File tree

3 files changed

lines changed

3 files changed

lines changed

Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
1 -//! A lot of UNIX platforms don't have a way to register TLS destructors.
2 -//! Instead, we use one TLS key to register a callback which will run
3 -//! iterate through the destructor list.
1 +//! A lot of UNIX platforms don't have a specialized way to register TLS
2 +//! destructors for native TLS. Instead, we use one TLS key with a destructor
3 +//! that will run all native TLS destructors in the destructor list.
4 4
5 5 use crate::ptr;
6 6 use crate::sys::thread_local::destructors;
Original file line number Diff line number Diff line change
@@ -1,14 +1,10 @@
1 -//! An implementation of `const`-creatable TLS keys for non-Windows platforms.
1 +//! A `StaticKey` implementation using racy initialization.
2 2 //!
3 -//! Most OSs without native TLS will provide a library-based way to create TLS
4 -//! storage. For each TLS variable, we create a key, which can then be used to
5 -//! reference an entry in a thread-local table. This then associates each key
6 -//! with a pointer which we can get and set to store our data.
7 -//!
8 -//! Unfortunately, none of these platforms allows creating the key at compile-time,
9 -//! which means we need a way to lazily create keys (`StaticKey`). Instead of
10 -//! blocking API like `OnceLock`, we use racy initialization, which should be
11 -//! more lightweight and avoids circular dependencies with the rest of `std`.
3 +//! Unfortunately, none of the platforms currently supported by `std` allows
4 +//! creating TLS keys at compile-time. Thus we need a way to lazily create keys.
5 +//! Instead of blocking API like `OnceLock`, we use racy initialization, which
6 +//! should be more lightweight and avoids circular dependencies with the rest of
7 +//! `std`.
12 8
13 9 use crate::sync::atomic::{self, AtomicUsize, Ordering};
14 10
Original file line number Diff line number Diff line change
@@ -40,8 +40,13 @@ cfg_if::cfg_if! {
40 40 }
41 41 }
42 42
43 -/// This module maintains a list of TLS destructors for the current thread,
44 -/// all of which will be run on thread exit.
43 +/// The native TLS implementation needs a way to register destructors for its data.
44 +/// This module contains platform-specific implementations of that register.
45 +///
46 +/// It turns out however that most platforms don't have a way to register a
47 +/// destructor for each variable. On these platforms, we keep track of the
48 +/// destructors ourselves and register (through the [`guard`] module) only a
49 +/// single callback that runs all of the destructors in the list.
45 50 #[cfg(all(target_thread_local, not(all(target_family = "wasm", not(target_feature = "atomics")))))]
46 51 pub(crate) mod destructors {
47 52 cfg_if::cfg_if! {
@@ -91,7 +96,12 @@ mod guard {
91 96 }
92 97 }
93 98
94 -/// This module provides the `StaticKey` abstraction over OS TLS keys.
99 +/// `const`-creatable TLS keys.
100 +///
101 +/// Most OSs without native TLS will provide a library-based way to create TLS
102 +/// storage. For each TLS variable, we create a key, which can then be used to
103 +/// reference an entry in a thread-local table. This then associates each key
104 +/// with a pointer which we can get and set to store our data.
95 105 pub(crate) mod key {
96 106 cfg_if::cfg_if! {
97 107 if #[cfg(any(