task: make JoinHandle::abort_handle public

tokio/src/runtime/task/join.rs

@@ -182,8 +182,9 @@ impl<T> JoinHandle<T> {
     /// ```rust
     /// use tokio::time;
     ///
-    /// #[tokio::main]
-    /// async fn main() {
+    /// # #[tokio::main(flavor = "current_thread")]
+    /// # async fn main() {
+    /// #  tokio::time::pause();
     ///    let mut handles = Vec::new();
     ///
     ///    handles.push(tokio::spawn(async {
@@ -203,7 +204,7 @@ impl<T> JoinHandle<T> {
     ///    for handle in handles {
     ///        assert!(handle.await.unwrap_err().is_cancelled());
     ///    }
-    /// }
+    /// # }
     /// ```
     /// [cancelled]: method@super::error::JoinError::is_cancelled
     pub fn abort(&self) {
@@ -252,7 +253,42 @@ impl<T> JoinHandle<T> {
     }
 
     /// Returns a new `AbortHandle` that can be used to remotely abort this task.
-    pub(crate) fn abort_handle(&self) -> super::AbortHandle {
+    ///
+    /// Awaiting a task cancelled by the `AbortHandle` might complete as usual if the task was
+    /// already completed at the time it was cancelled, but most likely it
+    /// will fail with a [cancelled] `JoinError`.
+    ///
+    /// ```rust
+    /// use tokio::{time, task};
+    ///
+    /// # #[tokio::main(flavor = "current_thread")]
+    /// # async fn main() {
+    /// #  time::pause();
+    ///    let mut handles = Vec::new();
+    ///
+    ///    handles.push(tokio::spawn(async {
+    ///       time::sleep(time::Duration::from_secs(10)).await;
+    ///       true
+    ///    }));
+    ///
+    ///    handles.push(tokio::spawn(async {
+    ///       time::sleep(time::Duration::from_secs(10)).await;
+    ///       false
+    ///    }));
+    ///
+    ///    let abort_handles: Vec<task::AbortHandle> = handles.iter().map(|h| h.abort_handle()).collect();
+    ///
+    ///    for handle in abort_handles {
+    ///        handle.abort();
+    ///    }
+    ///
+    ///    for handle in handles {
+    ///        assert!(handle.await.unwrap_err().is_cancelled());
+    ///    }
+    /// # }
+    /// ```
+    /// [cancelled]: method@super::error::JoinError::is_cancelled
+    pub fn abort_handle(&self) -> super::AbortHandle {
         self.raw.ref_inc();
         super::AbortHandle::new(self.raw)
     }