Attribute Macro main 

#[main]

将异步函数标记为由选定的 runtime 执行。该宏有助于设置 Runtime， 而无需用户直接使用 Runtime 或 Builder。

注意：这个宏设计着简单易用，靶向不需要复杂配置的应用程序。如果提供的功能不足 足使用 Builder，它提供更强大的接口。

注意：该宏可以用于任何函数，而不仅仅是 main 函数。在非 main 函数上使用它会使该函数表现得像同步函数一样， 因为每次调用时都会启动一个新的 runtime。如果该函数被频繁调用， 建议使用 runtime builder 来创建 runtime，以便在多次调用之间复用。

Non-worker async function

注意，被这个宏标记的 async 函数并不作为 worker 运行。 预期在这个函数内部派生其他任务，在其中 await 其他 future 的性能不像 worker 派生的任务那样快。

Runtime flavors

该宏可以通过 flavor 参数来配置，以选择不同的 runtime 配置。

多线程

要使用多线程 runtime，可以通过如下方式配置该宏

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

worker_threads 选项用于配置工作线程数， 默认为系统上的 CPU 数量。这是默认的 flavor。

注意：多线程运行时需要 rt-multi-thread 特性 标志。

当前线程

要使用称为 current_thread 运行时的单线程运行时， 可通过如下方式配置该宏

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

本地

要使用 本地运行时，可通过如下方式配置该宏

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

Function arguments

除 main 是特殊的外，任何函数都允许带参数。

Usage

设置运行时名称

#[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");
        })
}

配置未处理 panic 的行为

可用选项有 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;
        })
}

注意：该选项依赖于 Tokio 的不稳定 API。详见不稳定特性的相关文档， 了解如何启用 Tokio 的不稳定特性。