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.

1 files changed, 7 insertions, 4 deletions

diff --git a/library/std/src/thread/mod.rs b/library/std/src/thread/mod.rs
index ffdf4be1584..f33e785f96d 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
 ///