From 8d8f6995ce063fe812bb668a8b8fe4e5edf213ef Mon Sep 17 00:00:00 2001 From: Laurence Tratt Date: Sun, 11 Apr 2021 09:35:00 +0100 Subject: [PATCH 1/2] Clarify the guarantees that ThreadId does and doesn't make. The existing documentation does not spell out whether `ThreadId`s are unique during the lifetime of a thread or of a process. I had to examine the source code to realise (pleasingly!) that they're unique for the lifetime of a process. That seems worth documenting clearly, as it's a strong guarantee. Examining the way `ThreadId`s are created also made me realise that the `as_u64` method on `ThreadId` could be a trap for the unwary on those platforms where the platform's notion of a thread identifier is also a 64 bit integer (particularly if they happen to use a similar identifier scheme to `ThreadId`). I therefore think it's worth being even clearer that there's no relationship between the two. --- library/std/src/thread/mod.rs | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/library/std/src/thread/mod.rs b/library/std/src/thread/mod.rs index ffdf4be158457..f33e785f96dcd 100644 --- a/library/std/src/thread/mod.rs +++ b/library/std/src/thread/mod.rs @@ -965,10 +965,13 @@ pub fn park_timeout(dur: Duration) { /// A unique identifier for a running thread. /// -/// A `ThreadId` is an opaque object that has a unique value for each thread -/// that creates one. `ThreadId`s are not guaranteed to correspond to a thread's -/// system-designated identifier. A `ThreadId` can be retrieved from the [`id`] -/// method on a [`Thread`]. +/// A `ThreadId` is an opaque object that uniquely identifies each thread +/// created during the lifetime of a process. `ThreadId`s are guaranteed not to +/// be reused, even if a thread dies. `ThreadId`s are under the control of +/// Rust's standard library and there may not be any relationship between +/// `ThreadId` and the underlying platform's notion of a thread identifier -- +/// the two concepts cannot, therefore, be used interchangeably. A `ThreadId` +/// can be retrieved from the [`id`] method on a [`Thread`]. /// /// # Examples /// From d66a9e16bae86863cfdbd033b49b672da34bdde1 Mon Sep 17 00:00:00 2001 From: Laurence Tratt Date: Sat, 25 Dec 2021 15:18:55 +0000 Subject: [PATCH 2/2] Language tweak. --- library/std/src/thread/mod.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/library/std/src/thread/mod.rs b/library/std/src/thread/mod.rs index f33e785f96dcd..d1fe9260e529c 100644 --- a/library/std/src/thread/mod.rs +++ b/library/std/src/thread/mod.rs @@ -967,8 +967,8 @@ pub fn park_timeout(dur: Duration) { /// /// A `ThreadId` is an opaque object that uniquely identifies each thread /// created during the lifetime of a process. `ThreadId`s are guaranteed not to -/// be reused, even if a thread dies. `ThreadId`s are under the control of -/// Rust's standard library and there may not be any relationship between +/// be reused, even when a thread terminates. `ThreadId`s are under the control +/// of Rust's standard library and there may not be any relationship between /// `ThreadId` and the underlying platform's notion of a thread identifier -- /// the two concepts cannot, therefore, be used interchangeably. A `ThreadId` /// can be retrieved from the [`id`] method on a [`Thread`].