How do I synchronously return a value calculated in an asynchronous Future in stable Rust?

Standard library futures

Let's use this as our minimal, reproducible example:

async fn example() -> i32 {
    42
}

Call executor::block_on:

use futures::executor; // 0.3.1

fn main() {
    let v = executor::block_on(example());
    println!("{}", v);
}

Tokio

Use the tokio::main attribute on any function (not just main!) to convert it from an asynchronous function to a synchronous one:

use tokio; // 0.3.5

#[tokio::main]
async fn main() {
    let v = example().await;
    println!("{}", v);
}

tokio::main is a macro that transforms this

#[tokio::main]
async fn main() {}

Into this:

fn main() {
    tokio::runtime::Builder::new_multi_thread()
        .enable_all()
        .build()
        .unwrap()
        .block_on(async { {} })
}

This uses Runtime::block_on under the hood, so you can also write this as:

use tokio::runtime::Runtime; // 0.3.5

fn main() {
    let v = Runtime::new().unwrap().block_on(example());
    println!("{}", v);
}

For tests, you can use tokio::test.

async-std

Use the async_std::main attribute on the main function to convert it from an asynchronous function to a synchronous one:

use async_std; // 1.6.5, features = ["attributes"]

#[async_std::main]
async fn main() {
    let v = example().await;
    println!("{}", v);
}

For tests, you can use async_std::test.

Futures 0.1

Let's use this as our minimal, reproducible example:

use futures::{future, Future}; // 0.1.27

fn example() -> impl Future<Item = i32, Error = ()> {
    future::ok(42)
}

For simple cases, you only need to call wait:

fn main() {
    let s = example().wait();
    println!("{:?}", s);
}

However, this comes with a pretty severe warning:

This method is not appropriate to call on event loops or similar I/O situations because it will prevent the event loop from making progress (this blocks the thread). This method should only be called when it's guaranteed that the blocking work associated with this future will be completed by another thread.

Tokio

If you are using Tokio 0.1, you should use Tokio's Runtime::block_on:

use tokio; // 0.1.21

fn main() {
    let mut runtime = tokio::runtime::Runtime::new().expect("Unable to create a runtime");
    let s = runtime.block_on(example());
    println!("{:?}", s);
}

If you peek in the implementation of block_on, it actually sends the future's result down a channel and then calls wait on that channel! This is fine because Tokio guarantees to run the future to completion.

See also:

  • How can I efficiently extract the first element of a futures::Stream in a blocking manner?

Tags:

Future

Rust

Hyper