Repository: tokio-rs/tokio
File: tokio/src/runtime/task/join.rs (Rust)

Code before:

use std::fmt;
use std::future::Future;
use std::marker::PhantomData;
use std::panic::{RefUnwindSafe, UnwindSafe};
use std::pin::Pin;
use std::task::{ready, Context, Poll, Waker};

cfg_rt! {
    /// An owned permission to join on a task (await its termination).
    ///
    /// This can be thought of as the equivalent of [`std::thread::JoinHandle`]
    /// for a Tokio task rather than a thread. Note that the background task
    /// associated with this `JoinHandle` started running immediately when you
    /// called spawn, even if you have not yet awaited the `JoinHandle`.
    ///
    /// A `JoinHandle` *detaches* the associated task when it is dropped, which
    /// means that there is no longer any handle to the task, and no way to `join`
    /// on it.
    ///
    /// This `struct` is created by the [`task::spawn`] and [`task::spawn_blocking`]
    /// functions.
    ///
    /// It is guaranteed that the spawned future's or function's destructor has finished
    /// before the task completion is observed, for example,
    /// via [`JoinHandle`] `await` or [`JoinHandle::is_finished`].
    ///
    /// # 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`]:
    ///
    /// ```
    /// use tokio::task;
    ///
    /// # async fn doc() {
    /// let join_handle: task::JoinHandle<_> = task::spawn(async {
    ///     // some work here
    /// });
    /// # }
    /// ```
    ///
    /// Creation from [`task::spawn_blocking`]:

Review comment (suggestion):
A few wording nits:
* You always spawn a future.
* The mentioned methods are the only way to observe task completion.

```suggestion
    /// It is guaranteed that the destructor of the future has finished
    /// before the task completion is observed via [`JoinHandle`] `await` or
    /// [`JoinHandle::is_finished`].
```


Code after:

use std::fmt;
use std::future::Future;
use std::marker::PhantomData;
use std::panic::{RefUnwindSafe, UnwindSafe};
use std::pin::Pin;
use std::task::{ready, Context, Poll, Waker};

cfg_rt! {
    /// An owned permission to join on a task (await its termination).
    ///
    /// This can be thought of as the equivalent of [`std::thread::JoinHandle`]
    /// for a Tokio task rather than a thread. Note that the background task
    /// associated with this `JoinHandle` started running immediately when you
    /// called spawn, even if you have not yet awaited the `JoinHandle`.
    ///
    /// A `JoinHandle` *detaches* the associated task when it is dropped, which
    /// means that there is no longer any handle to the task, and no way to `join`
    /// on it.
    ///
    /// This `struct` is created by the [`task::spawn`] and [`task::spawn_blocking`]
    /// functions.
    ///
    /// It is guaranteed that the destructor of the spawned task has finished
    /// before task completion is observed via `JoinHandle` `await`,
    /// [`JoinHandle::is_finished`] or [`AbortHandle::is_finished`].
    ///
    /// # 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`]:
    ///
    /// ```
    /// use tokio::task;
    ///
    /// # async fn doc() {
    /// let join_handle: task::JoinHandle<_> = task::spawn(async {
    ///     // some work here
    /// });
    /// # }
    /// ```
    ///
    /// Creation from [`task::spawn_blocking`]: