Skip to content
Tutorials Center
My learning

Topics

Lesson 82 of 132 ยท Async Rust

Async/await Basics

Learn how Rust async/await works: futures are lazy state machines, async fn and async blocks, .await, why std has no runtime, a tiny block_on, Pin at a glance, and async vs threads.

Threads are a fine way to do several things at once, but they have a price: every thread reserves stack memory and the operating system has to schedule it. A web server with 50,000 open connections, most of them just waiting for data, cannot reasonably use 50,000 threads. Asynchronous programming solves this by letting one thread juggle many tasks: when a task has to wait, it steps aside, and the thread runs another task until the first one can continue.

Rust supports this with the keywords async and .await. They look simple, but Rust's design is unusual, and understanding it saves hours of confusion. Three facts explain nearly everything:

  1. An async fn does not run when you call it. It returns a future, a value describing work that has not happened yet.
  2. A future does nothing until something polls it. Futures are lazy.
  3. The standard library defines futures but ships no runtime to run them. You bring an executor (a crate such as Tokio, or, in this lesson, a few lines of your own).

In this lesson you will meet futures, async fn, async blocks and .await, write a tiny executor, look at Pin and Context just enough to read signatures, and compare async with threads. The next lesson, Futures and Executors by Hand, builds the machinery piece by piece.

Everything here runs with the standard library only. Real programs usually use the Tokio ecosystem, covered read-only in Tokio and the Async Ecosystem. Our editor cannot download crates, so we write the small runtime ourselves.

async fn returns a future

Adding async in front of fn changes the return type. async fn add(a: i32, b: i32) -> i32 behaves like a normal function that returns impl Future<Output = i32>. If you forget that and treat the result as a plain number, the compiler tells you:

Rust Calling an async fn does not give the value (fails on purpose)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with io::stdin().read_line()), it gets the next line from this box.

TEXT
error[E0308]: mismatched types
 --> main.rs:6:22
  |
6 |     let total: i32 = add(1, 2);
  |                ---   ^^^^^^^^^ expected `i32`, found future

To get the i32 you must await the future. But .await is only allowed inside another async context:

Rust await outside async (fails on purpose)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with io::stdin().read_line()), it gets the next line from this box.

TEXT
error[E0728]: `await` is only allowed inside `async` functions and blocks

So who awaits the first future? An executor: ordinary, non-async code that drives futures to completion. main is a normal function, which is why async programs use a runtime attribute such as #[tokio::main] to hide this step. Let us see what is underneath.

Futures are lazy, and an executor polls them

The Future trait is small:

Rust
pub trait Future {
    type Output;
    fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output>;
}

pub enum Poll<T> {
    Ready(T),
    Pending,
}

Calling poll asks the future to make progress. It answers Poll::Ready(value) if it finished, or Poll::Pending if it cannot continue yet (and it has arranged to be woken when it can; that is what the Context carries). An executor's job is to keep polling futures until they are ready.

Here is the smallest useful executor, block_on. It polls one future in a loop. This simple version spins; real ones sleep until a waker says progress is possible, which we build in the next lesson.

Rust A tiny block_on and a lazy future

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with io::stdin().read_line()), it gets the next line from this box.

Look at the order of the output: "future created" appears before "add is running". Calling add(1, 2) only built the future. The body ran when block_on polled it. This laziness is different from JavaScript promises, which start working immediately, and it is the source of the classic bug "I called the async function but nothing happened". Waker::noop() has been stable since Rust 1.85; before that people wrote the same thing with a hand-made RawWaker.

If a future finishes on its first poll, as add does, there is no waiting at all. Async only becomes interesting when a future returns Pending.

.await: wait without blocking the thread

Inside an async fn, other_future.await means: "poll other_future; if it is Pending, make my future return Pending too, and come back here the next time I am polled." The thread is not blocked. It returns to the executor, which can poll other tasks.

To see this, we need a future that is Pending at least once. This one yields control back to the executor one time, like tokio::task::yield_now:

Rust A future that is Pending once

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with io::stdin().read_line()), it gets the next line from this box.

The future needs three polls. The first runs up to the first .await and returns Pending; the second resumes right after it and runs to the next .await; the third finishes. This is the key insight: an async fn is compiled into a state machine that remembers where it paused and keeps its local variables between polls. The compiler writes that machine for you; the code you write looks like straight-line code.

async blocks and async closures

async fn is not the only way to make a future. An async block creates one inline, and an async closure (stable since Rust 1.85) is a closure that returns a future.

Rust Async blocks and async closures

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with io::stdin().read_line()), it gets the next line from this box.

The first block prints block = 60: a is 20, b is 40. The async move form is the one you need whenever a future must be sent to another task or stored somewhere, exactly like move closures for threads.

Running things one after another, or together

Awaiting two futures one after the other runs them sequentially, even though it looks parallel. To run them concurrently you need a combinator, like join! in the futures crates or Tokio. We can write a small one. Here is join for two futures: poll both until both are done.

Rust Sequential awaits versus a hand-written join

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with io::stdin().read_line()), it gets the next line from this box.

In the sequential version, A finishes both of its steps before B starts. In the joined version the steps interleave: A1, B1, A2, B2. All on a single thread, with no locks (RefCell is fine because there is only one thread). That is concurrency without parallelism, and it is what async gives you. We will build a more complete version of this idea in the next lessons.

Why there is no runtime in std

