Async Rust: futures, executors and Tokio

Lazy, concurrent, cancellable

1use std::time::Duration;2use tokio::time::{sleep, timeout};3 4async fn fetch(name: &str, ms: u64) -> String {5    sleep(Duration::from_millis(ms)).await; // yields to the executor while waiting6    format!("{name} after {ms} ms")7}8 9#[tokio::main]10async fn main() {11    let fut = fetch("lazy", 10); // nothing runs yet: a future is just a value12    println!("created the future");13    println!("{}", fut.await);  // now it runs14 15    let start = std::time::Instant::now();16    let (a, b) = tokio::join!(fetch("a", 100), fetch("b", 100)); // concurrently, one task17    println!("{a}, {b}, took about {} ms", start.elapsed().as_millis() / 100 * 100);18 19    match timeout(Duration::from_millis(20), fetch("slow", 500)).await {20        Ok(v) => println!("{v}"),21        Err(_) => println!("gave up after 20 ms; the inner future was dropped"),22    }23 24    let handle = tokio::spawn(fetch("spawned", 5)); // a separate task; must be 'static + Send25    println!("{}", handle.await.unwrap());26}

Run on the Rust Playground (Rust 1.99, Tokio 1.53) it printed created the future, lazy after 10 ms, a after 100 ms, b after 100 ms, took about 100 ms, the timeout message, and spawned after 5 ms.

What poll does

Future has one method, poll, which returns Poll::Ready(value) or Poll::Pending. A future that returns Pending has arranged for a waker to be called when it can make progress, for example when a socket becomes readable or a timer fires. The executor then polls it again. Because the generated state machine may hold references into itself, futures are polled through Pin<&mut Self>, which promises they won't be moved. You rarely meet Pin unless you write futures or combinators by hand.

Tasks and the runtime

• #[tokio::main] builds a runtime (multi-threaded by default, with one worker per CPU core) and blocks on your async fn main.
• tokio::spawn creates a task, the async equivalent of a green thread. Tasks are cheap; Tokio's tutorial puts one at a single allocation and 64 bytes. On the multi-threaded runtime a task may move between threads at each .await, so its future must be Send and 'static. Holding an Rc or a std::sync::MutexGuard across an .await makes it not Send, which is a common compile error.
• join! runs several futures concurrently inside one task. select! waits for the first of several and drops the rest.

Cancellation and blocking

Dropping a future cancels it: it stops at the last .await it reached and its locals are dropped. timeout and select! work this way. Write async code assuming any .await might be the last one, for example by not leaving shared state half-updated across an .await.

Scheduling is cooperative. A task that runs CPU-heavy code or calls a blocking function (std::thread::sleep, a synchronous file or database client) holds its worker thread and stalls every other task scheduled there. Use the async versions, or move the work to tokio::task::spawn_blocking.

Recent language changes made async easier to write: async fn in traits (Rust 1.75) and async closures (async || { ... }, Rust 1.85).