Структура JoinHandle

Владеющее разрешение на присоединение к задаче (ожидание её завершения).

Это можно считать эквивалентом std::thread::JoinHandle для задачи Tokio, а не потока. Обратите внимание, что фоновая задача, связанная с этим JoinHandle, начинает выполняться сразу после вызова spawn, даже если вы ещё не ожидали JoinHandle.

При удалении JoinHandle связанная задача отсоединяется, то есть дескриптора этой задачи больше не существует и её нельзя join.

Этот struct создаётся функциями task::spawn и task::spawn_blocking.

Гарантируется, что деструктор запущенной задачи завершит работу до того, как завершение задачи будет обнаружено через JoinHandle await, JoinHandle::is_finished или AbortHandle::is_finished.

Безопасность при отмене

Ожидание &mut JoinHandle<T> безопасно при отмене. Если оно используется в качестве ветви в tokio::select! и первой завершается другая ветвь, гарантируется, что результат задачи не будет потерян.

Если JoinHandle удаляется, задача продолжает выполняться в фоновом режиме, а её возвращаемое значение теряется.

Примеры

Создание с помощью task::spawn:

use tokio::task;

let join_handle: task::JoinHandle<_> = task::spawn(async {
    // some work here
});

Создание с помощью task::spawn_blocking:

use tokio::task;

let join_handle: task::JoinHandle<_> = task::spawn_blocking(|| {
    // some blocking work here
});

Параметр типа T в JoinHandle<T> — это тип возвращаемого значения запущенной задачи. Если возвращаемое значение имеет тип i32, дескриптор присоединения имеет тип JoinHandle<i32>:

use tokio::task;

let join_handle: task::JoinHandle<i32> = task::spawn(async {
    5 + 3
});

Если задача не возвращает значение, дескриптор присоединения имеет тип JoinHandle<()>:

use tokio::task;

let join_handle: task::JoinHandle<()> = task::spawn(async {
    println!("I return nothing.");
});

Обратите внимание, что handle.await не возвращает тип возвращаемого значения напрямую. Оно обёрнуто в Result, поскольку паники в запущенной задаче перехватываются Tokio. Чтобы извлечь возвращённое значение, оператор ? нужно использовать дважды:

use tokio::task;
use std::io;

let join_handle: task::JoinHandle<Result<i32, io::Error>> = tokio::spawn(async {
    Ok(5 + 3)
});

let result = join_handle.await??;
assert_eq!(result, 8);
Ok(())

Если задача завершается паникой, ошибкой будет JoinError, содержащая информацию о панике:

use tokio::task;
use std::io;
use std::panic;

#[tokio::main]
async fn main() -> io::Result<()> {
    let join_handle: task::JoinHandle<Result<i32, io::Error>> = tokio::spawn(async {
        panic!("boom");
    });

    let err = join_handle.await.unwrap_err();
    assert!(err.is_panic());
    Ok(())
}

Дочерняя задача отсоединяется и продолжает работу после завершения родительской:

use tokio::task;
use tokio::time;
use std::time::Duration;

let original_task = task::spawn(async {
    let _detached_task = task::spawn(async {
        // Here we sleep to make sure that the first task returns before.
        time::sleep(Duration::from_millis(10)).await;
        // This will be called, even though the JoinHandle is dropped.
        println!("♫ Still alive ♫");
    });
});

original_task.await.expect("The task being joined has panicked");
println!("Original task is joined.");

// We make sure that the new task has time to run, before the main
// task returns.

time::sleep(Duration::from_millis(1000)).await;