Skip to content
Tutorials Center
My learning

Topics

Lesson 83 of 132 ยท Async Rust

Futures and Executors by Hand

Implement Rust's Future trait yourself: Poll, Pin and Context, a Wake-based block_on executor that parks the thread, a thread-backed timer future, and a join of two futures.

In the previous lesson you used async fn and a block_on that spun in a loop. This lesson takes the lid off. You will write a Future with your own hands, learn what a waker is and why every future must handle it, replace the busy loop with a proper executor that puts the thread to sleep, build a timer future backed by a helper thread, and write a join that runs two futures concurrently.

You will almost never write futures this way in day-to-day work, because async fn writes them for you and libraries provide timers and I/O. But writing them once is the fastest way to understand what a runtime such as Tokio actually does, and to debug the dreaded program that "just hangs".

Everything here uses only std: std::future::Future, std::task::{Context, Poll, Wake, Waker}, std::pin::Pin and std::thread. The code is deliberately small; production executors add task queues, multi-threading and I/O polling on top of the same ideas.

The Future trait, once more

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

The contract for poll:

  1. If the future is finished, return Poll::Ready(output). After that, it must not be polled again (it may panic or return anything).
  2. If it cannot finish yet, return Poll::Pending and make sure the executor will be told when to try again, by saving a clone of cx.waker() somewhere that will eventually call wake().
  3. poll must return quickly. Never block inside it.

Let us start with the simplest non-trivial future: one that counts down and is ready after N polls. It wakes itself immediately each time, which is legal but wasteful (it is a "yield" in disguise):

Rust A countdown 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.

Countdown contains only a u32, so it is Unpin (movable), which is why we may write self.remaining -= 1 through the Pin<&mut Self>: Pin hands out &mut access only to Unpin types. For types that hold self-references you would need unsafe or a helper crate like pin-project; for the futures in this lesson, plain fields are enough.

Now this future can be awaited from async code just like any other:

Rust Awaiting a hand-written 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.

The two countdowns need 2 and 1 pending polls, and the final poll completes everything, so the output is result 200 in 4 polls. The async function simply forwards each Pending to the executor: .await is a loop around poll that returns Pending up the chain.

Wakers: how a task asks to be polled again

A busy loop works for toy futures, but it burns a whole CPU core. An executor should sleep until some task can make progress. That is the waker's purpose.

A Waker is a handle that says "task X is ready to be polled again". Calling wake() is the future's way of telling the executor: something I was waiting for has happened. Executors build wakers from a type that implements the std::task::Wake trait (stable since Rust 1.51):

Rust
pub trait Wake {
    fn wake(self: Arc<Self>);
    fn wake_by_ref(self: &Arc<Self>) { /* default: clone and wake */ }
}

The simplest executor has exactly one task, so waking it means unparking the thread that is running block_on. thread::park() puts the thread to sleep; Thread::unpark() wakes it. An unpark that arrives before the park is remembered (a token), so there is no lost wake-up.

Rust A block_on that sleeps instead of spinning

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.

Waker::from(Arc<W>) works for any W: Wake + Send + Sync + 'static. The waker is Clone (it clones the Arc), Send and Sync, so a future can hand it to another thread, and that is exactly what the timer in the next section does. The program prints wake-ups seen: 2 because each of the two YieldOnce futures woke the task once.

Waker::noop() (Rust 1.85) is a waker whose wake does nothing. It is correct only for executors that poll in a loop anyway (like our first block_on), and for tests. Never give it to a future that waits for something external, or the wake-up is lost.

A timer future backed by a thread

A real I/O future registers interest with the operating system (epoll, kqueue, IOCP) and the reactor wakes it. We do not have a reactor, but we can do the same with an ordinary thread: spawn a thread that sleeps, marks the timer as completed and calls wake().

The shared state holds two things: whether the timer fired and the most recent waker. Always store the latest waker, because a future can be moved to a different task between polls and the old waker would then point to the wrong place.

Rust A Delay future with a timer thread

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.

