Макрос-атрибут main

Помечает асинхронную функцию для выполнения выбранной средой выполнения. Этот макрос помогает настроить Runtime, не требуя от пользователя напрямую использовать Runtime или Builder.

Примечание: этот макрос предназначен для упрощённого использования и подходит для приложений, которым не требуется сложная настройка. Если предоставляемой функциональности недостаточно, можно использовать Builder, который предоставляет более мощный интерфейс.

Примечание: этот макрос можно использовать с любой функцией, а не только с функцией main. Хотя функция написана с использованием async fn, макрос преобразует её в синхронную функцию, которая запускает среду выполнения при каждом вызове. Если функция вызывается часто, предпочтительно создать среду выполнения с помощью построителя, чтобы повторно использовать её при последующих вызовах. Подробнее о преобразовании см. в разделе Взаимодействие с синхронным кодом.

Асинхронная функция, не являющаяся рабочим потоком

Обратите внимание, что асинхронная функция, помеченная этим макросом, не выполняется как рабочий поток. Предполагается, что эта функция запускает другие задачи. Ожидание завершения других future в этой функции будет выполняться медленнее, чем ожидание завершения задач, запущенных как рабочие потоки.

Варианты среды выполнения

Макрос можно настроить с помощью параметра flavor для выбора различных конфигураций среды выполнения.

Многопоточная среда выполнения

Чтобы использовать многопоточную среду выполнения, макрос можно настроить следующим образом:

#[tokio::main(flavor = "multi_thread", worker_threads = 10)]

Параметр worker_threads задаёт количество рабочих потоков; по умолчанию используется количество процессоров в системе. Это вариант среды выполнения по умолчанию.

Примечание: для многопоточной среды выполнения требуется флаг функции rt-multi-thread.

Среда выполнения в текущем потоке

Чтобы использовать однопоточную среду выполнения, известную как среда выполнения current_thread, макрос можно настроить следующим образом:

#[tokio::main(flavor = "current_thread")]

Локальная среда выполнения

Чтобы использовать локальную среду выполнения, макрос можно настроить следующим образом:

#[tokio::main(flavor = "local")]

Аргументы функции

Аргументы разрешены для любых функций, кроме main, которая является особым случаем.

Использование

Задание имени среды выполнения

#[tokio::main(name = "my-runtime")]
async fn main() {
    println!("Hello world");
}

Эквивалентный код без использования #[tokio::main]

fn main() {
    tokio::runtime::Builder::new_multi_thread()
        .enable_all()
        .name("my-runtime")
        .build()
        .unwrap()
        .block_on(async {
            println!("Hello world");
        })
}

Использование многопоточной среды выполнения

#[tokio::main]
async fn main() {
    println!("Hello world");
}

Эквивалентный код без использования #[tokio::main]

fn main() {
    tokio::runtime::Builder::new_multi_thread()
        .enable_all()
        .build()
        .unwrap()
        .block_on(async {
            println!("Hello world");
        })
}

Использование среды выполнения в текущем потоке

Базовый планировщик является однопоточным.

#[tokio::main(flavor = "current_thread")]
async fn main() {
    println!("Hello world");
}

Эквивалентный код без использования #[tokio::main]

fn main() {
    tokio::runtime::Builder::new_current_thread()
        .enable_all()
        .build()
        .unwrap()
        .block_on(async {
            println!("Hello world");
        })
}

Использование локальной среды выполнения

Локальная среда выполнения похожа на среду выполнения в текущем потоке, но поддерживает task::spawn_local.

#[tokio::main(flavor = "local")]
async fn main() {
    println!("Hello world");
}

Эквивалентный код без использования #[tokio::main]

fn main() {
    tokio::runtime::Builder::new_current_thread()
        .enable_all()
        .build_local(tokio::runtime::LocalOptions::default())
        .unwrap()
        .block_on(async {
            println!("Hello world");
        })
}

Задание количества рабочих потоков

#[tokio::main(worker_threads = 2)]
async fn main() {
    println!("Hello world");
}

Эквивалентный код без использования #[tokio::main]

fn main() {
    tokio::runtime::Builder::new_multi_thread()
        .worker_threads(2)
        .enable_all()
        .build()
        .unwrap()
        .block_on(async {
            println!("Hello world");
        })
}

Настройка запуска среды выполнения с приостановленным временем

#[tokio::main(flavor = "current_thread", start_paused = true)]
async fn main() {
    println!("Hello world");
}

Эквивалентный код без использования #[tokio::main]

fn main() {
    tokio::runtime::Builder::new_current_thread()
        .enable_all()
        .start_paused(true)
        .build()
        .unwrap()
        .block_on(async {
            println!("Hello world");
        })
}

Обратите внимание, что для start_paused требуется включить функцию test-util.

Переименование пакета

use tokio as tokio1;

#[tokio1::main(crate = "tokio1")]
async fn main() {
    println!("Hello world");
}

Эквивалентный код без использования #[tokio::main]

use tokio as tokio1;

fn main() {
    tokio1::runtime::Builder::new_multi_thread()
        .enable_all()
        .build()
        .unwrap()
        .block_on(async {
            println!("Hello world");
        })
}

Настройка поведения при необработанной панике

Доступны варианты shutdown_runtime и ignore. Подробнее см. в разделе Builder::unhandled_panic.

Этот параметр совместим только со средой выполнения current_thread.

#[cfg(tokio_unstable)]
#[tokio::main(flavor = "current_thread", unhandled_panic = "shutdown_runtime")]
async fn main() {
    let _ = tokio::spawn(async {
        panic!("This panic will shutdown the runtime.");
    }).await;
}

Эквивалентный код без использования #[tokio::main]

#[cfg(tokio_unstable)]
fn main() {
    tokio::runtime::Builder::new_current_thread()
        .enable_all()
        .unhandled_panic(tokio::runtime::UnhandledPanic::ShutdownRuntime)
        .build()
        .unwrap()
        .block_on(async {
            let _ = tokio::spawn(async {
                panic!("This panic will shutdown the runtime.");
            }).await;
        })
}

Примечание: этот параметр зависит от нестабильного API Tokio. Подробнее о том, как включить нестабильные функции Tokio, см. в документации по нестабильным функциям.