How Async/Await Works Under the Hood

23 min read

In Section 11 you learned to use async/await. This page opens the hood: an async fn is not magic and there is no hidden event loop in the language. It compiles down to an ordinary value — a state machine — that implements one small trait called Future, and a separate library called a runtime repeatedly calls one method on it until it produces a result.

Quick Overview

A Rust Future is a plain data structure with a single core method, poll, that the runtime calls to ask “are you done yet?”. The compiler rewrites every async fn and async block into an enum-shaped state machine where each .await point becomes a state; polling resumes from the last suspended state. When a future cannot make progress (waiting on I/O, a timer, a lock), it returns Poll::Pending and registers a Waker so that whatever it is waiting on can later tell the runtime “poll this future again.” Understanding this loop — poll, suspend, wake, re-poll — explains nearly every async behavior and performance characteristic in Rust.

Note: Every runnable Rust snippet on this page was compiled and executed with cargo/rustc 1.96.0 (current stable; 2024 edition). Examples that need a runtime use Tokio (tokio = { version = "1.52", features = ["full"] }), one uses the futures crate (futures = "0.3"), and the real-world example uses pin-project-lite = "0.2". Add them with cargo add tokio --features full, cargo add futures, and cargo add pin-project-lite.

TypeScript/JavaScript Example

In JavaScript you never see the machinery: the engine (V8) and the event loop (libuv in Node) are built in. When you write an async function, the engine internally turns it into a resumable coroutine. A close, hand-visible analogy is a generator: each yield is a suspension point, and calling .next() resumes execution from where it left off. That is almost exactly what the Rust compiler does for you, except in Rust the suspension points are .await and you (well, the runtime) drive the resumption.

1
// JavaScript (Node v22) — a generator makes the hidden "state machine" visible.
2
// An async function is conceptually this, with the event loop calling .next() for you.
3
function makeStateMachine() {
4
  function* gen() {
5
    console.log("state A");
6
    yield; // suspension point #1
7
    console.log("state B");
8
    yield; // suspension point #2
9
    console.log("state C (done)");
10
  }
11
  const it = gen();
12
  return () => it.next(); // each call advances one "poll"
13
}
14

15
const step = makeStateMachine();
16
console.log("poll 1:", step().done);
17
console.log("poll 2:", step().done);
18
console.log("poll 3:", step().done);

Running this with Node v22 prints:

1
state A
2
poll 1: false
3
state B
4
poll 2: false
5
state C (done)
6
poll 3: true

The function runs in pieces: .next() advances it to the next yield, returns { done: false }, and the local variables survive across calls. In JavaScript the event loop is the thing calling .next() (and done is hidden inside the Promise machinery). Rust exposes this same pattern as the Future trait, and the thing calling the equivalent of .next() is the async runtime.

Note: A JavaScript generator is the closest built-in analogy, but it is not identical: generators are not Futures, JS Promises are eager, and the engine resumes them automatically. The Rust equivalents are lazy and require an explicit runtime — see Promises vs Futures.

Rust Equivalent

Here is the trait at the center of everything, exactly as it appears in std:

1
// std::future::Future (shown for reference — you do not write this).
2
pub trait Future {
3
    type Output;
4
    fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output>;
5
}
6

7
// std::task::Poll — the result of one poll.
8
pub enum Poll<T> {
9
    Ready(T),  // the future finished; here is the value
10
    Pending,   // not done yet; I've registered to be woken later
11
}

You rarely implement Future by hand — you write an async fn and the compiler generates the state machine. But writing one by hand makes the generated code concrete. Below is the state machine the compiler would produce for this async fn:

1
// The async fn we are de-sugaring by hand:
2
//   async fn two_steps() -> u32 {
3
//       let a = step_one().await; // yields once
4
//       let b = step_two().await; // yields once
5
//       a + b
6
//   }
7
use std::future::Future;
8
use std::pin::Pin;
9
use std::task::{Context, Poll};
10

11
// A leaf future: returns Pending the first time it is polled, Ready the second.
12
// This stands in for "real" leaf futures like a socket read or a timer.
13
struct YieldOnce {
14
    polled: bool,
15
    value: u32,
16
}
17