Trace what happens. block_on polls the future, which creates a Delay (starting the helper thread) and polls it: not completed, so it stores the waker and returns Pending. block_on parks. 30 ms later the helper thread sets completed, calls wake(), which unparks the main thread. block_on polls again; this time the delay is complete and the async block moves on to the second one.

The lock is what avoids a race: if the timer fires between "check completed" and "store the waker", the thread would find no waker and nobody would ever wake the future. Because both sides hold the same mutex while checking and storing, one of two things must happen: the poll sees completed == true, or the thread sees the stored waker.

The classic way to write a hanging async program is to return Pending without registering a waker, or to register it and then forget to call wake(). The executor will happily sleep forever. When something hangs, ask: "who is going to call wake() for this future?"

Spurious polls

Executors are allowed to poll a future even when nobody woke it. Futures must therefore be idempotent about polling: check the real condition each time, and do not assume that being polled means progress is possible. The Delay above does the right thing, because it looks at completed on every poll rather than trusting the poll itself.

Running futures concurrently: join

A single block_on drives one future. To get two delays running at the same time, we can write a future that contains two futures and polls both. Its job is to hold each child's result until both are ready. Here is a small generic Join2, built on Box::pin so it does not need unsafe code:

Rust join: two timers at the same time

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.

Both timers start when Join2 is first polled, so the total wait is about 60 ms (the longer one), not 80 ms. The results come back as a tuple in argument order, not in completion order. Each child future gets the same waker from the Context; when either timer fires, the task is woken and Join2::poll runs again, polling both children (a finished child is skipped because its output is stored).

This is what futures::join! and tokio::join! do, with more care: macros avoid the boxing, handle any number of futures, and the generic bounds are hidden. The comment "fine: Join2 is Unpin because its fields are" matters: Pin<Box<_>> is always Unpin, and the stored outputs are Unpin by our bounds, which is why &mut *self compiles.

What a real executor adds

Our block_on runs one task on one thread. A general executor such as Tokio's adds:

  • a task queue: many futures, each wrapped in a task that knows how to re-schedule itself when its waker is called (next lesson builds this);
  • a reactor: one thread (or the OS) watching sockets and timers, calling wakers when they are ready, instead of a thread per timer;
  • work stealing across worker threads, so futures may be polled on different threads (hence Send bounds);
  • spawn, JoinHandles, cancellation, select!, timeouts and blocking-task pools.

Seeing that a waker is just "an Arc with a wake method" demystifies all of this. A task's waker typically pushes the task back onto the run queue.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What must a future do when it returns Poll::Pending?

    A pending future must register (a clone of) cx.waker() with whatever will complete it. Otherwise the executor never polls it again and the program hangs.
  2. 2. How can you create a Waker from your own type using only std?

    std::task::Wake plus Waker::from(Arc<W>) (stable since 1.51) is the safe way; RawWaker is the unsafe, lower-level one.
  3. 3. Why does the Delay future store cx.waker().clone() on every Pending poll?

    A future can move between tasks, so the waker passed to the most recent poll is the correct one. Calling a stale waker would wake the wrong task.
  4. 4. What is the purpose of thread::park() in our block_on?

    Parking avoids a busy loop. wake() calls unpark(), and an unpark that happens before the park leaves a token, so wake-ups are not lost.
  5. 5. A join of two 60 ms and 20 ms timers takes roughly how long?

    Both timers run at once, so the total is about the maximum. The result tuple keeps argument order regardless of completion order.

Summary

  • A hand-written Future implements poll, returning Ready(value) or Pending; .await inside async code just loops over poll and forwards Pending.
  • Before returning Pending, a future must store the waker from Context where the completing event will find it; forgetting this makes the program hang.
  • std::task::Wake + Waker::from(Arc<_>) builds wakers; a one-task executor can park the thread and let wake() unpark it.
  • Always store the most recent waker, and guard the "check then register" step with a lock to avoid lost wake-ups; expect spurious polls.
  • A join is a future that polls several child futures and keeps their outputs; real runtimes add task queues, reactors, work stealing and spawn.

Next: Async Patterns with a Mini Runtime