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

rust
1// Creating
2let mut guard = AsyncDropGuard::new(my_value);
3
4// Using (transparent via Deref)
5guard.do_something();
6
7// Cleanup (REQUIRED before dropping)
8guard.async_drop().await?;

The AsyncDrop Trait

rust
1#[async_trait]
2pub trait AsyncDrop {
3    type Error: Debug;
4    async fn async_drop_impl(&mut self) -> Result<(), Self::Error>;
5}

Essential Rules

The with_async_drop_2! Macro

Automatically calls async_drop() on scope exit:

rust
1let resource = get_resource().await?;
2with_async_drop_2!(resource, {
3    // Use resource here
4    resource.do_work().await?;
5    Ok(result)
6})

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/