Attribute Macro main 

#[main]

将 async 函数标记为由所选运行时执行。该宏帮助设置一个 Runtime， 无需用户直接使用 Runtime 或 Builder。

注意：该宏被设计为简单易用，面向不需要复杂配置的应用。如果所提供的功能不够用， 您可以考虑使用 Builder，它提供更强大的接口。

注意：该宏可用于任何函数，不仅仅是 main 函数。在非 main 函数上使用它 会让该函数表现得像同步函数一样（每次调用时启动一个新运行时）。如果该函数被频繁调用， 建议使用 runtime builder 创建运行时，以便跨调用复用。

非 worker 异步函数

注意：由该宏标记的 async 函数不会作为 worker 运行。预期行为是此函数内部派生其他任务。 在此处提供的函数中 await 其他 future 的性能不会像 worker 派生的任务那样快。

运行时类型

该宏可通过 flavor 参数配置不同的运行时配置。

多线程

要使用多线程运行时，可通过以下方式配置该宏：

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

worker_threads 选项用于配置 worker 线程数量， 默认为系统上的 CPU 数量。这是默认类型。

注意：多线程运行时需要 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");
        })
}

设置 worker 线程数

#[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 不稳定特性的详情，请参阕不稳定特性相关文档。