Skip to content

Commit

Permalink
std: update TLS module documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
joboet committed Jun 17, 2024
1 parent 00d4964 commit 2b9a4f3
Show file tree
Hide file tree
Showing 3 changed files with 22 additions and 16 deletions.
6 changes: 3 additions & 3 deletions std/src/sys/thread_local/guard/key.rs
Original file line number Diff line number Diff line change
@@ -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;
Expand Down
16 changes: 6 additions & 10 deletions std/src/sys/thread_local/key/racy.rs
Original file line number Diff line number Diff line change
@@ -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};

Expand Down
16 changes: 13 additions & 3 deletions std/src/sys/thread_local/mod.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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! {
Expand Down Expand Up @@ -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(
Expand Down

0 comments on commit 2b9a4f3

Please sign in to comment.