std: update TLS module documentation · rust-lang/rust@35f050b

File tree

3 files changed

lines changed

  • library/std/src/sys/thread_local

3 files changed

lines changed

Original file line numberDiff line numberDiff 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.

44
55

use crate::ptr;

66

use crate::sys::thread_local::destructors;

Original file line numberDiff line numberDiff 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.

22

//!

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`.

128
139

use crate::sync::atomic::{self, AtomicUsize, Ordering};

1410
Original file line numberDiff line numberDiff line change

@@ -40,8 +40,13 @@ cfg_if::cfg_if! {

4040

}

4141

}

4242
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.

4550

#[cfg(all(target_thread_local, not(all(target_family = "wasm", not(target_feature = "atomics")))))]

4651

pub(crate) mod destructors {

4752

cfg_if::cfg_if! {

@@ -91,7 +96,12 @@ mod guard {

9196

}

9297

}

9398
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.

95105

pub(crate) mod key {

96106

cfg_if::cfg_if! {

97107

if #[cfg(any(