AsyncDrop Pattern Guide

The AsyncDrop pattern enables async cleanup for types that hold resources requiring asynchronous teardown (network connections, file handles, background tasks, etc.).

Core Concept

Rust's Drop trait is synchronous, but sometimes cleanup needs to be async. The AsyncDrop pattern solves this by:

1. Wrapping values in AsyncDropGuard<T>
2. Requiring explicit async_drop().await calls
3. Panicking if cleanup is forgotten

Quick Reference

// Creating (no `mut` needed unless you mutate the value)
let guard = AsyncDropGuard::new(my_value);

// Using (transparent via Deref)
guard.do_something();

// Cleanup (REQUIRED before dropping). Consumes the guard:
// using `guard` after this line is a compile error.
guard.async_drop().await?;

The AsyncDrop Trait

pub trait AsyncDrop {
    type Error: Debug;
    fn async_drop_impl(self) -> impl Future<Output = Result<(), Self::Error>> + Send;
}

Implement it as a plain async fn async_drop_impl(self) without #[async_trait]. self is taken by value, so destructure it to move AsyncDropGuard members out and drop them. List every field (name: _ for the ones that don't need dropping) instead of using ..: that way adding a field later is a compile error here, which forces whoever adds an AsyncDropGuard field to decide how to drop it.

impl AsyncDrop for MyType {
    type Error = anyhow::Error;

    async fn async_drop_impl(self) -> Result<(), Self::Error> {
        let Self { connection, cache, config: _ } = self;
        cache.async_drop().await?;
        connection.async_drop().await?;
        Ok(())
    }
}

Essential Rules

The with_async_drop! Macro

Automatically calls async_drop() on scope exit:

let resource = get_resource().await?;
with_async_drop!(resource, {
    // Use resource here
    resource.do_work().await?;
    Ok(result)
})

Several independent guards can be listed; they are dropped concurrently afterward:

with_async_drop!(source, dest, {
    move_entry(&source, &dest).await
})

To drop several independent guards without running a block, use async_drop_all((a, b, c)).await?.

Additional References

• patterns.md - Implementation patterns and examples
• gotchas.md - Common mistakes and how to avoid them
• helpers.md - Helper types (AsyncDropArc, AsyncDropHashMap, etc.)

Location

Implementation: crates/utils/src/async_drop/