Marks async function to be executed by the selected runtime. This macro helps set up a Runtime without requiring the user to use Runtime or Builder directly.

Note: This macro is designed to be simplistic and targets applications that do not require a complex setup. If the provided functionality is not sufficient, you may be interested in using Builder, which provides a more powerful interface.

Note: This macro can be used on any function and not just the main function. Although the function is written with async fn, this macro expands it to a synchronous function that starts a runtime each time it is called. If the function is called often, it is preferable to create the runtime using the runtime builder so the runtime can be reused across calls. For details on the expansion, see Bridging with sync code.

Non-worker async function

Note that the async function marked with this macro does not run as a worker. The expectation is that other tasks are spawned by the function here. Awaiting on other futures from the function provided here will not perform as fast as those spawned as workers.

Runtime flavors

The macro can be configured with a flavor parameter to select different runtime configurations.

Multi-threaded

To use the multi-threaded runtime, the macro can be configured using

#[tokio::main(flavor = "multi_thread", worker_threads = 10)]
# async fn main() {}

The worker_threads option configures the number of worker threads, and defaults to the number of cpus on the system. This is the default flavor.

Note: The multi-threaded runtime requires the rt-multi-thread feature flag.

Current-thread

To use the single-threaded runtime known as the current_thread runtime, the macro can be configured using

#[tokio::main(flavor = "current_thread")]
# async fn main() {}

Local

To use the local runtime, the macro can be configured using

#[tokio::main(flavor = "local")]
# async fn main() {}

Function arguments

Arguments are allowed for any functions, aside from main which is special.

Usage

Set the name of the runtime

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

Equivalent code not using #[tokio::main]

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

Using the multi-threaded runtime

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

Equivalent code not using #[tokio::main]

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

Using the current-thread runtime

The basic scheduler is single-threaded.

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

Equivalent code not using #[tokio::main]

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

Using the local runtime

The local runtime is similar to the current-thread runtime but supports task::spawn_local.

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

Equivalent code not using #[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");
        })
}

Set number of worker threads

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

Equivalent code not using #[tokio::main]

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

Configure the runtime to start with time paused

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

Equivalent code not using #[tokio::main]

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

Note that start_paused requires the test-util feature to be enabled.

Rename package

use tokio as tokio1;

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

Equivalent code not using #[tokio::main]

use tokio as tokio1;

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

Configure unhandled panic behavior

Available options are shutdown_runtime and ignore. For more details, see Builder::unhandled_panic.

This option is only compatible with the current_thread runtime.

#[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;
}
# #[cfg(not(tokio_unstable))]
# fn main() { }

Equivalent code not using #[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;
        })
}
# #[cfg(not(tokio_unstable))]
# fn main() { }

Note: This option depends on Tokio's unstable API. See the documentation on unstable features for details on how to enable Tokio's unstable features.