Async Rust

An async function does not (necessarily) start executing immediately

To start an asynchronous function, you must either .await it or launch a task using an executor (we'll get to that in a moment). Until this happens, all you have is a Future that has not started. Let's look at an example to make it clearer:

use async_std::task;
// ^ we need this for task spawning

async fn negate_async(n: i32) -> i32 {
    println!("Negating {}", n);
    task::sleep(std::time::Duration::from_secs(5)).await;
    println!("Finished sleeping for {}!", n);
    n * -1
}

async fn f() -> i32 {
    let neg = negate_async(1);
    // ... nothing happens yet
    let neg_task = task::spawn(negate_async(2));
    // ^ this task /is/ started
    task::sleep(std::time::Duration::from_secs(1)).await;
    // we sleep for effect.

    neg.await + neg_task.await
    // ^ this starts the first task `neg`
    // and waits for both tasks to finish
}

So in the above little code snippet, here's what's going on.

• The first line imports async_std::task. There's more on this below, but we need an external library to run futures as the standard library does not come with an executor.
• The async function negate_async takes as input a signed integer, sleeps for 5 seconds, and returns the negated version of that integer.
• The async function f is more interesting:
• The first line (let neg ...) creates a Future of the negate_async function and assigns it to the neg variable. Importantly, it does /not/ start executing yet.
• The next line of code (let neg_task ...) uses the task::spawn function to start executing the Future returned by negate_async. Like with neg, the Future returned by negate_async is assigned to the neg_task variable.
• Next: we sleep for a second. This is so that it will be obvious from the output when a task starts running.
• Finally, we await both futures, add them together, and return them. By awaiting neg, we start executing the Future and run it to completion. Since neg_task has already been started, we just wait for it to finish.

So what's the result of this, then?

Negating 2
# <- there's a 1 second pause here
Negating 1
Finished sleeping for 2!
Finished sleeping for 1!

As we can see, the second future, neg_task, started executing as soon as it was called---thanks to task::spawn---while neg did not start executing until it was awaited.

You need an external library to use async/.await

As was briefly alluded to above, you need to reach for an external library to do asynchronous programming in Rust. This took me a while to understand, as I'm used to it being part of the language experience. In Rust, however, *you need a dedicated executor/*[fn:1]. The executor is what takes care of /executing the futures, polling them and returning the results when they're done. The standard library does not come with an executor, so we need to reach out to an external crate for this. There are a few ones to choose from, but the two most prominent ones are ~async-std~ (which we're using here) and ~tokio~.

Step 1: creating the application

Let's create a new application! Simply run this command in your preferred directory:

cargo new async-basics

Step 2: Dependencies

We're going to be using ~async-std~ for spawning tasks, and ~surf~ to fetch data from the API. Let's add them to the Cargo.toml file. Your whole file should look something like this:

[package]
name = "async-basics"
version = "0.1.0"
authors = ["Your Name <your.email@provider.tld>"]
edition = "2018"

[dependencies]
async-std = "1"
surf = "1"

Nice! This is going swimmingly!

Step 3: Fetch data

Okay, final step. Let's modify the main.rs file. We'll make it as simple as possible. Here's what we want to use:

use async_std::task;
use surf;

// fetch data from a url and return the results as a string.
// if an error occurs, return the error.
async fn fetch(url: &str) -> Result<String, surf::Exception> {
    surf::get(url).recv_string().await
}

// execute the fetch function and print the results
async fn execute() {
    match fetch("https://pokeapi.co/api/v2/move/surf").await {
        Ok(s) => println!("Fetched results: {:#?}", s),
        Err(e) => println!("Got an error: {:?}", e),
    };
}

fn main() {
    task::block_on(execute());
    // ^ start the future and wait for it to finish
}

That's all the code you need. In fact, it's more than what you need, as some parts have been broken up for legibility. Let's walk through it!

~use~ statements

Nothing exciting here. Just importing the crates we declared in the Cargo.toml file: surf and async_std.

~fetch~

This is simply a thin wrapper around the surf::get function which returns either the payload as a String or an Exception if something went wrong.

~execute~

This function calls fetch with the endpoint for the move Surf, waits for the result to return, and then matches on the result. If everything went well: print the output. Else: print the error.

~main~

main simply kicks off execute and waits for it to finish. task::block_on is a synchronous counterpart to task::spawn that starts an asynchronous operation, but blocks until it has finished. Because the main function can't itself be async (at least not at the time of writing), we can't use .await in it, but we can block on asynchronous operations.

Step 4: Extend it!

Hey, you made it this far; congrats! That's all I really have in store for you for this one, but if you want to play around a bit more, how about adding ~serde~ and try using surf's recv_json<T> instead? If you'd rather keep looking at async/.await, how about performing multiple requests simultaneously? Or how about making a PokéAPI CLI? (Ooh, that sounds like fun! Hit me up if you're doing this; I want in!)