docs: clarify task ID reuse guarantees

Fixes: #7553

Author: OxleyS

tokio/src/runtime/task/id.rs

@@ -5,12 +5,18 @@ use std::{fmt, num::NonZeroU64};
 /// An opaque ID that uniquely identifies a task relative to all other currently
 /// running tasks.
 ///
+/// A task's ID may be re-used for another task only once *both* of the
+/// following happen:
+/// 1. The task itself exits.
+/// 2. The task's [`JoinHandle`](crate::task::JoinHandle) is either dropped, or
+///    joined on (for example, by `await`ing it to completion).
+///
 /// # Notes
 ///
-/// - Task IDs are unique relative to other *currently running* tasks. When a
-///   task completes, the same ID may be used for another task.
 /// - Task IDs are *not* sequential, and do not indicate the order in which
 ///   tasks are spawned, what runtime a task is spawned on, or any other data.
+/// - Holding an [`AbortHandle`](crate::task::AbortHandle) alone does not
+///   prevent a completed task's ID from being re-used.
 /// - The task ID of the currently running task can be obtained from inside the
 ///   task via the [`task::try_id()`](crate::task::try_id()) and
 ///   [`task::id()`](crate::task::id()) functions and from outside the task via

tokio/src/task/join_set.rs

@@ -295,7 +295,7 @@ impl<T: 'static> JoinSet<T> {
     ///
     /// This method is cancel safe. If `join_next_with_id` is used as the event in a `tokio::select!`
     /// statement and some other branch completes first, it is guaranteed that no tasks were
-    /// removed from this `JoinSet`.
+    /// removed from this `JoinSet`, nor any task's ID freed for re-use by another task.
     ///
     /// [task ID]: crate::task::Id
     /// [`JoinError::id`]: fn@crate::task::JoinError::id
@@ -535,7 +535,9 @@ impl<T: 'static> JoinSet<T> {
     ///  * `Poll::Ready(None)` if the `JoinSet` is empty.
     ///
     /// Note that this method may return `Poll::Pending` even if one of the tasks has completed.
-    /// This can happen if the [coop budget] is reached.
+    /// This can happen if the [coop budget] is reached. However, the task's `JoinHandle` is only
+    /// consumed (and the task ID freed for potential re-use) if this method returns
+    /// `Poll::Ready(Some(_))`.
     ///
     /// [coop budget]: crate::task::coop#cooperative-scheduling
     /// [task ID]: crate::task::Id