rust-lang / rust-lang/rust

Document thread_local behavior with foreign-created threads

Open
#136,546 3 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

A-docs A-thread-locals T-libs
Dominant language
Rust
Stars
119k
Forks
16.1k
PR merge metrics
PR metrics pending

Description

Location

https://doc.rust-lang.org/std/macro.thread_local.html
https://doc.rust-lang.org/std/thread/struct.LocalKey.html

Summary

Rust can be used as a static or dynamic library in a host process in another language/runtime. The thread_local documentation makes no mention about how foreign threads behave with respect to to thread locals created via LocalKey or the !thread_local macro.

I think it is safe, with one possible exception. I think the const {} syntax allows Rust to avoid lazy initialization and instead use a more efficient implementation that may rely on statically allocated thread-local storage (TLS) instead of dynamically allocated TLS keys. I do not see how this would work with foreign-created threads that call into Rust.

Researching this has proved difficult, I think the docs should clarify the behavior and what is guaranteed and what isn't when it comes to foreign-created threads.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the documentation at std::thread_local and std:🧵:LocalKey, then investigate the behavior of foreign-created threads calling into Rust. Document what is guaranteed for LocalKey and the thread_local! macro, including the const {} case and any limitations, so the two linked pages clearly explain the supported behavior.

Written by the indexing model from the issue text.

Assessment

Tech stack
rust
Domain
documentation, operating-systems
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
38/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.