Attribute Macro tokio::main

#[main]

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. Using it on a non-main function makes the function behave as if it was synchronous by starting a new 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.

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.

Multi-threaded runtime

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

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

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 runtime

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

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

Function arguments:

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

Usage

Using the multi-thread 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 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");
        })
}

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;
}

Equivalent code not using #[tokio::main]

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

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.