thread_local! foreign threads docs

[ArkadySkv]

Document thread_local! foreign thread behavior

This PR adds comprehensive documentation about thread_local! and LocalKey
behavior when used in dynamic libraries loaded by foreign runtimes.

Research Basis

• 6 languages tested: C, C++, Rust, Go, Python, Ruby
• 12+ test scenarios: Sync and async patterns
• 50+ thread executions: Observed under various conditions
• Unix/Linux focus: Tested on pthreads-based systems

Key Findings

• ✅ Works with native OS threads (pthreads, Windows threads)
• ✅ Compatible with Go goroutines via CGO binding
• ✅ Works with Python threading and Ruby green threads
• ✅ Consistent behavior across all tested environments

Documentation Added

• Foreign thread compatibility matrix
• Practical usage examples with #[no_mangle]
• Platform considerations (Unix/Windows)
• Caveats for exotic runtimes

Issue: #136546

r? rust-lang/libs-team

[rustbot]

Team or group rust-lang/libs-team not found.

rust-lang team names can be found at https://github.com/rust-lang/team/tree/master/teams.
Reviewer group names can be found in triagebot.toml in this repo.

[rustbot]

r? @Mark-Simulacrum

rustbot has assigned @Mark-Simulacrum.
They will have a look at your PR within the next two weeks and either review your PR or reassign to another reviewer.

Use r? to explicitly pick a reviewer

[Noratrieb]

Both the description and content of this PR appear to be AI-generated. We are not interested in AI-generated PRs.

[rust-log-analyzer]

The job aarch64-gnu-llvm-20-2 failed! Check out the build log: (web) (plain enhanced) (plain)

Click to see the possible cause of the failure (guessed by this bot)

 Documenting std v0.0.0 (/checkout/library/std)
error: unresolved link to `with`
  --> library/std/src/thread/local.rs:13:29
   |
13 | /// primary method is the [`with`] method, though there are helpers to make
   |                             ^^^^ no item named `with` in scope
   |
   = help: to escape `[` and `]` characters, add '\' before them like `\[` or `\]`
   = note: `-D rustdoc::broken-intra-doc-links` implied by `-D warnings`
   = help: to override `-D warnings` add `#[allow(rustdoc::broken_intra_doc_links)]`

error: unresolved link to `with`
  --> library/std/src/thread/local.rs:16:11
   |
16 | /// The [`with`] method yields a reference to the contained value which cannot
   |           ^^^^ no item named `with` in scope
   |
   = help: to escape `[` and `]` characters, add '\' before them like `\[` or `\]`

error: unresolved link to `with`
  --> library/std/src/thread/local.rs:24:7
   |
24 | /// [`with`]) within a thread, and values that implement [`Drop`] get
   |       ^^^^ no item named `with` in scope
   |
   = help: to escape `[` and `]` characters, add '\' before them like `\[` or `\]`

error: could not parse code block as Rust code
  --> library/std/src/thread/local.rs:54:5
---
 96 | | ///
 97 | | /// # Platform-specific behavior
 98 | | ///
...   |
127 | | /// [`JoinHandle::join`]: crate::thread::JoinHandle::join
128 | | /// [`with`]: LocalKey::with
    | |____________________________^
    |
    = note: error from rustc: prefix `it` is unknown
    = note: error from rustc: unknown start of token: `
    = note: error from rustc: unknown start of token: `
---
   = note: `-D rustdoc::invalid-html-tags` implied by `-D warnings`
   = help: to override `-D warnings` add `#[allow(rustdoc::invalid_html_tags)]`
help: try marking as source code
   |
40 | /// static DATA: `LocalKey<RefCell<String>>` = {
   |                  +                         +

error: unclosed HTML tag `String`
  --> library/std/src/thread/local.rs:42:32
   |
42 | ///         static KEY: RefCell<String> = RefCell::new(String::new());
   |                                ^^^^^^^^
   |
help: try marking as source code
   |
42 | ///         static KEY: `RefCell<String>` = RefCell::new(String::new());
   |                         +               +

error: unclosed HTML tag `u32`
  --> library/std/src/thread/local.rs:79:35
   |
79 | /// thread_local!(static FOO: Cell<u32> = const { Cell::new(1) });
   |                                   ^^^^^
   |
help: try marking as source code
   |
79 | /// thread_local!(static FOO: `Cell<u32>` = const { Cell::new(1) });
   |                               +         +

error: could not document `std`
warning: build failed, waiting for other jobs to finish...
[RUSTC-TIMING] std test:false 6.602
Command `/checkout/obj/build/aarch64-unknown-linux-gnu/stage0/bin/cargo doc --target aarch64-unknown-linux-gnu -Zbinary-dep-depinfo -j 4 -Zroot-dir=/checkout --locked --color always --release --features 'backtrace panic-unwind compiler-builtins-c' --manifest-path /checkout/library/sysroot/Cargo.toml --no-deps --target-dir /checkout/obj/build/aarch64-unknown-linux-gnu/stage1-std/aarch64-unknown-linux-gnu/doc -Zskip-rustdoc-fingerprint -Zrustdoc-map -p alloc -p compiler_builtins -p core -p panic_abort -p panic_unwind -p proc_macro -p rustc-std-workspace-core -p std -p std_detect -p sysroot -p test -p unwind [workdir=/checkout]` failed with exit code 101
Created at: src/bootstrap/src/core/build_steps/doc.rs:777:21
Executed at: src/bootstrap/src/core/build_steps/doc.rs:814:22

Command has failed. Rerun with -v to see more details.
Bootstrap failed while executing `--stage 2 test --skip tests --skip coverage-map --skip coverage-run --skip library --skip tidyselftest`
Build completed unsuccessfully in 0:31:04
  local time: Tue Sep 23 10:42:18 UTC 2025
  network time: Tue, 23 Sep 2025 10:42:18 GMT
##[error]Process completed with exit code 1.

[ArkadySkv]

@Noratrieb, I understand the concern about AI-generated content, but I want to clarify that this PR is based on my own empirical research. I conducted extensive testing across C, C++, Go, Python, and Ruby to understand thread_local! behavior with foreign threads. I'm happy to discuss the research methodology or make any changes needed.

[Noratrieb]

Research into the problem space is welcome, as long as that research was conducted with an appropriate amount of AI usage (as otherwise the data may just all be wrong).
As for the wording of the docs, I think the docs should look quite different. Currently it looks very handwavy and unclear, I think it should be clearer about what mechanisms are used (namely either dynamic key-based TLS or static binary-format-based TLS when const {} is used) (there are probably better words for it), and how it always integrates properly with the underlying OS mechanisms, so as long as they are used it's compatible. I wouldn't put testing results into docs.
And while you're not forbidden from using AI a bit to help you think about the best wording, we want the docs written by humans, to avoid both the potential mistakes from AI and the often unnecessary fluff that comes from it. It should look natural and easy to read, which is usually the opposite of what AIs output.
For the PR description, it's the same. We want to get the information you're trying to convey in the easiest way to understand, where all the fluff from AI (which cannot add any information for the context of a PR description) useless. Write the descriptions yourself, as if you're trying to explain the background, motivation, and other potentially releveant details that can't trivially be understood by looking at the diff behind the change.