18
impl Future for YieldOnce {
19
    type Output = u32;
20
    fn poll(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<u32> {
21
        if self.polled {
22
            Poll::Ready(self.value)
23
        } else {
24
            self.polled = true;
25
            cx.waker().wake_by_ref(); // "I made progress, poll me again soon"
26
            Poll::Pending
27
        }
28
    }
29
}
30

31
// The compiler turns the async fn into an enum of states. Here it is by hand.
32
// Each variant captures exactly the locals that must survive across an `.await`.
33
enum TwoSteps {
34
    Start,
35
    AwaitingFirst { first: YieldOnce },
36
    AwaitingSecond { a: u32, second: YieldOnce },
37
    Done,
38
}
39

40
impl Future for TwoSteps {
41
    type Output = u32;
42
    fn poll(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<u32> {
43
        loop {
44
            match &mut *self {
45
                TwoSteps::Start => {
46
                    // Begin: move into the first await's state.
47
                    *self = TwoSteps::AwaitingFirst {
48
                        first: YieldOnce { polled: false, value: 10 },
49
                    };
50
                }
51
                TwoSteps::AwaitingFirst { first } => {
52
                    // `YieldOnce` is Unpin, so Pin::new is sound here.
53
                    match Pin::new(first).poll(cx) {
54
                        Poll::Pending => return Poll::Pending, // suspend the whole fn
55
                        Poll::Ready(a) => {
56
                            *self = TwoSteps::AwaitingSecond {
57
                                a,
58
                                second: YieldOnce { polled: false, value: 32 },
59
                            };
60
                        }
61
                    }
62
                }
63
                TwoSteps::AwaitingSecond { a, second } => {
64
                    let a = *a;
65
                    match Pin::new(second).poll(cx) {
66
                        Poll::Pending => return Poll::Pending,
67
                        Poll::Ready(b) => {
68
                            *self = TwoSteps::Done;
69
                            return Poll::Ready(a + b);
70
                        }
71
                    }
72
                }
73
                TwoSteps::Done => panic!("polled after completion"),
74
            }
75
        }
76
    }
77
}
78

79
#[tokio::main]
80
async fn main() {
81
    let result = TwoSteps::Start.await;
82
    println!("hand-written state machine produced: {result}");
83
}

Real output:

1
hand-written state machine produced: 42

That enum is what async fn two_steps() becomes — minus the readable names. Each .await is a place where the function can return Poll::Pending and later resume. The match/loop is the resume logic. Notice there is no thread blocking and no callback: just a value that remembers where it left off.

Detailed Explanation

The `Future` trait has exactly one job

poll answers one question: “given a chance to run, can you produce your Output?” It returns Poll::Ready(value) if yes, or Poll::Pending if it had to stop and wait. That is the whole protocol. Everything else — runtimes, executors, tokio::spawn, join! — is built on top of this one method.

This is the deepest contrast with JavaScript. A Promise is push-based: it holds callbacks and the engine pushes the result into them when ready. A Future is pull-based: it holds no callbacks; something must pull on it by calling poll. Nothing happens until someone polls — which is why Rust futures are lazy (the opposite of eager JS Promises).

`Output` is the resolved type

type Output is the associated type the future eventually produces. For async fn foo() -> User, the generated future has Output = User. This is the analog of the T in Promise<T>.

`Context` carries the `Waker`

The cx: &mut Context<'_> parameter currently carries exactly one thing: a reference to a Waker, retrieved with cx.waker(). When a future returns Poll::Pending, it is responsible for arranging that the waker gets called once progress is possible. In the YieldOnce example we call cx.waker().wake_by_ref() immediately (so it is re-polled right away); a real socket future would instead hand its waker to the OS event subsystem (epoll/kqueue/IOCP) and return without waking, so the future sleeps until the kernel reports readiness.

The `.await` de-sugar is a poll loop

When you write let a = some_future.await;, the compiler does not block. It generates, in effect:

1
// What `let value = inner().await;` becomes inside the generated state machine
2
// (driven here manually to show the loop; normally the runtime drives it).
3
use std::future::Future;
4
use std::pin::pin;
5
use std::task::{Context, Poll, Waker};
6

7
async fn inner() -> u32 { 99 }
8

9
fn main() {
10
    let waker = Waker::noop();
11
    let mut cx = Context::from_waker(&waker);
12
    let mut fut = pin!(inner());
13
    let value = loop {
14
        match fut.as_mut().poll(&mut cx) {
15
            Poll::Ready(v) => break v,
16
            Poll::Pending => {
17
                // In a real state machine, THIS is the point where the
18
                // enclosing function returns Poll::Pending to ITS caller,
19
                // saving the current state so it can resume here later.
20
                continue;
21
            }
22
        }
23
    };
24
    println!("desugared await produced: {value}");
25
}

Real output:

1
desugared await produced: 99

Waker::noop() is a real no-op waker in std (stabilized in Rust 1.85) handy for driving a future manually in tests. In production you never write this loop — the runtime does, and instead of continue it returns Pending all the way up, then re-enters when the waker fires.

Who calls `poll`? The runtime.

Rust ships no executor in the standard library, so a Future left alone does nothing. A runtime (Tokio, async-std, smol, or futures::executor) owns a queue of tasks and a poll loop. Here is a complete, minimal single-threaded executor — the same shape Tokio uses, just tiny — so you can see the moving parts: a run queue, a Waker that re-enqueues a task, and the poll loop.

1
use std::future::Future;
2
use std::pin::Pin;
3
use std::task::{Context, Poll, Waker};
4
use std::sync::{Arc, Mutex};
5
use std::sync::mpsc::{sync_channel, Receiver, SyncSender};
6
use std::thread;
7
use std::time::Duration;
8

9
// A real leaf future: completes after a timer fires on a background thread.
10
struct TimerFuture {
11
    shared: Arc<Mutex<SharedState>>,
12
}
13

14
struct SharedState {
15
    completed: bool,
16
    waker: Option<Waker>, // who to wake when the timer fires
17
}
18

19
impl Future for TimerFuture {
20
    type Output = &'static str;
21
    fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output> {
22
        let mut state = self.shared.lock().unwrap();
23
        if state.completed {
24
            Poll::Ready("timer done")
25
        } else {
26
            // Store the LATEST waker so the timer thread can wake us.
27
            state.waker = Some(cx.waker().clone());
28
            Poll::Pending
29
        }
30
    }
31
}
32

33
impl TimerFuture {
34
    fn new(dur: Duration) -> Self {
35
        let shared = Arc::new(Mutex::new(SharedState { completed: false, waker: None }));
36
        let thread_shared = Arc::clone(&shared);
37
        thread::spawn(move || {
38
            thread::sleep(dur);
39
            let mut state = thread_shared.lock().unwrap();
40
            state.completed = true;
41
            if let Some(waker) = state.waker.take() {
42
                waker.wake(); // tell the executor: poll this task again
43
            }
44
        });
45
        TimerFuture { shared }
46
    }
47
}
48

49
// A task is a top-level future plus a handle to re-enqueue itself.
50
struct Task {
51
    future: Mutex<Option<Pin<Box<dyn Future<Output = ()> + Send>>>>,
52
    task_sender: SyncSender<Arc<Task>>,
53
}
54

55
// Implementing std::task::Wake gives us a Waker for free via Waker::from(Arc<Task>).
56
impl std::task::Wake for Task {
57
    fn wake(self: Arc<Self>) {
58
        let _ = self.task_sender.send(self.clone()); // reschedule
59
    }
60
}
61

62
struct MiniExecutor {
63
    ready_queue: Receiver<Arc<Task>>,
64
}
65

66
#[derive(Clone)]
67
struct Spawner {
68
    task_sender: SyncSender<Arc<Task>>,
69
}
70

71
impl Spawner {
72
    fn spawn(&self, fut: impl Future<Output = ()> + Send + 'static) {
73
        let task = Arc::new(Task {
74
            future: Mutex::new(Some(Box::pin(fut))),
75
            task_sender: self.task_sender.clone(),
76
        });
77
        self.task_sender.send(task).unwrap();
78
    }
79
}
80

81
impl MiniExecutor {
82
    fn run(&self) {
83
        // The executor's heartbeat: take a ready task, poll it once.
84
        while let Ok(task) = self.ready_queue.recv() {
85
            let mut slot = task.future.lock().unwrap();
86
            if let Some(mut fut) = slot.take() {
87
                let waker = Waker::from(task.clone());
88
                let mut cx = Context::from_waker(&waker);
89
                match fut.as_mut().poll(&mut cx) {
90
                    Poll::Pending => *slot = Some(fut), // keep it; it'll be re-sent on wake
91
                    Poll::Ready(()) => {}               // done; drop the future
92
                }
93
            }
94
        }
95
    }
96
}
97

98
fn new_executor_and_spawner() -> (MiniExecutor, Spawner) {
99
    let (task_sender, ready_queue) = sync_channel(1024);
100
    (MiniExecutor { ready_queue }, Spawner { task_sender })
101
}
102

103
fn main() {
104
    let (executor, spawner) = new_executor_and_spawner();
105
    spawner.spawn(async {
106
        println!("task: start, awaiting timer...");
107
        let msg = TimerFuture::new(Duration::from_millis(50)).await;
108
        println!("task: timer returned {msg:?}");
109
    });
110
    drop(spawner); // close the channel so run() exits after tasks finish
111
    executor.run();
112
    println!("executor: all tasks complete");
113
}

Real output:

1
task: start, awaiting timer...
2
task: timer returned "timer done"
3
executor: all tasks complete

Trace the flow: the executor polls the task → the TimerFuture is not done, so it stores the waker and returns Pending → the executor parks (its recv() blocks) → 50 ms later the timer thread sets completed and calls waker.wake(), which sends the task back onto the queue → the executor wakes, polls again → Ready. No CPU was spinning during the wait. That single wake-and-re-poll cycle is the essence of every async runtime.

Why a state machine instead of a thread?

Each suspended async fn is a value just big enough to hold its live locals at its widest .await point — typically tens to a few hundred bytes. A thread needs a full OS stack (often megabytes) and a context switch to suspend. Millions of pending futures cost a few hundred megabytes of heap; millions of threads are impossible. This is why async scales to huge connection counts. The trade-off is the topic of async-vs-sync.md.

Key Differences

Concept	JavaScript `Promise`	Rust `Future`
Model	Push (callbacks invoked for you)	Pull (`poll` called on it)
When work starts	Eagerly, at creation	Lazily, only when polled
Built-in driver	Yes — the engine’s event loop	No — bring a runtime (Tokio, etc.)
Suspension mechanism	Engine resumes the coroutine	`Poll::Pending` + a `Waker`
Cancellation	Hard (Promises can’t be cancelled)	Drop the future — it stops being polled
Cost per pending op	Heap object + microtask queue entry	A small state-machine value (no thread)
Compiled form	Engine-internal coroutine	A concrete `enum`/struct generated at compile time

Tip: Two consequences fall straight out of “pull, not push.” First, dropping a future cancels it — no one polls it again, so its remaining work never runs (a clean, structured cancellation JavaScript lacks). Second, an async fn you never .await and never hand to a runtime simply never executes — the compiler even warns you about the unused future.

`Waker`: the “call me back” handle

A Waker is a type-erased, cheaply-cloneable handle (an Arc-like fat pointer to a vtable). Its only meaningful method is wake() (consuming) / wake_by_ref() (borrowing). Whoever a future is waiting on — a timer thread, an epoll reactor, another task — keeps the waker and calls it when progress is possible. The waker’s job is not to run the future; it is to put the future’s task back on the runtime’s ready queue. This indirection is what lets the same future run unchanged on Tokio, smol, or your 80-line MiniExecutor above.

Common Pitfalls

Pitfall 1: Trying to call `poll` on a future you own

poll takes self: Pin<&mut Self>, not &mut self. You cannot call it on a plain owned or borrowed future; you must pin it first. TypeScript developers expecting future.poll(cx) to “just work” hit this:

1
use std::future::Future;
2
use std::task::{Context, Waker};
3

4
async fn work() -> i32 { 42 }
5

6
fn main() {
7
    let waker = Waker::noop();
8
    let mut cx = Context::from_waker(&waker);
9
    let mut fut = work();
10
    // does not compile (E0599): poll() needs Pin<&mut Self>, not a bare &mut.
11
    let _ = fut.poll(&mut cx);
12
}

The real compiler error is informative — it even points you at pinning:

1
error[E0599]: no method named `poll` found for opaque type `impl Future<Output = i32>` in the current scope
2
  --> src/main.rs:11:17
3
   |
4
11 |     let _ = fut.poll(&mut cx);
5
   |                 ^^^^ method not found in `impl Future<Output = i32>`
6
   |
7
   = help: method `poll` found on `Pin<&mut impl Future<Output = i32>>`, see documentation for `std::pin::Pin`
8
   = help: self type must be pinned to call `Future::poll`, see https://rust-lang.github.io/async-book/04_pinning/01_chapter.html#pinning-in-practice
9
help: consider pinning the expression
10
   |
11
11 ~     let mut pinned = std::pin::pin!(fut);
12
12 ~     let _ = pinned.as_mut().poll(&mut cx);

The fix is to pin it with the std::pin::pin! macro (stack pinning) or Box::pin (heap pinning), then call poll on Pin<&mut _>. Why poll requires Pin — because the generated state machine can be self-referential — is the entire subject of pin-unpin.md.

Pitfall 2: Returning `Pending` without registering a waker

If your poll returns Poll::Pending but never stores cx.waker() anywhere that will call it, the future hangs forever: the runtime parks the task and nothing ever re-enqueues it. There is no compiler error — it is a runtime deadlock. The rule is: every Pending path must ensure the current waker will eventually be woken. In our TimerFuture we store the waker on every poll; doing it only on the first poll would be a subtle bug, because the runtime may poll with a new waker after a task is moved between threads.

Pitfall 3: Blocking the executor inside `poll` / an `async fn`

poll must return quickly. If you do CPU-heavy work or call a blocking API (std::fs::read, std::thread::sleep, a synchronous DB driver) inside an async fn, you stall the executor thread and starve every other task scheduled on it — the async analog of blocking the JavaScript event loop, but worse, because one Tokio worker may be driving thousands of tasks. Use the async equivalents (tokio::fs, tokio::time::sleep) or move blocking work to tokio::task::spawn_blocking.

Pitfall 4: Assuming `.await` yields to other tasks

.await only yields control if the awaited future returns Pending. A future that is always immediately Ready (a tight loop of async { 1 }.await) never hands the executor a chance to run anything else. If you need to cooperatively yield in a long-running async loop, call tokio::task::yield_now().await explicitly.

Best Practices

Let the compiler write your state machines. Write async fn; hand-implementing Future is for library authors building leaf futures (timers, I/O sources) or combinators. Reach for it only when you genuinely need custom poll behavior.
When you must implement Future, prefer pin-project / pin-project-lite to safely access pinned fields, instead of writing unsafe Pin projections by hand. See the real-world example below.
Always re-register the current waker on every Pending. Store cx.waker().clone() (or compare-and-update); never assume the waker from a previous poll is still valid.
Use combinators and poll_fn for one-off futures. std::future::poll_fn(|cx| ...) builds a Future from a closure that returns Poll, avoiding a whole boilerplate struct.
Keep poll non-blocking and fast. Offload CPU work with spawn_blocking or rayon; use async I/O for I/O.
Reach for the right runtime. Tokio for almost everything; futures::executor::block_on for tests, examples, and synchronous edges where you just need to drive one future to completion.

1
// `poll_fn` builds a Future from a closure — no custom struct needed.
2
use std::future::poll_fn;
3
use std::task::Poll;
4

5
fn main() {
6
    let mut count = 0;
7
    let fut = poll_fn(move |cx| {
8
        count += 1;
9
        if count < 3 {
10
            cx.waker().wake_by_ref(); // re-poll soon
11
            println!("poll #{count}: Pending");
12
            Poll::Pending
13
        } else {
14
            println!("poll #{count}: Ready");
15
            Poll::Ready(count)
16
        }
17
    });
18
    // block_on drives the future on the current thread until it completes.
19
    let total = futures::executor::block_on(fut);
20
    println!("future completed after {total} polls");
21
}

Real output:

1
poll #1: Pending
2
poll #2: Pending
3
poll #3: Ready
4
future completed after 3 polls

Real-World Example

A common production need: instrument a future to see how often it is polled. A future polled hundreds of times before completing is a red flag — it may be waking spuriously (re-enqueuing itself without real progress) and burning CPU. The idiomatic way to wrap another future and add behavior around its poll is a combinator future. Because it stores the inner future by value, we use pin-project-lite to safely get a Pin<&mut Inner> for the inner field (the safe alternative to hand-written unsafe pin projection, covered in pin-unpin.md).

1
// Cargo.toml:
2
//   tokio = { version = "1.52", features = ["full"] }
3
//   pin-project-lite = "0.2"
4
use std::future::Future;
5
use std::pin::Pin;
6
use std::task::{Context, Poll};
7
use std::time::Duration;
8
use pin_project_lite::pin_project;
9

10
pin_project! {
11
    /// Wraps any future and counts how many times it is polled before completing.
12
    /// Drop this around a suspicious future to diagnose spurious wakeups.
13
    struct PollCounter<F> {
14
        #[pin]
15
        inner: F,
16
        polls: u32,
17
        label: &'static str,
18
    }
19
}
20

21
impl<F: Future> PollCounter<F> {
22
    fn new(label: &'static str, inner: F) -> Self {
23
        PollCounter { inner, polls: 0, label }
24
    }
25
}
26

27
impl<F: Future> Future for PollCounter<F> {
28
    type Output = F::Output;
29
    fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<F::Output> {
30
        let this = self.project();        // safe pinned access to fields
31
        *this.polls += 1;
32
        let n = *this.polls;
33
        match this.inner.poll(cx) {        // delegate to the wrapped future
34
            Poll::Pending => {
35
                println!("[{}] poll #{n} -> Pending", this.label);
36
                Poll::Pending
37
            }
38
            Poll::Ready(v) => {
39
                println!("[{}] poll #{n} -> Ready (took {n} polls)", this.label);
40
                Poll::Ready(v)
41
            }
42
        }
43
    }
44
}
45

46
async fn fetch_user(id: u32) -> String {
47
    // Two awaits => the inner future suspends (Pending) more than once.
48
    tokio::time::sleep(Duration::from_millis(10)).await;
49
    tokio::time::sleep(Duration::from_millis(10)).await;
50
    format!("user#{id}")
51
}
52

53
#[tokio::main]
54
async fn main() {
55
    let name = PollCounter::new("fetch_user", fetch_user(7)).await;
56
    println!("result: {name}");
57
}

Real output:

1
[fetch_user] poll #1 -> Pending
2
[fetch_user] poll #2 -> Pending
3
[fetch_user] poll #3 -> Ready (took 3 polls)
4
result: user#7

The wrapper is transparent — fetch_user runs unchanged — yet you can now see it suspends twice (once per sleep) and completes on the third poll. This same delegation pattern is exactly how Tokio’s Timeout, the futures crate’s Map/Then, and tracing instrumentation like tracing-futures are built: a struct that holds an inner future, projects to it with Pin, and adds logic around the poll call.

Exercises

Exercise 1

Difficulty: Beginner

Objective: Implement Future by hand to feel the poll loop.

Instructions: Write a struct Countdown { remaining: u32 } that implements Future<Output = &'static str>. On each poll, if remaining == 0 return Poll::Ready("liftoff"); otherwise print T-minus {remaining}, decrement it, wake the current waker so it is polled again, and return Poll::Pending. Drive it with #[tokio::main] and .await, starting from remaining: 3.

Solution

1
use std::future::Future;
2
use std::pin::Pin;
3
use std::task::{Context, Poll};
4

5
struct Countdown {
6
    remaining: u32,
7
}
8

9
impl Future for Countdown {
10
    type Output = &'static str;
11
    fn poll(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<&'static str> {
12
        if self.remaining == 0 {
13
            Poll::Ready("liftoff")
14
        } else {
15
            println!("T-minus {}", self.remaining);
16
            self.remaining -= 1;
17
            cx.waker().wake_by_ref(); // ask to be polled again
18
            Poll::Pending
19
        }
20
    }
21
}
22

23
#[tokio::main]
24
async fn main() {
25
    let msg = Countdown { remaining: 3 }.await;
26
    println!("{msg}");
27
}

Real output:

1
T-minus 3
2
T-minus 2
3
T-minus 1
4
liftoff

Exercise 2

Difficulty: Intermediate

Objective: Build a combinator future that polls two futures and returns whichever finishes first — a hand-rolled select/Promise.race.

Instructions: Write struct Race<A, B> { a: A, b: B } implementing Future<Output = T> where A: Future<Output = T> + Unpin and B: Future<Output = T> + Unpin. On each poll, poll a; if it is Ready, return its value; otherwise poll b and return its value if Ready; if both are Pending, return Pending. Test it with a small ReadyAfter { polls_left, value } leaf future and confirm the one that becomes ready sooner wins. (The Unpin bound lets you use Pin::new(&mut self.a) safely.)

Solution

1
use std::future::Future;
2
use std::pin::Pin;
3
use std::task::{Context, Poll};
4

5
/// Polls two futures of the same output type; returns whichever is Ready first.
6
struct Race<A, B> {
7
    a: A,
8
    b: B,
9
}
10

11
impl<A, B, T> Future for Race<A, B>
12
where
13
    A: Future<Output = T> + Unpin,
14
    B: Future<Output = T> + Unpin,
15
{
16
    type Output = T;
17
    fn poll(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<T> {
18
        if let Poll::Ready(v) = Pin::new(&mut self.a).poll(cx) {
19
            return Poll::Ready(v);
20
        }
21
        if let Poll::Ready(v) = Pin::new(&mut self.b).poll(cx) {
22
            return Poll::Ready(v);
23
        }
24
        Poll::Pending
25
    }
26
}
27

28
struct ReadyAfter {
29
    polls_left: u32,
30
    value: u32,
31
}
32

33
impl Future for ReadyAfter {
34
    type Output = u32;
35
    fn poll(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<u32> {
36
        if self.polls_left == 0 {
37
            Poll::Ready(self.value)
38
        } else {
39
            self.polls_left -= 1;
40
            cx.waker().wake_by_ref();
41
            Poll::Pending
42
        }
43
    }
44
}
45

46
#[tokio::main]
47
async fn main() {
48
    let winner = Race {
49
        a: ReadyAfter { polls_left: 3, value: 1 }, // ready later
50
        b: ReadyAfter { polls_left: 1, value: 2 }, // ready sooner -> wins
51
    }
52
    .await;
53
    println!("winner: {winner}");
54
}

Real output:

1
winner: 2

Note: A production select! is fairer (it does not always poll a first) and handles non-Unpin futures via pinning; this exercise version is deliberately simplified to focus on the poll mechanics.

Exercise 3

Difficulty: Advanced

Objective: Wire up a Waker across tasks: build a one-shot event that one task waits on and another task fires, exactly as a real synchronization primitive does.

Instructions: Build an Event backed by Arc<Mutex<{ ready: bool, waker: Option<Waker> }>>. Give it fire(&self) (set ready = true and call any stored waker) and wait(&self) -> impl Future<Output = ()>. The wait-future’s poll returns Ready(()) when ready, otherwise stores cx.waker().clone() and returns Pending. Spawn a task that .awaits event.wait(), sleep briefly in main, then event.fire() and confirm the waiter resumes.

Solution

1
use std::future::Future;
2
use std::pin::Pin;
3
use std::sync::{Arc, Mutex};
4
use std::task::{Context, Poll, Waker};
5

6
#[derive(Default)]
7
struct EventInner {
8
    ready: bool,
9
    waker: Option<Waker>,
10
}
11

12
#[derive(Clone, Default)]
13
struct Event {
14
    inner: Arc<Mutex<EventInner>>,
15
}
16

17
impl Event {
18
    fn fire(&self) {
19
        let mut g = self.inner.lock().unwrap();
20
        g.ready = true;
21
        if let Some(w) = g.waker.take() {
22
            w.wake(); // re-enqueue the waiting task
23
        }
24
    }
25

26
    fn wait(&self) -> EventWait {
27
        EventWait { ev: self.clone() }
28
    }
29
}
30

31
struct EventWait {
32
    ev: Event,
33
}
34

35
impl Future for EventWait {
36
    type Output = ();
37
    fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<()> {
38
        let mut g = self.ev.inner.lock().unwrap();
39
        if g.ready {
40
            Poll::Ready(())
41
        } else {
42
            // Always store the LATEST waker; the task may have moved threads.
43
            g.waker = Some(cx.waker().clone());
44
            Poll::Pending
45
        }
46
    }
47
}
48

49
#[tokio::main]
50
async fn main() {
51
    let event = Event::default();
52
    let waiter = {
53
        let event = event.clone();
54
        tokio::spawn(async move {
55
            println!("waiter: blocking on event");
56
            event.wait().await;
57
            println!("waiter: event fired, resuming");
58
        })
59
    };
60

61
    tokio::time::sleep(std::time::Duration::from_millis(20)).await;
62
    println!("main: firing event");
63
    event.fire();
64
    waiter.await.unwrap();
65
}

Real output:

1
waiter: blocking on event
2
main: firing event
3
waiter: event fired, resuming

This is a minimal version of tokio::sync::Notify / a one-shot channel: the waiter parks (no busy-waiting), and fire() wakes it through the stored Waker. Re-storing the waker on every Pending poll is what makes it correct under Tokio’s multi-threaded scheduler.

How Async/Await Works Under the Hood

Quick Overview

TypeScript/JavaScript Example

Rust Equivalent

Detailed Explanation

The `Future` trait has exactly one job

`Output` is the resolved type

`Context` carries the `Waker`

The `.await` de-sugar is a poll loop

Who calls `poll`? The runtime.

Why a state machine instead of a thread?

Key Differences

`Waker`: the “call me back” handle

Common Pitfalls

Pitfall 1: Trying to call `poll` on a future you own

Pitfall 2: Returning `Pending` without registering a waker

Pitfall 3: Blocking the executor inside `poll` / an `async fn`

Pitfall 4: Assuming `.await` yields to other tasks

Best Practices

Real-World Example

Further Reading

Official Documentation

Exercises

Exercise 1

Exercise 2

Exercise 3

How Async/Await Works Under the Hood

Quick Overview

TypeScript/JavaScript Example

Rust Equivalent

Detailed Explanation

The Future trait has exactly one job

Output is the resolved type

Context carries the Waker

The .await de-sugar is a poll loop

Who calls poll? The runtime.

Why a state machine instead of a thread?

Key Differences

Waker: the “call me back” handle

Common Pitfalls

Pitfall 1: Trying to call poll on a future you own

Pitfall 2: Returning Pending without registering a waker

Pitfall 3: Blocking the executor inside poll / an async fn

Pitfall 4: Assuming .await yields to other tasks

Best Practices

Real-World Example

Further Reading

Official Documentation

Related Sections in This Guide

Exercises

Exercise 1

Exercise 2

Exercise 3

The `Future` trait has exactly one job

`Output` is the resolved type

`Context` carries the `Waker`

The `.await` de-sugar is a poll loop

Who calls `poll`? The runtime.

`Waker`: the “call me back” handle

Pitfall 1: Trying to call `poll` on a future you own

Pitfall 2: Returning `Pending` without registering a waker

Pitfall 3: Blocking the executor inside `poll` / an `async fn`

Pitfall 4: Assuming `.await` yields to other tasks