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.

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.

NOTE:

If you rename the Tokio crate in your dependencies this macro will not work. If you must rename the current version of Tokio because you’re also using an older version of Tokio, you must make the current version of Tokio available as tokio in the module where this macro is expanded.