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.
This commit is contained in:
Laurence Tratt 2021-04-11 09:35:00 +01:00
parent 28b948fc5c
commit 8d8f6995ce

View file

@ -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
///