Макрос join

macro_rules! join {
    ($(biased;)? $($future:expr),*) => { ... };
}

Доступен только при включённой возможности crate macros.

Ожидает завершения нескольких параллельных ветвей и возвращает результат, когда завершаются все ветви.

Макрос join! должен использоваться внутри асинхронных функций, замыканий и блоков.

Макрос join! принимает список асинхронных выражений и выполняет их параллельно в рамках одной задачи. Каждое асинхронное выражение возвращает future, а futures от каждого выражения мультиплексируются в текущей задаче.

При работе с асинхронными выражениями, возвращающими Result, join! будет ожидать завершения всех ветвей, даже если какая-либо из них завершается с Err. Используйте try_join!, чтобы завершить выполнение сразу при получении Err.

Примечания

Переданные futures хранятся непосредственно и не требуют выделения Vec.

Характеристики выполнения

Поскольку все асинхронные выражения выполняются в текущей задаче, они могут выполняться конкурентно, но не параллельно. Это означает, что все выражения выполняются в одном потоке, и если одна ветвь блокирует поток, остальные выражения не смогут продолжить выполнение. Если требуется параллелизм, запустите каждое асинхронное выражение с помощью tokio::spawn и передайте дескриптор объединения в join!.

Справедливость

По умолчанию future, генерируемый макросом join!, при каждом пробуждении меняет порядок, в котором опрашиваются содержащиеся в нём futures.

Это поведение можно переопределить, добавив biased; в начало вызова макроса. Подробности см. в примерах. В этом случае join будет опрашивать futures в порядке их появления сверху вниз.

Это может быть полезно, если futures взаимодействуют таким образом, что известный порядок опроса имеет значение.

Однако у этого режима есть важная особенность: вы сами должны следить за справедливостью порядка опроса futures. Например, если вы объединяете поток и future завершения работы, а поток содержит огромное количество сообщений, обработка которых занимает много времени при каждом опросе, следует поместить future завершения работы раньше в списке join!, чтобы он всегда опрашивался и не задерживался из-за того, что future потока долго не возвращает Poll::Pending.

Примеры

Простое объединение двух ветвей

async fn do_stuff_async() {
    // async work
}

async fn more_async_work() {
    // more here
}

let (first, second) = tokio::join!(
    do_stuff_async(),
    more_async_work());

// do something with the values

Использование режима biased; для управления порядком опроса.

async fn do_stuff_async() {
    // async work
}

async fn more_async_work() {
    // more here
}

let (first, second) = tokio::join!(
    biased;
    do_stuff_async(),
    more_async_work()
);

// do something with the values