Implement Thread::os_id

[valentynkit]

Implements Thread::os_id as an unstable feature, per the accepted ACP rust-lang/libs-team#635.

Tracking issue: #160215

os_id returns the OS-level thread id, so Rust programs can tie their own logs to system-level logs (the ACP's stated motivation).

It's a snapshot taken when the thread starts running: the OS can reuse a TID after the thread that held it exits, so it isn't guaranteed to be unique.
The std Thread can outlive the OS-level thread, so os_id can go stale. It has no guaranteed relation to ThreadId.

Implementation

Based on the decision in the ACP, Thread does not store a pthread_t; the two have separate lifecycles.
pthread_t goes invalid on join or detach, Thread is an Arc and outlives that.

Not storing a pthread_t inside the std Thread is why it can't be queried on demand. Even when a pthread_t exists (on the native handle), some platforms have no by-handle query at all, or it isn't plumbed through Rust's libc. (details below)

That's why os_id does not represent direct, up-to-date information but rather a snapshot of the os_id when the thread starts.

There are 2 categories of handle creation (3 call sites):

1. By the current thread itself (init_current, current_or_unnamed), which run on the thread being described, so they build the handle with Thread::new_current, which fills os_id immediately with the right one.
2. By the spawning thread before the child exists (spawn_unchecked); the important parts of the lifecycle are described below:
   t0. Thread::new lifecycle.rs:48 (imp::current_os_id() returns the parent's TID) - this is why we can't set os_id inside Thread::new, it will assign parent TID to child Thread.
   run_spawn_hooks(&thread) lifecycle.rs:53 - user code already holds &Thread here, but no related OS thread exists yet. As long as hooks are handed a &Thread before creation, no design can close that window.
   t1. imp::Thread::new lifecycle.rs:116 - (imp::current_os_id() still returns the parent's TID during the call), the only way to get os_id here, once it returns, is by querying handle, not current_os_id.
   t2. thread_start runs ThreadInit::init lifecycle.rs:146, using imp::current_os_id() and setting the thread's os_id.

The earliest time we could get os_id is t1, by querying the handle. (Current PR handles t2 case)

Only the spawn path writes late, and by then the handle is already shared: the parent can call (JoinHandle::thread().os_id() before join(), for example). So the field needs synchronization.

The field is set after the handle already exists, once the thread is running; if it hasn't started yet, os_id gives None.
The signature matches the ACP's fn os_id(&self) -> Option<u64>, but the reason is new - the ACP's None meant "platform doesn't support it", not-yet-started is an extra case represented by None state for os_id.

The following options were considered for the Thread::os_id synchronization primitive:

1. Atomic<u64> and 0 sentinel, nothing guarantees OS tid is never 0, also for targets without 64-bit atomics platform specific handling will be needed (cfg_select!) - OnceLock needs none of that.
2. Using OnceLock::wait would change an accessor into a blocking call: if imp::Thread::new returns Err, os_id is never set, and wait() would hang forever - that's why it isn't used here.

Further improvements

This PR is a starting point, there is room for further improvements and refinements for os_id in follow up PRs.
In spawn path os_id is filled by the child itself when it starts, further improvements could aim for setting os_id by parent right after child thread is created, by querying the handle to get os_id from pthread, platform specific interfaces exist for some platforms. Making current approach (child itself set os_id on start) as fallback for cases when platform doesn't support querying by handle.

It could introduce the race. A parent-side fill after creating a thread and the child's own write at start (self.handle.set_os_id_to_current()) would both write the same field, concurrently.
OnceLock already absorbs that today - thread.rs:132, let _ = self.inner.os_id.set(os_id) - one set wins, the other's Err is discarded.
That's why OnceLock stays under this design rather than being replaced by anything else.

Per platform:

Platform	Symbol	In libc crate?
Apple	pthread_threadid_np	yes
illumos/Solaris	pthread_t is the tid	n/a
Windows	GetThreadId	n/a
Android (bionic)	pthread_gettid_np	yes
Linux/glibc	pthread_gettid_np, glibc 2.42+	yes
musl	no such symbol	-
FreeBSD/NetBSD/OpenBSD	self-only functions	-

Sketch, per platform:

// sys/thread/unix.rs
impl Thread {
    pub fn os_id(&self) -> Option<u64> { ... }
}

And in spawn_unchecked, right after creation succeeds:

let native = unsafe { imp::Thread::new(stack_size, init)? };
thread.set_os_id(native.os_id());  
Ok(JoinInner { native, thread, packet: my_packet })

Cost. A new imp::Thread::os_id() needs an arm in each platform that support it.

Testing

On aarch64-apple-darwin:

• ./x check library/std
• ./x test library/std --no-doc --test-args thread_os_id, 3 passed (the two new ones and the existing test_thread_os_id_not_equal)
• ./x test library/std --doc --test-args os_id, 1 passed
• ./x fmt --check --all reports no changes

r? libs

[joboet]

Nothing guarantees that the OS's ID is non-zero, we really shouldn't use zero as a sentinel.

View changes since the review

[valentynkit]

Switched to OnceLock: write-once without a sentinel, and it needs no 64-bit atomic so the cfg_select is gone too.

Waiting would need the child to always store the value, so OnceLock<Option>.
I'm also not sure how it works out for spawn hooks, which get &Thread on the parent before the thread exists.
You mentioned you have an implementation, so if you've already worked that out I'd rather build on it than guess.

[rustbot]

Reminder, once the PR becomes ready for a review, use @rustbot ready.

[valentynkit]

@rustbot ready

[joboet]

A meta comment: I appreciate your recent contributions to the project, you are clearly interested in helping out and invest time and thought into it. At the same time, especially the description of this PR makes it very obvious that you are using a LLM to aid you in your contributions, both in writing code and comments. These kinds of cases have been very intensely discussed within the project, and the result of that discussion is our LLM policy that will come into effect next week. Under that policy your LLM usage is deemed forbidden, and failing to declare it (like you have been doing) may result in moderation actions against you.

I'm not a moderator, and this is not a moderation warning, just some friendly advice that I want to give you, stemming from years of working on the standard library:

In my experience, the hard part about working on the standard library is not actually writing the code, but in

1. Doing the research and taking the thinking time to verify that the changes are truly correct. The standard library ships on literally billions of devices, we must try very hard to ensure that it works as intended.
2. Communicating that work to other people so that not just you, but the person reviewing your work (in this case, me) and everyone else can follow along.

An LLM can do neither those things. While they are admittedly good at doing the mechanical task of writing the code, they are awfully unreliable when it comes to providing evidence, have little to no intrinsic capability to exercise good judgement and are fundamentally just not you.

As an example, the current description of this PR is mostly just a very detailed summary of its changes. I can see those myself, thank you very much, that's what the "Files changed" tab is for! The much more interesting questions in this case are e.g. why OnceLock is correct in this case (both you and me need to think this through in any case, the LLM cannot lift that responsibility off our shoulders), or how one might do better (here you'd need e.g. links to platform documentation – which is rather difficult for an LLM to find especially in the curious case of pthread_gettid_np), or why this PR is still a good point to start from (that's a matter of taste and opinion, I see why one might argue that it is). And if you've thought about all these questions, then writing these kinds of PRs entirely on your own is actually easier than proofreading the LLMs output and explaining all your thoughts to it.

Thus, please, remember to take time to think and research and be the author, not just the editor, of your communication and your code. If you want to learn how best to use (or not use) LLMs, feel free to join our LLM-mentoring channel on Zulip.

As for me, I'm not interested in some stochastic parrot's output, but in other people's, since that's what I learn and thrive from. That's why I invest my time in this project anyway, and am very happy to help other people out if they get stuck. I must insist however that the responsibility of doing the thinking and research doesn't fall on my shoulders alone.

@rustbot author
until you update the PR description with something entirely of your own.

[valentynkit]

In my experience, the hard part about working on the standard library is not actually writing the code, but in

1. Doing the research and taking the thinking time to verify that the changes are truly correct. The standard library ships on literally _billions_ of devices, we must try very hard to ensure that it works as intended.

2. Communicating that work to other people so that not just you, but the person reviewing your work (in this case, me) and everyone else can follow along.

Thanks for your advice, I totally agree with inappropriate use of LLM in this PR, I usually trying to take more time preparing the PR and understanding all the nuances, this one was bad and too heavily relied on AI.

Thanks and I will take it into consideration.

As for this PR, I will take some time to really reason about it and also consider other approaches.
Especially about using OnceLock or alternative approaches.

Sorry for that. :)

[tgross35]

Could this do the assert_ne! test here? I think that demos relevant properties a bit better.

View changes since the review

[valentynkit]

Thanks, applied the changes but guarded it so it will not fail on other platforms that do not support os_id and could return None making it fail.

[tgross35]

It's usable for any thread that is running, not just the current right?

I think the property to convey is that OS TIDs uniquely represent a thread among other running threads, which effectively means that if a thread isn't known to be running then ID can only be used in cases where non-uniqueness is okay (e.g. logging). And then one way to know the thread is running is if you're looking at the current thread's ID.

Not sure how best to put this into words.

View changes since the review

[valentynkit]

So there are conditions under which it is safe to use os_id and it refers to correct thread, however in other conditions it should be used only for cases when stale os_id reference is harmless, like logging.

I have tried to reword this section to better communicate this, thank. Let me know if you see any better way to put this into words.

[teor2345]

Some sandboxes or containers allow per-function filtering, so it is also possible the thread ID exists with an API to read it, but the process can't do that.

Suggested change

	/// it. `None` means the platform has no such id or offers no way to read it,
	/// it. `None` means the platform has no such id or it can't be read,

View changes since the review

[valentynkit]

Thanks, applied your suggestion to reword it slightly.

[Darksonn]

Why doesn't Thread::new just call set_os_id_to_current internally?

If there are callers where this doesn't work, maybe we should have two constructors?

• Thread::new_current uses current OS id
• Thread::new_remote takes OS id as paramter

I think this would also avoid the OnceLock.

View changes since the review

[valentynkit]

I added Thread::new_current just for the current path, however I think we couldn't get rid of sync primitives for os_id because of the spawn_unchecked path, in that case when we create the Thread, we are still running on parent thread, so using set_os_id_to_current would assign parent os_id to child thread that it is trying to spawn.

1. Thread::new lifecycle.rs:48 (imp::current_os_id() returns the parent's TID)
2. imp::Thread::new lifecycle.rs:116

[valentynkit]

@rustbot ready

I have addressed suggested refinements.

PR body was updated to better explain decisions for the implementation and further possible refinements, it is pretty long and detailed but I think those nuances worth explaining properly.

[Darksonn]

Sorry I'm at capacity for the next two weeks.

@rustbot reroll