Other languages build one scheduler into the language. Rust does not, for good reasons:

  • Different programs want different executors: a single-threaded one for an embedded device, a work-stealing multi-threaded one for a server, one integrated with a GUI event loop.
  • A built-in runtime would cost every program that does not use async.
  • Keeping Future in std lets libraries be written against the trait while applications pick the runtime.

The price is a more complicated start. In practice you add one dependency (almost always Tokio), write #[tokio::main], and the details disappear. But knowing what sits underneath makes errors much less mysterious.

Pin and Context at a glance

You will see two odd types in the poll signature.

Context carries the waker. When a future returns Pending, it must make sure that something will call cx.waker().wake() later (a timer firing, a socket becoming readable). The executor then knows to poll that task again. A future that returns Pending without arranging a wake-up will hang forever, which is the most common bug when you write futures by hand.

Pin<&mut Self> exists because of the state machine. An async fn may keep a reference to one of its own local variables across an .await (a self-referential struct). If such a future were moved in memory, that reference would dangle. Pin is a promise that the value will not be moved, so self-references stay valid. For day-to-day code you only need these rules of thumb:

  • pin!(future) (a standard macro) pins a future on the stack, as block_on did above.
  • Box::pin(future) pins it on the heap and gives Pin<Box<dyn Future<Output = T>>>, the type to use when you need to store different futures in one collection or write a recursive async fn.
  • You rarely implement poll yourself; you write async fn and let the compiler do it.
Rust Boxing futures: a Vec of different futures

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with io::stdin().read_line()), it gets the next line from this box.

Async and Send

When an executor moves a task between threads, the future must be Send. A future is Send only if everything it holds across an .await is Send. That is why the Send and Sync rules show up in async code:

Rust Holding an Rc across await (fails on purpose)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with io::stdin().read_line()), it gets the next line from this box.

TEXT
error: future cannot be sent between threads safely
  = help: within `impl Future<Output = ()>`, the trait `Send` is not implemented for `Rc<i32>`
note: future is not `Send` as this value is used across an await

The note points at the .await and at local. Fixes: use Arc instead of Rc, or end the variable's scope before the .await (put it in a block, or drop it). A MutexGuard held across an .await triggers the same error, and also a worse problem: it blocks other tasks on the same thread while waiting.

Async versus threads

Threads Async tasks
Unit of work OS thread Future (state machine)
Memory per unit Stack, often 2 MB reserved Often a few hundred bytes
Switching By the OS, anywhere Only at .await points
Blocking a call Fine, only that thread waits Disastrous if it blocks the executor thread
Good for CPU-heavy work, simple programs Many mostly-waiting tasks: network servers, clients, timers
Needs a runtime No Yes

The last row of caution deserves emphasis: never block inside an async task (thread::sleep, heavy computation, a blocking file read). The executor thread cannot poll anything else meanwhile. Async runtimes provide spawn_blocking-style escape hatches for that. For CPU-bound work, the parallel patterns with threads are the better tool; the two approaches combine well, async for I/O and threads for computation.

And since .await points are the only places where tasks can switch, async code on a single thread can often avoid locks entirely, as in the join example above.

What the compiler builds

For the curious, here is roughly what the compiler generates for a function with two .await points: an enum with one variant per pause point, each holding exactly the local variables that are alive across it.

Rust
// Conceptual, not real syntax:
enum StepsFuture {
    Start,
    AfterFirstAwait { /* locals alive here */ },
    AfterSecondAwait { /* locals alive here */ },
    Done,
}

poll is then a big match on that enum that runs until the next .await returns Pending. This is why async Rust is called a zero-cost abstraction: no heap allocation is needed for the state machine itself, and the size of a future is the size of the largest set of variables it must keep. It is also why futures can be large when you hold big arrays across an .await, and why recursion in an async fn requires boxing: the type would otherwise contain itself.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What happens when you call an async fn without awaiting or polling the result?

    Futures in Rust are lazy. The body only runs when an executor polls the future, usually through .await in a running task.
  2. 2. What does Poll::Pending tell the executor?

    Pending means not ready. The future must have registered the waker from the Context; otherwise nobody will poll it again.
  3. 3. Why does std not include an async runtime?

    Rust defines Future, Poll, Context and Waker in std and leaves the scheduling policy to crates, so each program picks the executor it needs.
  4. 4. Two futures are awaited one after the other: a.await; b.await;. How do they run?

    Awaiting one after another is sequential. To run them concurrently use a combinator such as join!, or spawn them as separate tasks.
  5. 5. What is the main danger of calling std::thread::sleep inside an async task?

    Async tasks only yield at .await. A blocking call holds the whole thread, starving every other task scheduled on it.

Summary

  • An async fn or async block returns a future: a lazy state machine that does nothing until polled.
  • Future::poll returns Poll::Ready(value) or Poll::Pending; a pending future must arrange a wake-up through the Waker in the Context.
  • .await is allowed only inside async contexts, and it suspends the current future instead of blocking the thread.
  • std has no runtime; an executor such as Tokio (or your own block_on) polls futures to completion.
  • Pin keeps self-referential state machines from moving; use pin! on the stack and Box::pin for boxed dyn Future.
  • Futures must be Send to move between threads, which fails if a non-Send value is held across an .await.
  • Async excels at many mostly-waiting tasks; use threads for CPU-bound work, and never block inside a task.

Next: Futures and Executors by Hand