Skip to content
Tutorials Center
My learning

Topics

Lesson 84 of 132 ยท Async Rust

Async Patterns with a Mini Runtime

Learn async Rust patterns by building them: a task executor with spawn and JoinHandle, channels between tasks, select, cancellation by drop, poll_fn, and async closures.

Async Rust has one surprising fact at its core: the standard library gives you Future, async and .await, but no runtime. Nothing in std can start a task, wait for a timer or run two futures side by side. All of that comes from an executor, usually from a crate such as Tokio. That sounds like a drawback, but it also means that the machinery is small enough to write yourself in a lesson, and once you have written it, the patterns you see in real async code (spawning, joining, channels, select!, cancellation) stop being magic.

In this lesson you build a tiny single-threaded executor and use it to explore the patterns. Everything runs with the standard library only, so you can edit and run every example. If futures, Poll and wakers feel new, read async/await basics and futures and executors by hand first. The next lesson shows how Tokio provides the same ideas, with real timers and I/O.

The examples are deterministic on purpose. The executor runs on one thread and always takes tasks from a first-in, first-out queue, so the order of the output never changes. Real runtimes such as Tokio run tasks on several threads and make no promise about the order in which ready tasks run.

What an executor does

An async task is a future that something keeps polling. The executor's whole job is a loop:

  1. Take a task that is ready from a queue.
  2. Call poll on it. The task runs until it hits an .await on something that is not ready yet, then returns Poll::Pending.
  3. When the thing it waits for becomes ready, that thing calls wake() on the task's waker. The waker puts the task back in the queue.
  4. Repeat until the queue is empty.

A task that returns Pending without arranging for a wake-up is never polled again. That is the most common async bug, and our executor will help us see it.

Here is a complete executor in about 60 lines. It owns the tasks, keeps a queue of task numbers that are ready to run, and hands each task a waker that pushes its number back on the queue. It also has spawn, which returns a JoinHandle you can .await to get a task's result. The program at the bottom spawns three workers that each print three steps and yield to the others after each step. A yield_now future is the smallest possible future: the first poll returns Pending after asking to be woken at once, the second poll returns Ready.

Rust A tiny executor with spawn and JoinHandle

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 output. The three workers take turns: A, B, C, then A again. No task ever ran two steps in a row, because yield_now().await handed control back to the executor, which moved on to the next task in the queue. That is cooperative scheduling: tasks switch only at .await points. The fourth task spawned a child, printed a message, and then awaited the child's JoinHandle. The handle returned Pending and stored the task's waker; when the child finished, the wrapper future woke the waiting task and it got the value 42.

Notice that nothing here used a thread. Thousands of tasks cost only their futures' sizes, which is why async is attractive for servers that wait on many sockets.

Dropping a JoinHandle

In this executor (and in Tokio), dropping a JoinHandle does not cancel the task. It detaches it: the task keeps running and its result is thrown away. Contrast that with dropping an ordinary future, which stops it dead; we come back to that in the cancellation section.

std::future helpers: ready, pending and poll_fn

The standard library has three tiny building blocks that are handy in tests and in your own combinators.

  • std::future::ready(value) is a future that is immediately Ready with value.
  • std::future::pending::<T>() is a future that is never ready. It is the neutral element for "wait forever".
  • std::future::poll_fn(closure) turns a closure FnMut(&mut Context) -> Poll<T> into a future, so you can write a hand-made future without defining a struct.

To keep this example free of any executor, here is a minimal block_on that runs one future on the current thread by parking it until it is woken. It is the executor from the previous section reduced to one task. It also uses Waker::noop() (stable since Rust 1.85), a waker that does nothing, to poll once by hand.

Rust ready, pending and poll_fn

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.

poll_fn is the quickest way to experiment with polling. Notice the wake_by_ref() call inside the Pending branch. Remove it, and block_on would park the thread forever, because nobody is left to wake it. Whenever you return Pending, you promise that something will call the waker later.

Channels between tasks

Tasks usually need to talk to each other. An async channel is a queue plus a stored waker: recv() returns Pending when the queue is empty and remembers the waker, and send() pushes a value and wakes the waiting receiver. Here is a minimal unbounded channel built on poll_fn. It closes when the last Sender is dropped, so the receiver's loop can end.

The second half of main shows what a lost wake-up looks like from the executor's point of view. The receiver is waiting on a channel whose sender is still alive but never sends. Nothing will ever wake that task, so the queue runs dry while a task is still unfinished, and run reports it.

Rust An async channel between two tasks

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 collector prints messages in the order they were sent, and when the last worker finishes and its Sender is dropped, Drop wakes the collector one more time so that it can see None and leave its loop. That wake on close is easy to forget when writing channels. Without it, the collector would wait forever, exactly like the receiver in the second half of the program.

Real channels, such as tokio::sync::mpsc, work the same way, plus a bound on the queue so that fast producers cannot use unlimited memory.

Racing futures: a select by hand

Often you want to wait for the first of several things: a reply or a timeout, a message or a shutdown signal. In Tokio that is the select! macro. Underneath, it is one future that polls its branches in turn and finishes with the first that is ready. Here is a two-way version in a few lines, using poll_fn and pin!:

Rust
async fn select<A: Future, B: Future>(a: A, b: B) -> Either<A::Output, B::Output> {
    let mut a = pin!(a);
    let mut b = pin!(b);
    poll_fn(|cx| {
        if let Poll::Ready(v) = a.as_mut().poll(cx) {
            return Poll::Ready(Either::Left(v));
        }
        if let Poll::Ready(v) = b.as_mut().poll(cx) {
            return Poll::Ready(Either::Right(v));
        }
        Poll::Pending
    })
    .await
}

The branch that did not win is simply dropped when select returns. That brings us to the next topic.

Cancellation is dropping

A future is a value, and a future that is dropped is gone. There is no cancel() method in Rust's async model. To cancel an async operation you stop polling it and drop it. Whatever it had done up to its last .await stays done, and the code after that .await never runs. Variables the future owned are dropped normally, so Drop implementations run.

That has a real design consequence: any cleanup that must happen has to live in a Drop implementation, not in the lines after an .await. In the next example, a Guard reports whether its work finished or was cancelled. A fast job races a slow job through our select.

Rust select and cancellation by drop

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.

Study the output. The two jobs alternate their steps, because select polls a, then b, every time it is polled. When fast completes, select returns and its locals, including the pinned slow future, are dropped. Dropping slow drops the Guard it was holding at its last .await, and that prints CANCELLED. The last case shows laziness: a future that is never polled never even creates its guard.

Cancellation can happen at any .await. If a task updates two things with an .await in between, a cancellation in the middle leaves the first update done and the second one missing. This is called cancel safety. Documentation for async APIs, such as Tokio's, states for each function whether it is cancel-safe. When you write your own, make state changes either happen entirely between two .await points or be repaired in Drop.

Async closures

An ordinary closure that returns a future, such as |x| async move { ... }, has a long-standing limitation: the future it returns cannot borrow from the closure's own captured variables in a lending way, and the types of such closures are hard to name in bounds. Rust 1.85 added async closures, written async |x| { ... }, together with the traits AsyncFn, AsyncFnMut and AsyncFnOnce. They are the async versions of Fn, FnMut and FnOnce.

Rust Async closures and AsyncFn bounds (Rust 1.85)

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 second closure mutates log across .await points and the caller reads log afterwards. Try to express that with |round| async move { ... }: the async move block would take ownership of log on the first call, which a closure that may be called again cannot allow, and a non-move block cannot return a future borrowing the closure's own state. This is exactly the gap async closures fill. Here is the mistake in its natural form:

Rust A closure returning a borrowing future (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.

The compiler refuses with error: captured variable cannot escape FnMut closure body. The async block borrows count from the closure, and an FnMut closure cannot hand out such a borrow, because it could be called again while the first future still exists. The fix is the new syntax, let mut bump = async || { count += 1; };, whose futures are allowed to borrow from the closure itself. Use async closures for callbacks (retry helpers, with_connection(async |conn| { ... }), per-item handlers). The older |x| async move { ... } form still works when each call can simply take ownership of cloned values.

Pitfalls you will meet in real code

  • Blocking inside a task. thread::sleep or a long loop in one task stops every task on that executor thread, since tasks only switch at .await. Our executor makes the damage obvious: nothing else runs. Move blocking work to a thread (thread::spawn) or to your runtime's spawn_blocking.
  • Returning Pending without a wake-up. The task is never polled again. Symptoms: the program ends early, or hangs with no CPU use. Our run function reports such tasks as stuck.
  • Holding a RefCell borrow or a lock across .await. The guard stays alive while the task is suspended, so another task can hit BorrowMutError or deadlock. Release the guard (scope it in a block) before awaiting.
  • Detached tasks hide errors. A dropped JoinHandle discards the result, including a panic. Await your handles, or collect them.
  • Fairness. A task that loops without ever awaiting something that returns Pending starves the others. A yield_now().await inside a long loop fixes that.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What does the executor do with a task that returns Poll::Pending and never calls its waker?

    A task is only put back in the ready queue when its waker is called. Without a wake-up the executor has no reason to poll it, so the task sits there forever. That is why every Pending needs a registered waker.
  2. 2. What happens when you drop a future that is in the middle of an async function?

    Cancellation in Rust is dropping. The future's state, including locals, is dropped normally (so Drop impls run), but nothing after the suspended .await is executed.
  3. 3. What does dropping a JoinHandle do in the executor of this lesson?

    The task is owned by the executor, not by the handle. The handle only gives access to the result. Dropping it does not stop the task.
  4. 4. Why is the order of the output in this lesson's executor examples always the same?

    That is a property of our simple executor, not of Rust. Multi-threaded runtimes such as Tokio do not promise any order between ready tasks.
  5. 5. What is std::future::pending::<T>() useful for?

    pending never returns Ready. It is the opposite of std::future::ready, which completes immediately.

Summary

  • The standard library defines Future, Waker and Wake, but the executor that polls tasks comes from you or from a crate.
  • An executor loops: pop a ready task, poll it, and rely on wakers to put tasks back in the queue. A Pending without a registered waker means a task that is lost for good.
  • spawn hands a future to the executor; a JoinHandle is a future for the result, and dropping it detaches the task rather than cancelling it.
  • Async channels are a queue plus a stored waker; remember to wake the receiver both on send and when the last sender is dropped.
  • select polls branches in order and drops the losers. Cancellation always means dropping the future, so put cleanup in Drop and design for cancel safety.
  • std::future::ready, pending and poll_fn are small tools for tests and custom futures; Waker::noop() needs Rust 1.85 and pin! Rust 1.68.
  • Async closures (async |x| ..., AsyncFn*, Rust 1.85) can borrow and mutate captured state across .await.
  • Never block inside a task, and never hold a lock or RefCell borrow across an .await.

Next: Tokio and the Async Ecosystem