JoinSet, clarify behaviour of blocking code under abort/drop

tokio/src/task/join_set.rs

@@ -23,7 +23,10 @@ use crate::util::IdleNotifiedSet;
 ///
 /// All of the tasks must have the same return type `T`.
 ///
-/// When the `JoinSet` is dropped, all tasks in the `JoinSet` are immediately aborted.
+/// When the `JoinSet` is dropped, all *async* tasks in the `JoinSet` are
+/// immediately aborted. Tasks spawned with [`spawn_blocking`] or
+/// [`spawn_blocking_on`] can only be aborted before they start running.
+/// This is because they are not *async*, see [task cancellation].
 ///
 /// # Examples
 ///
@@ -51,6 +54,9 @@ use crate::util::IdleNotifiedSet;
 ///     }
 /// }
 /// ```
+/// [`spawn_blocking`]: fn@Self::spawn_blocking
+/// [`spawn_blocking_on`]: fn@Self::spawn_blocking_on
+/// [task cancellation]: crate::task#cancellation
 #[cfg_attr(docsrs, doc(cfg(feature = "rt")))]
 pub struct JoinSet<T> {
     inner: IdleNotifiedSet<JoinHandle<T>>,
@@ -205,6 +211,9 @@ impl<T: 'static> JoinSet<T> {
     /// it in this `JoinSet`, returning an [`AbortHandle`] that can be
     /// used to remotely cancel the task.
     ///
+    /// Note that this task can only be aborted before it starts running.
+    /// This is because they are not *async*, see [task cancellation].
+    ///
     /// # Examples
     ///
     /// Spawn multiple blocking tasks and wait for them.
@@ -237,6 +246,7 @@ impl<T: 'static> JoinSet<T> {
     /// This method panics if called outside of a Tokio runtime.
     ///
     /// [`AbortHandle`]: crate::task::AbortHandle
+    /// [task cancellation]: crate::task#cancellation
     #[track_caller]
     pub fn spawn_blocking<F>(&mut self, f: F) -> AbortHandle
     where
@@ -251,6 +261,9 @@ impl<T: 'static> JoinSet<T> {
     /// provided runtime and store it in this `JoinSet`, returning an
     /// [`AbortHandle`] that can be used to remotely cancel the task.
     ///
+    /// Note that this task can only be aborted before it starts running.
+    /// This is because they are not *async*, see [task cancellation].
+    ///
     /// [`AbortHandle`]: crate::task::AbortHandle
     #[track_caller]
     pub fn spawn_blocking_on<F>(&mut self, f: F, handle: &Handle) -> AbortHandle
@@ -367,8 +380,16 @@ impl<T: 'static> JoinSet<T> {
     /// This method ignores any panics in the tasks shutting down. When this call returns, the
     /// `JoinSet` will be empty.
     ///
+    /// Note that tasks spawned with [`spawn_blocking`] or [`spawn_blocking_on`]
+    /// can not be aborted after they start running. This is because they are not
+    /// *async*, see [task cancellation]. These tasks may cause the call to shutdown to
+    /// block.
+    ///
     /// [`abort_all`]: fn@Self::abort_all
     /// [`join_next`]: fn@Self::join_next
+    /// [`spawn_blocking`]: fn@Self::spawn_blocking
+    /// [`spawn_blocking_on`]: fn@Self::spawn_blocking_on
+    /// [task cancellation]: crate::task#cancellation
     pub async fn shutdown(&mut self) {
         self.abort_all();
         while self.join_next().await.is_some() {}
@@ -451,6 +472,15 @@ impl<T: 'static> JoinSet<T> {
     ///
     /// This does not remove the tasks from the `JoinSet`. To wait for the tasks to complete
     /// cancellation, you should call `join_next` in a loop until the `JoinSet` is empty.
+    ///
+    /// Note that tasks spawned with [`spawn_blocking`] or [`spawn_blocking_on`]
+    /// can not be aborted after they start running. This is because they are not
+    /// *async*, see [task cancellation]. These tasks may cause the call to shutdown to
+    /// block.
+    ///
+    /// [`spawn_blocking`]: fn@Self::spawn_blocking
+    /// [`spawn_blocking_on`]: fn@Self::spawn_blocking_on
+    /// [task cancellation]: crate::task#cancellation
     pub fn abort_all(&mut self) {
         self.inner.for_each(|jh| jh.abort());
     }