From bdbb0ece10e654b9e265364a6b39439d85bf7601 Mon Sep 17 00:00:00 2001
From: Alice Ryhl <alice@ryhl.io>
Date: Thu, 11 Aug 2022 04:17:03 -0700
Subject: [PATCH] task: add cancel safety docs to `JoinHandle` (#4901)

---
 tokio/src/runtime/task/join.rs | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/tokio/src/runtime/task/join.rs b/tokio/src/runtime/task/join.rs
index a04ec956a..018e1898d 100644
--- a/tokio/src/runtime/task/join.rs
+++ b/tokio/src/runtime/task/join.rs
@@ -20,6 +20,15 @@ cfg_rt! {
     /// This `struct` is created by the [`task::spawn`] and [`task::spawn_blocking`]
     /// functions.
     ///
+    /// # Cancel safety
+    ///
+    /// The `&mut JoinHandle<T>` type is cancel safe. If it is used as the event
+    /// in a `tokio::select!` statement and some other branch completes first,
+    /// then it is guaranteed that the output of the task is not lost.
+    ///
+    /// If a `JoinHandle` is dropped, then the task continues running in the
+    /// background and its return value is lost.
+    ///
     /// # Examples
     ///
     /// Creation from [`task::spawn`]: