Canceling asynchronous Rust

Welcome to LWN.net The following subscription-only content has been made available to you by an LWN subscriber. Thousands of subscribers depend on LWN for the best news from the Linux and free software communities. If you enjoy this article, please consider subscribing to LWN. Thank you for visiting LWN.net!

Asynchronous Rust code has what Rain Paharia calls a "universal cancellation protocol", meaning that any asynchronous code can be interrupted in the same way. They claim that this is both a useful feature when used deliberately, and a source of errors when done by accident. They presented about this problem at RustConf 2025, offering a handful of techniques to avoid introducing bugs into asynchronous Rust code.

Paharia started their talk (slides) with a question for the Rust programmers in the audience. Suppose that one wanted to use the tokio library's asynchronous queues (called channels) to read from a channel in a loop until the channel is closed, raising an error if the channel is ever empty for too long. Is this code the correct way to do it?

    loop {
        match timeout(Duration::from_secs(5), rx.recv()).await {
            Ok(Ok(msg)) => process(msg),
            Ok(Err(_)) => return,
            Err(_) => println!("No messages for 5 seconds"),
        }
    }

As is typical of code shown on slides, this example is somewhat terse. In this case, timeout() returns an Err value if it hits the time limit, or an Ok value wrapping the return value from whatever operation is being subjected to a time limit — in this case, rx.recv(). That returns either an error (when the channel is closed unexpectedly) or an Ok value containing the message read from the channel. In a real application, the programmer would probably want to handle the channel closing more explicitly; but as far as example code goes, it demonstrates the basic idea of wrapping a read from a channel in a timeout.

The members of the audience were hesitant to answer, because anytime a speaker asks you if code is correct, it seems like they're about to point out a subtle problem. But, after a moment of tension, Paharia revealed that yes, this is completely correct code. What about the corresponding code for the other end of the channel? They put up another slide, and asked whether anyone thought this was the right way to write to a channel:

    loop {
        let msg = next_message();
        match timeout(Duration::from_secs(5), tx.send(msg)).await {
            Ok(Ok(_)) => println!("Sent successfully"),
            Ok(Err(_)) => return,
            Err(_) => println!("No space in queue for 5 seconds"),
        }
    }

This time, people were a bit more confident: no, that code has a bug. If the send times out (taking the Err(_) branch) or the channel is closed (the Ok(Err(_)) branch), the code drops msg, potentially losing data. This is a problem, Paharia said: because of the way asynchronous Rust is currently designed, it's far too easy to make a mistake like this by accident.

They wanted to emphasize that this wasn't to claim that asynchronous Rust is bad. "I love async!" They gave a talk at RustConf 2023 about how it's a great fit for writing correct POSIX signal-handling code, even. At their job at Oxide, they use asynchronous Rust throughout the company's software stack. Asynchronous Rust is great, so they've written a lot of it — which is exactly why they've run into so many problems around canceling asynchronous tasks, and why they want to share ways to minimize those pitfalls.

Asynchronous Rust is built around the Future trait, which represents a computation that can be polled and suspended. When the programmer writes an asynchronous function, the compiler turns it into an enumeration representing the possible states of a state machine. That enumeration implements Future, which provides a common interface for driving state machines forward. async functions make it ergonomic to stick those little state machines together into bigger state machines using await.

Paharia likes this design, but says that it can come as a surprise to programmers moving to Rust from JavaScript or Go, where the equivalent language mechanism is implemented with green threads. In those languages, creating the equivalent of a Future (called a promise) starts executing the code right away in a separate thread, and the promise is just a handle for retrieving the eventual result. In Rust, creating a Future doesn't do anything — it just creates the state machine in memory. Nothing actually happens until the programmer calls the .poll() method.

Rust's design here is driven by the needs of embedded software, they explained. In the embedded world, there are no threads and no runtime, so it pretty much has to work like this. The fact that asynchronous tasks in Rust are just normal data is also what makes it easy to cancel them. If one wants to cancel an asynchronous function, one can just stop calling .poll() on it. There are lots of ways to do that. Paharia gave some examples of real bugs where they had written code that accidentally dropped (freed) a Future:

    // An operation that is initially implemented in synchronous code
    some_operation();

    // It returns a Result, which the linter warns about ignoring
    // But in this case we don't care, so silence the linter warning:
    let _ = some_operation();

    // Later, it gets refactored to be written asynchronously
    let _ = some_async_operation();

    // ... now the Future is being created and dropped without being run

At that point, they wanted to define two terms: "cancel safety" and "cancel correctness". Cancel safety refers to whether a Future can be safely dropped or not. The reader example above can be safely dropped — it will just stop reading from the queue. The writer example cannot — dropping it can also drop some data. The former is "cancel-safe" and the latter is not. Tokio's documentation has a section on whether their asynchronous API functions are cancel-safe or not, so programmers can usually figure this out by just looking at the local definition of a function.

Cancel correctness, on the other hand, is a global property of the whole program. A program is cancel-correct if it doesn't have any bugs related to Future cancellation. A cancel-unsafe function will not always lead to correctness problems. For example, if one is using some kind of acknowledgment and redelivery mechanism, it might not actually be a bug to drop a message like the example does.

Three things have to be true for there to be a cancel-correctness bug, Paharia said. A cancel-unsafe Future must exist, get canceled at some point, and that cancellation must violate a system property. Most approaches to eliminating cancel-correctness bugs work by tackling one of those three pillars. Unfortunately, no single technique is a complete solution in current Rust. They went on to share a handful of techniques that can all help to eliminate cancel-correctness bugs.

The first technique is to break up potentially dangerous operations into smaller pieces. The writer example from above could use the .reserve() method on a tokio queue to obtain access to a guaranteed slot for the message, before it actually sends it. This code won't drop msg if a timeout occurs:

    loop {
        let msg = next_message();
        loop {
            match timeout(Duration::from_secs(5), tx.reserve()).await {
                Ok(Ok(permit)) => { permit.send(msg); break; }
                Ok(Err(_)) => return,
                Err(_) => println!("No space for 5 seconds"),
            }
        }
    }

That works, but it still takes care to get right. Another technique would be to use APIs that record partial progress, so that the programmer can know what data has been processed and what has not. For example, tokio's Writer::write_all() method is not cancel-safe, but there is an alternative Writer::write_all_buf() that uses a cursor so the programmer can see where a write was interrupted and recover.

A final technique is to use threads to emulate the approach from Go and JavaScript. Tokio has a spawn() function that takes a Future, starts a new thread (or grabs one from a thread pool), and then runs the Future to completion.

"This sucks!" Paharia summarized. All of these techniques can help, but none of them is a full, systemic solution. They went so far as to call this the "least Rusty part of Rust" because the language doesn't have any mechanisms to prevent this kind of bug — yet.

There is hope for the future. There are three different proposals for how Rust could rule out cancel-correctness bugs: Async drop, which would let asynchronous code run a cleanup function on cancellation; Unforgettable types, which would require all Future values to be used; and the closely related Undroppable types.

In the future, when one of those proposals has been decided on and adopted, this entire class of bugs could go away. Until then, Paharia recommends finding ways to make asynchronous code cancel-safe, design APIs that make it easy to do the right thing, and use techniques like spawned threads to ensure that critical Future values can't be dropped or forgotten by accident. There wasn't time for everything they wanted to cover in the talk, so more detail is available in the document they wrote for Oxide on the topic.