The RAII Drop-Guard Pattern in Rust

2026-04-30T00:00:00+00:00
The RAII Drop-Guard Pattern in Rust</h1>

Context</h2>
In Rust, any value that owns a resource and frees it in its Drop</code> implementation acts as a guard</strong>: the resource lives for exactly as long as the value is in scope. This is RAII - Resource Acquisition Is Initialization</em> - and in Rust it is the primary, statically-enforced mechanism for resource management.</p>
A drop guard</strong> is the pattern of binding such a value to a name whose sole purpose is to keep it in scope. It looks like you're creating an unused variable. You're not - you're creating a lexical region in which a resource is held. The compiler uses the variable's scope to schedule the exact point at which the resource is released.</p>
This doc explains the mechanics, why the pattern exists, the benefits it offers, and three concrete examples from real reviews where readers misread the pattern on first contact.</p>

1. The Rust mechanics</h2>
There are three syntactic forms people confuse. They behave differently.</p>
1.1 Three bindings that look similar</h3>
// Form A: bind to a proper name</span></span>
let</span> permit</span> =</span> sem</span>.</span>acquire</span>()</span>.</span>await</span>?</span>;</span></span>
</span>
// Form B: bind to a name starting with underscore</span></span>
let</span> _permit</span> =</span> sem</span>.</span>acquire</span>()</span>.</span>await</span>?</span>;</span></span>
</span>
// Form C: destructure with a bare underscore pattern</span></span>
let</span> _</span> =</span> sem</span>.</span>acquire</span>()</span>.</span>await</span>?</span>;</span></span></code></pre>
Semantically:</p>
Form</th> Binding</th> Drop runs at</th></tr></thead>

A - permit</code></td> yes</td> end of enclosing scope (}</code>)</td></tr>
B - _permit</code></td> yes</td> end of enclosing scope (}</code>)</td></tr>
C - _</code></td> no binding</strong></td> immediately on this statement</strong></td></tr>
</tbody></table>
Forms A and B are identical in terms of when Drop runs. They differ only in how the compiler treats the name for lint purposes:</p>

permit</code></strong> - a used-looking name. If you never read it, unused_variables</code> warns.</li>
_permit</code></strong> - a name starting with _</code> suppresses unused_variables</code> but is still a real binding. The value is stored; it lives until the scope ends.</li>
_</code></strong> (bare) - a pattern</em>, not a name. The value is matched, then immediately dropped. No storage, no name, no lifetime extension.</li>
</ul>
This distinction is critical for RAII. If you write let _ = sem.acquire().await?;</code>, you've released the permit on that very line - you held the slot for a nanosecond. If you write let _permit = sem.acquire().await?;</code>, you hold the slot until the closing brace.</p>
1.2 When does Drop actually run?</h3>
Scope exit, in LIFO order of creation. Temporaries within an expression drop at the end of the enclosing statement; let</code>-bound values drop at the end of their block.</p>
fn</span> work</span>() {</span></span>
    let</span> a</span> =</span> Guard</span>::</span>new</span>("</span>a</span>");</span>       // acquired</span></span>
    let</span> b</span> =</span> Guard</span>::</span>new</span>("</span>b</span>");</span>       // acquired</span></span>
    do_stuff</span>();</span>                    // runs with both guards held</span></span>
    // implicit: b dropped, then a dropped</span></span>
}</span></span></code></pre>fn</span> work</span>() {</span></span>
    {</span></span>
        let</span> _inner</span> =</span> Guard</span>::</span>new</span>("</span>inner</span>");</span></span>
        do_inner</span>();</span></span>
    }</span>                              // _inner dropped here</span></span>
    do_outer</span>();</span>                    // runs with no guards held</span></span>
}</span></span></code></pre>
The compiler inserts the drops at the }</code>. You cannot observe them in the source, but they are deterministic and guaranteed barring abort/panic-during-drop pathologies.</p>
1.3 Explicit release</h3>
If you need to release a guard earlier than end-of-scope, call drop(x)</code>:</p>
let mut</span> guard</span> =</span> mutex</span>.</span>lock</span>()</span>.</span>unwrap</span>();</span></span>
modify_protected_state</span>(</span>&mut *</span>guard);</span></span>
drop</span>(guard);</span>                       // release before the function returns</span></span>
expensive_computation_that_doesnt_need_the_lock</span>();</span></span></code></pre>
Or nest a block:</p>
let</span> result</span> =</span> {</span></span>
    let</span> _guard</span> =</span> mutex</span>.</span>lock</span>()</span>.</span>unwrap</span>();</span></span>
    read_protected_state</span>()</span></span>
};</span>                                 // _guard dropped here</span></span>
use</span>(result);</span></span></code></pre>
Both idioms are explicit and legitimate. What you cannot</strong> do is "forget" to drop - the compiler will drop at scope exit whether you want it to or not, which is the whole point.</p>

2. What makes a type a "guard"</h2>
Any type with a Drop</code> impl that releases a resource is a guard. The Rust ecosystem is full of them:</p>
Type</th> Resource it guards</th> Who releases on drop</th></tr></thead>

std::sync::MutexGuard<'_, T></code></td> an acquired Mutex</code> lock</td> releases the lock</td></tr>
tokio::sync::SemaphorePermit<'_></code></td> a semaphore slot</td> releases one permit</td></tr>
tempfile::TempDir</code></td> an on-disk temp directory</td> deletes the directory</td></tr>
std::fs::File</code></td> an OS file descriptor</td> closes the fd</td></tr>
Box<T></code></td> heap allocation</td> deallocates</td></tr>
Vec<T></code></td> heap buffer + len</td> deallocates buffer, drops elements</td></tr>
A custom struct</code> with manual impl Drop</code></td> whatever you coded</td> whatever you coded</td></tr>
</tbody></table>
Because the resource lifetime is tied to a value's scope, you get deterministic, leak-safe, exception-safe cleanup by construction - without try/finally</code>, without defer</code>, without a garbage collector.</p>

3. Three flavors of the pattern in practice</h2>
These are three examples that came up in real code review comments on a single PR. Each uses the same underlying Rust mechanic; each looked surprising or wrong to a reviewer encountering it in a context they hadn't previously mapped to RAII.</p>
3.1 Semaphore permits as concurrency gates</h3>
join_set</span>.</span>spawn</span>(</span>async move</span> {</span></span>
    let</span> _global_permit</span> =</span> match</span> global_sem</span>.</span>acquire</span>()</span>.</span>await</span> {</span></span>
        Ok</span>(p)</span> =></span> p,</span></span>
        Err</span>(_)</span> =></span> return</span> (rid,</span> Err</span>(</span>sem_closed_error</span>())),</span></span>
    };</span></span>
    let</span> _local_permit</span> =</span> match</span> local_sem</span>.</span>acquire</span>()</span>.</span>await</span> {</span></span>
        Ok</span>(p)</span> =></span> p,</span></span>
        Err</span>(_)</span> =></span> return</span> (rid,</span> Err</span>(</span>sem_closed_error</span>())),</span></span>
    };</span></span>
    let</span> result</span> =</span> do_work</span>()</span>.</span>await</span>;</span></span>
    (rid, result)</span></span>
    // _local_permit dropped here → local slot released</span></span>
    // _global_permit dropped here → global slot released</span></span>
});</span></span></code></pre>
Two caps - a global one enforced across all spawned groups, a local one per group - are implemented as two semaphores. Each task must hold one permit from each to proceed. The permits are bound to _global_permit</code> and _local_permit</code> so they survive until the task finishes, then release on scope exit.</p>
A reviewer on this PR called the pattern "clever." What they likely noticed was that two values appear to be "unused" - nothing reads _global_permit</code> or _local_permit</code> - yet the code depends critically on their existence. The existence</em> of the value is the work; the value itself is never consumed. That is the distinctive shape of an RAII guard.</p>
Two things are worth noting beyond the scope-trick itself:</p>

Acquisition order is consistent</strong>: every task acquires global before local. That is deliberate - it's the standard anti-deadlock discipline for nested locks. Reverse ordering in some paths (acquire local before global on the error branch, say) would let two tasks each hold one and wait on the other.</li>
Release order is LIFO</strong>: _local_permit</code> drops before _global_permit</code>, matching acquisition. No hand-coded drop()</code> calls are needed.</li>
</ul>
3.2 TempDir</code> as a filesystem lifetime anchor</h3>
fn</span> create_test_workspace</span>()</span> -></span> (</span>tempfile</span>::</span>TempDir</span>,</span> Workspace</span>) {</span></span>
    let</span> tmp</span> =</span> tempfile</span>::</span>TempDir</span>::</span>new</span>()</span>.</span>unwrap</span>();</span></span>
    let</span> ws</span> =</span> Workspace</span>::</span>create_at</span>(tmp</span>.</span>path</span>(),</span> ExecutionStrategy</span>::</span>Sequential</span>)</span></span>
        .</span>expect</span>("</span>Failed to create test workspace</span>");</span></span>
    (tmp, ws)</span></span>
}</span></span>
</span>
#[</span>test</span>]</span></span>
fn</span> test_something</span>() {</span></span>
    let</span> (_tempdir,</span> mut</span> workspace)</span> =</span> create_test_workspace</span>();</span></span>
    workspace</span>.</span>set_session</span>("</span>/github</span>",</span> SessionId</span>::</span>new</span>("</span>…</span>"</span>.</span>into</span>()))</span>.</span>unwrap</span>();</span></span>
    workspace</span>.</span>save</span>()</span>.</span>unwrap</span>();</span></span>
    // ...assertions...</span></span>
    // _tempdir dropped here → directory deleted</span></span>
}</span></span></code></pre>
tempfile::TempDir</code> guards a temporary directory on disk. It deletes the directory when it drops. TempDir::path</code> returns a &Path</code> borrow; the workspace likely converts it to an owned PathBuf</code> internally for storage, but it does not own the TempDir</code> itself - so if the TempDir</code> drops mid-test, subsequent workspace.save()</code> will fail because the backing directory is gone.</p>
So the helper returns both</em> - the Workspace</code> you operate on and the TempDir</code> whose scope must outlive it. The caller binds the TempDir</code> to a name. Any name works, but _tempdir</code> is conventional because:</p>

It communicates "this is a lifetime anchor, not something you'll read."</li>
It silences the unused-variable lint without the bare _</code> that would drop it immediately.</li>
</ul>
A reviewer on this PR objected that "the first element of the tuple isn't being used." The literal claim is a misread - _tempdir</code> is</em> used, via its Drop</code> side-effect, which is the point of the binding. But the misread is informative: the pattern's central move (a binding whose value is never read) looks like dead code to readers not tuned to RAII. The cheapest mitigation is naming: _tempdir</code> reads intent better than _tmp</code>.</p>
3.3 MutexGuard</code> for scoped critical sections</h3>
static</span> STATE</span>:</span> Mutex</span><</span>Counters</span>></span> =</span> Mutex</span>::</span>new</span>(</span>Counters</span>::</span>new</span>());</span></span>
</span>
fn</span> observe_and_reset</span>()</span> -></span> Counters</span> {</span></span>
    let mut</span> guard</span> =</span> STATE</span>.</span>lock</span>()</span>.</span>unwrap</span>();</span></span>
    let</span> snapshot</span> =</span> guard</span>.</span>clone</span>();</span></span>
    *</span>guard</span> =</span> Counters</span>::</span>new</span>();</span></span>
    snapshot</span></span>
    // guard dropped here → mutex released</span></span>
}</span></span></code></pre>
MutexGuard</code> is probably the most textbook RAII guard in Rust. Acquired by lock()</code>, released on drop, and Deref</code>s to the protected value. The snapshot</code> returned is derived from the protected state under the lock; the guard releases immediately after the expression snapshot</code> is evaluated, at the end of the function.</p>
If you want to shrink the critical section, nest a block:</p>
fn</span> observe_and_reset</span>()</span> -></span> Counters</span> {</span></span>
    let</span> snapshot</span> =</span> {</span></span>
        let mut</span> guard</span> =</span> STATE</span>.</span>lock</span>()</span>.</span>unwrap</span>();</span></span>
        let</span> s</span> =</span> guard</span>.</span>clone</span>();</span></span>
        *</span>guard</span> =</span> Counters</span>::</span>new</span>();</span></span>
        s</span></span>
    };</span> // guard dropped here</span></span>
    expensive_post_processing</span>(</span>&</span>snapshot);</span></span>
    snapshot</span></span>
}</span></span></code></pre>
Same pattern. The guard anchors the critical section to a lexical region.</p>

4. Why Rust uses this pattern</h2>
Rust deliberately doesn't have try/finally</code>, defer</code>, or runtime-managed cleanup. RAII via Drop</code> is the uniform mechanism, and that is a design decision worth understanding.</p>
4.1 Static, deterministic cleanup</h3>
The compiler knows when every value's scope ends. Drop code is inserted at those points. There is no runtime scheduling, no "when the GC feels like it," no race between cleanup threads. The same source produces the same drop ordering on every run. This means:</p>

Cleanup cost is accounted for at compile time - you know where the drop()</code> calls are even if they're implicit.</li>
Drop order is observable and portable - tests that exercise cleanup side effects are reproducible.</li>
</ul>
4.2 Exception-safety is free</h3>
If a function panics mid-way, stack unwinding drops every value in every stack frame being unwound, in reverse order of creation. A MutexGuard</code> held across the panic point releases the lock during unwind. A TempDir</code> deletes itself. A File</code> closes. Contrast with C++ (where you get RAII in destructors but must combine it with careful exception types) or Go (where a forgotten defer</code> leaks silently).</p>
There is no path through a Rust function, however exceptional, that skips Drop. The exceptions are all explicit and named:</p>

std::process::abort()</code> - terminates without unwinding.</li>
std::mem::forget()</code> and ManuallyDrop</code> - opt out of running Drop</code> for a specific value.</li>
Box::leak</code> / Vec::leak</code> / String::leak</code> - intentionally turn an owned value into a 'static</code> reference, leaking the allocation.</li>
A Drop</code> impl that itself panics during unwinding - aborts the process.</li>
Reference cycles via Rc</code> / Arc</code></strong> - if two Rc</code>s reference each other, neither's strong count ever reaches zero, so neither value is dropped. This is memory-safe (no UB, as mem::forget</code> is also memory-safe) but it is the most common "my Drop</code> never ran" footgun in real code. The standard remedy is Weak</code> for the back-edge.</li>
</ul>
4.3 Coupling lifetime to semantic</em> scope, not to control flow</h3>
The shape of the scope - function body, block, match arm - becomes the shape of the resource's lifetime. You don't have to hand-thread release calls through every early return, every error branch, every loop break. The compiler does it. That removes a whole class of bugs:</p>

"forgot to unlock on the error path" - impossible; the guard drops on unwind.</li>
"released the permit twice" - can't; you can only drop an owned value once.</li>
"used after release" - caught at compile time; the borrow checker rejects uses after drop(guard)</code> or after scope exit.</li>
"resource leaked because of an early return" - the return point runs the implicit drops.</li>
</ul>
4.4 Composable</h3>
A struct that owns a guard inherits the guard's behavior. If MyService</code> holds a MutexGuard<'_, State></code>, dropping MyService</code> releases the lock. You build larger transactional units by composition, and Rust's drop ordering gives you deterministic control - but note that the rule for struct fields</strong> differs from the rule for local let</code> bindings</strong>:</p>

Locals in a block drop in reverse declaration</strong> order (LIFO), as shown in §1.2.</li>
Struct fields drop in declaration order</strong> (top to bottom).</li>
Tuple and array elements likewise drop in declaration / index order.</li>
</ul>
So to release the lock last</em> (after the audit log is finalized and pending entries are released), the lock field must be declared last</em>:</p>
struct</span> Transaction</span><'</span>a</span>> {</span></span>
    pending</span>:</span> Vec</span><</span>Entry</span>>,</span></span>
    _log</span>:</span> AuditLog</span>,</span></span>
    _lock</span>:</span> MutexGuard</span><'</span>a</span>,</span> Bank</span>>,</span></span>
}</span></span>
// Fields drop in declaration order:</span></span>
//   1. pending drops - entries released</span></span>
//   2. _log drops    - audit entry finalized</span></span>
//   3. _lock drops   - bank unlocked (released last, as intended)</span></span>
// To change the order, reorder the fields.</span></span></code></pre>
If a struct itself has a manual impl Drop</code>, the compiler runs that drop</code> body first, then drops the fields in declaration order.</p>
4.5 Tooling recognizes the pattern</h3>
Clippy and rustc have lints specifically for drop-guard misuse:</p>

#[must_use]</code> on MutexGuard</code> / SemaphorePermit</code> / TempDir</code> makes rustc warn when the value is dropped as a bare expression statement</em> (e.g., mutex.lock();</code> with no binding at all). Note: it does not</strong> fire for let _ = mutex.lock();</code> - the underscore pattern counts as a use.</li>
let_underscore_lock</code> (clippy) covers exactly that gap - it warns on let _ = mutex.lock();</code> because the bare _</code> pattern drops the guard immediately, almost always a bug.</li>
let_underscore_must_use</code> (clippy) is the more general form: warns when let _</code> discards any #[must_use]</code> value.</li>
used_underscore_binding</code> (clippy) warns if a _name</code> binding is actually read (reasonably - _name</code> signals intent-not-to-read).</li>
</ul>
The ecosystem is aware of the pattern and the failure modes adjacent to it.</p>

5. Benefits, restated as a checklist</h2>
When you reach for an RAII guard over an explicit acquire/release pair, you get:</p>

Cleanup on every path, including panics.</strong> No try/finally</code>.</li>
One acquisition site, one name, one scope.</strong> No "did I call release on every branch?"</li>
Static drop-order guarantees.</strong> No runtime reordering; no surprises.</li>
Composable resource ownership.</strong> Guards nest into structs, get returned from functions, and still respect their scope. (Caveat for async: a std::sync::MutexGuard</code> is !Send</code> and cannot be held across an .await</code> in a Send</code> future. Even when the type system permits it, holding a sync mutex across .await</code> is almost always a bug - it can stall the runtime. Clippy's await_holding_lock</code> flags this. Use tokio::sync::Mutex</code> if a guard genuinely needs to live across an await point.)</li>
Lint-enforced correctness.</strong> The compiler and clippy catch the common mistakes.</li>
Self-documenting lifetime.</strong> The region where the resource is held is visible as a block or a function body - no reader has to trace control flow to find the release.</li>
</ol>
The cost, compared to a "just call release()</code> manually" approach, is essentially zero at runtime and slightly more vocabulary at read time: you must recognize that _guard</code> is a real binding, that Drop runs at the }</code>, and that a bare _</code> is different from _name</code>. Once internalized, the pattern fades into background idiom.</p>

6. Common misreadings</h2>
These are the shapes that trip readers who haven't fully absorbed the pattern. Each has a cheap remedy.</p>
Misreading 1: "This variable is unused."</h3>
let</span> _permit</span> =</span> sem</span>.</span>acquire</span>()</span>.</span>await</span>?</span>;</span></span></code></pre>
The name starts with _</code>, there is no read of _permit</code> anywhere, the linter is silent. To a reader used to scanning for reads, the binding looks dead. They may suggest removing it or changing it to let _ = sem.acquire().await?;</code>. Both changes break the program</strong> - the permit would release immediately.</p>
Remedy:</strong> give the binding a name that telegraphs intent to hold</em>, and/or add a one-line comment the first time the pattern appears in a file.</p>
let</span> _permit</span> =</span> sem</span>.</span>acquire</span>()</span>.</span>await</span>?</span>;</span> // RAII guard – keeps permit alive until end of task</span></span></code></pre>
Or, for strictly lifetime-anchoring values:</p>
let</span> _permit_keep_alive</span> =</span> sem</span>.</span>acquire</span>()</span>.</span>await</span>?</span>;</span></span></code></pre>Misreading 2: "Drop isn't happening where I expect."</h3>
fn</span> work</span>() {</span></span>
    let</span> _guard</span> =</span> mutex</span>.</span>lock</span>()</span>.</span>unwrap</span>();</span></span>
    // ...20 lines...</span></span>
    expensive_pure_computation</span>();</span>   // still holds the mutex!</span></span>
}</span></span></code></pre>
_guard</code> drops at the end of the function, not at the end of the work that actually needs it. A reviewer might assume the mutex is released before expensive_pure_computation</code>; it isn't.</p>
Remedy:</strong> use explicit drop(_guard);</code>, or nest a block to bound the critical section:</p>
fn</span> work</span>() {</span></span>
    {</span></span>
        let</span> _guard</span> =</span> mutex</span>.</span>lock</span>()</span>.</span>unwrap</span>();</span></span>
        protected_step</span>();</span></span>
    }</span></span>
    expensive_pure_computation</span>();</span>   // now runs unlocked</span></span>
}</span></span></code></pre>Misreading 3: "The first tuple element isn't used."</h3>
let</span> (_tempdir, workspace)</span> =</span> create_test_workspace</span>();</span></span></code></pre>
This is misreading 1 in disguise, but dressed up as a tuple destructure. The first element is a TempDir</code> whose Drop</code> impl deletes the on-disk directory. Binding it to _tempdir</code> keeps the directory alive for the test body. Destructuring with let (_, workspace) = …</code> would delete the directory immediately and break every subsequent I/O operation on workspace</code>.</p>
Remedy:</strong> the name. _tempdir</code> reads better than _tmp</code>; a doc comment on the helper that returns the tuple seals the intent.</p>
Misreading 4: "Just use drop()</code> at the right place - guards are magic."</h3>
The concern here is that Drop at scope exit is "implicit" and therefore opaque. In practice the placement is predictable (closing brace of the enclosing block) and tools can show you: rust-analyzer</code>'s "inlay hints" will display drop points; cargo clippy</code> catches the main misuse shapes. You don't need to treat Drop as magic - you need to treat it as a compile-time scheduling rule.</p>

7. When to use the pattern - and when not to</h2>
Use a drop guard when:</p>

You hold a resource whose release is deterministic and tied to a lexical region.</li>
The release is infallible or best-effort (dropping a MutexGuard</code> can't fail meaningfully; deleting a TempDir</code> is best-effort - errors are swallowed).</li>
You want the release to happen on every exit path, including panic, without threading cleanup calls through every branch.</li>
You want the guard to compose into larger owned units (structs, tuples, closures captured by move</code>).</li>
</ul>
Avoid the pattern or supplement it when:</p>

The release is fallible in a way the caller must observe. Drop</code> cannot return errors and cannot be await</code>ed. Flushing a buffered writer, for instance, should usually be explicit (writer.flush()?</code>) with the guard as a safety net for the panic path - not as the primary mechanism. BufWriter</code>'s drop flushes best-effort and ignores errors.</li>
The resource needs async cleanup. Drop</code> is synchronous. For async cleanup, use explicit close().await</code> and let the guard handle only the emergency-panic path. The AsyncDrop</code> RFCs are still in flux.</li>
The scope-exit timing is wrong. If the "natural" scope is larger than the time you want to hold the resource, use drop(x)</code> or a nested block.</li>
</ul>
For ad-hoc "run this on scope exit" needs that don't justify a dedicated type - restoring some thread-local, undoing a temporary state mutation in a test - the scopeguard</code></a> crate provides defer!</code> and defer_on_unwind!</code> macros. They are RAII guards underneath (a generated struct with a Drop</code> impl) and complement, rather than replace, named guard types: reach for defer!</code> when the cleanup is one-off and inline; reach for a named guard when the resource has a real type that consumers should see in signatures.</p>

8. Quick reference</h2>
// Standard: bind, use implicitly via Drop, scope-exit releases.</span></span>
let</span> _permit</span> =</span> sem</span>.</span>acquire</span>()</span>.</span>await</span>?</span>;</span></span>
work</span>()</span>.</span>await</span>;</span></span>
// drop here</span></span>
</span>
// Explicit early release.</span></span>
let</span> permit</span> =</span> sem</span>.</span>acquire</span>()</span>.</span>await</span>?</span>;</span></span>
hot_path</span>()</span>.</span>await</span>;</span></span>
drop</span>(permit);</span></span>
cold_path</span>()</span>.</span>await</span>;</span></span>
</span>
// Nested scope to bound release.</span></span>
let</span> result</span> =</span> {</span></span>
    let</span> _guard</span> =</span> mutex</span>.</span>lock</span>()</span>.</span>unwrap</span>();</span></span>
    compute_under_lock</span>()</span></span>
};</span></span>
// _guard released here</span></span>
use_result</span>(result);</span></span>
</span>
// Tuple-returning helper with an anchor.</span></span>
let</span> (_tempdir, workspace)</span> =</span> make_workspace</span>();</span></span>
// _tempdir lives as long as this frame; don't rebind to `_`.</span></span>
</span>
// WRONG: immediate drop.</span></span>
let</span> _</span> =</span> sem</span>.</span>acquire</span>()</span>.</span>await</span>?</span>;</span>           // permit dropped NOW</span></span>
let</span> _</span> =</span> mutex</span>.</span>lock</span>()</span>.</span>unwrap</span>();</span>          // unlocked NOW</span></span>
let</span> _</span> =</span> TempDir</span>::</span>new</span>()</span>.</span>unwrap</span>();</span>        // directory deleted NOW</span></span></code></pre>

9. Further reading</h2>

Rust reference on drop order: https://doc.rust-lang.org/reference/destructors.html</a></li>
std::mem::drop</code> and destructor semantics: https://doc.rust-lang.org/std/ops/trait.Drop.html</a></li>
Tokio Semaphore</code> - "Using a semaphore as a limiter" example: https://docs.rs/tokio/latest/tokio/sync/struct.Semaphore.html</a></li>
tempfile::TempDir</code> - guarantees and pitfalls: https://docs.rs/tempfile/latest/tempfile/struct.TempDir.html</a></li>
Clippy lint let_underscore_lock</code>: https://rust-lang.github.io/rust-clippy/master/#let_underscore_lock</a></li>
Article: "Using Drop</code> to write idiomatic Rust" by Jon Gjengset and others - covers the pattern under the name "drop guards."</li>
</ul>

Takeaway</h2>
A let _name = value;</code> binding where value</code> has a meaningful Drop</code> is not an "unused variable." It is a lexical declaration of a resource's lifetime.</strong> The value's type - MutexGuard</code>, SemaphorePermit</code>, TempDir</code>, File</code>, custom Drop</code> impl - tells you what's being held. The scope - function body, block, match arm - tells you for how long. The scope's }</code> is the release point.</p>
Once that triad (type, scope, brace) is legible to a reader, the pattern stops being "clever" and becomes background mechanism. Until then, the cheapest thing to do in a codebase is name the bindings well (_tempdir</code>, _permit</code>, _guard</code>) and document the pattern at its first load-bearing use in the file.</p>


Dyn-Compatible Async Traits in Rust: Why the Manual Boxed Future Idiom is Required
2026-04-26T00:00:00+00:00
Pin<Box<dyn Future + Send>></code> in Traits - Why the Manual Desugar?</h1>
Context</h2>
When a Rust trait needs async methods and</strong> must be usable as a trait object (Box<dyn Trait></code>, &dyn Trait</code>, Arc<dyn Trait></code>), you cannot just write async fn</code> and move on. async fn</code> in traits returns an opaque</strong> impl Future</code> whose concrete type differs per implementation - which breaks vtable dispatch. The compiler's own error-recovery hint spells it out:</p>

to make this trait dyn-compatible, use -> Pin<Box<dyn Future<Output = ...> + Send>></code> instead.</p>
</blockquote>
The manual form - write a synchronous fn returning Pin<Box<dyn Future<Output = T> + Send>></code>, implement it with Box::pin(async move { ... })</code> - exists to preserve dyn-compatibility. It is what #[async_trait]</code> generates under the hood. It is what tower::Service</code>, hyper::Service</code>, and many service-oriented abstractions use (sometimes with an associated future type, sometimes with the boxed form). It looks unfamiliar at first; it is mechanically load-bearing.</p>
This doc explains why the pattern exists, what it gives you, and the lifetime subtlety that turns every "clone Arc fields before async move</code>" line in the implementation into a consequence of the trait's signature.</p>

1. The setup: async + polymorphism + pluggable backends</h2>
A common design:</p>

You define a trait that abstracts some capability with async methods - an executor, a service, a storage backend, a message bus.</li>
Production uses one implementation (a real HTTP executor, a real database backend).</li>
Tests use another (a mock that records calls and returns canned responses).</li>
Consumers of the trait want to swap between them at construction time without recompiling.</li>
</ul>
The most natural Rust encoding is:</p>
pub</span> struct</span> Dispatcher</span> {</span></span>
    executor</span>:</span> Box</span><</span>dyn</span> StepExecutor</span>>,</span>   // production or mock, decided at construction</span></span>
}</span></span></code></pre>
For this to compile, StepExecutor</code> must be dyn-compatible</strong> (the compiler's current term for what used to be called "object-safe"). That is: you can build a vtable for it, because every method's signature is known at compile time regardless of the Self</code> type that implements it.</p>
Synchronous methods are trivially dyn-compatible. Async methods are not - and that is where the whole pattern starts.</p>

2. What async fn</code> actually is</h2>
async fn foo(...) -> T { body }</code> is sugar for:</p>
fn</span> foo</span>(</span>...</span>)</span> -></span> impl</span> Future</span><</span>Output</span> =</span> T</span>> {</span> async move</span> { body } }</span></span></code></pre>
The return type is impl Future<Output = T></code> - an anonymous existential type</strong> whose concrete identity is "whatever compiler-generated state machine this particular function body produced." The caller gets something that implements Future</code>, but the caller does not know (and cannot name) the concrete type (that's what existential types are for).</p>
This is excellent for monomorphized, generic code. The compiler specializes each call site against the concrete future type and inlines aggressively.</p>
It is fatal for dyn dispatch.</p>
2.1 Why impl Future</code> and dyn dispatch are incompatible</h3>
A vtable stores function pointers with fixed signatures. For a sync method fn run(&self, x: u32) -> bool</code>, the vtable slot is a pointer to a function taking (&dyn Trait, u32)</code> and returning bool</code>. Every implementation of the trait must produce a function with that exact signature.</p>
For fn run(&self, x: u32) -> impl Future<Output = bool></code>:</p>

Implementation A's impl Future</code> is some compiler-generated Running<A></code> state machine.</li>
Implementation B's impl Future</code> is a different Running<B></code> state machine with a different size, different layout, and different poll</code> code.</li>
They are not the same type</strong>. There is no single function signature the vtable can store.</li>
</ul>
You cannot put Running<A></code> and Running<B></code> behind the same function pointer. Polymorphism through dispatch requires a stable, type-erased return type. impl Future</code> is the opposite of type-erased.</p>
2.2 What the compiler does today (Rust 1.75+)</h3>
You can</em> write async fn</code> in traits. The compiler added that support in Rust 1.75 (late 2023). But the same method on dyn Trait</code> is rejected with an error that explicitly instructs you to switch to the manual form.</p>
Consider this minimal example - a trait with one async fn</code>, then an attempt to use it behind a trait object:</p>
type</span> Result</span><</span>T</span>></span> =</span> std</span>::</span>result</span>::</span>Result</span><</span>T</span>,</span> Box</span><</span>dyn</span> std</span>::</span>error</span>::</span>Error</span>>>;</span></span>
</span>
pub</span> trait</span> StepExecutor</span> {</span></span>
    async fn</span> execute</span>(</span>&</span>self</span>)</span> -></span> Result</span><()>;</span></span>
}</span></span>
</span>
fn</span> build</span>()</span> -></span> Box</span><</span>dyn</span> StepExecutor</span>> {</span> todo!</span>() }</span></span></code></pre>
The trait declaration compiles fine on its own. The line Box<dyn StepExecutor></code> is what trips the dyn-compatibility check, producing:</p>
error[E0038]: the trait `StepExecutor` is not dyn compatible</span></span>
  --> src/lib.rs:10:18</span></span>
   |</span></span>
10 | fn build() -> Box<dyn StepExecutor> { todo!() }</span></span>
   |                  ^^^^^^^^^^^^^^^^^ `StepExecutor` is not dyn compatible</span></span>
   |</span></span>
note: for a trait to be dyn compatible it needs to allow building a vtable</span></span>
help: consider boxing the future:</span></span>
   |</span></span>
-    async fn execute(&self) -> Result<()>;</span></span>
+    fn execute(&self) -> Pin<Box<dyn Future<Output = Result<()>> + Send + '_>>;</span></span></code></pre>
The compiler is telling you the lowered form. Adopting it is the</em> way to keep dyn compatibility.</p>

3. The manual form, line by line</h2>
Here is the paired trait declaration and impl, written the manual way:</p>
// Trait declaration</span></span>
pub</span> trait</span> StepExecutor</span>:</span> Send</span> +</span> Sync</span> {</span></span>
    fn</span> execute_prepared</span>(</span></span>
        &</span>self</span>,</span></span>
        requests</span>:</span> Vec</span><</span>PreparedRequest</span>>,</span></span>
        max_concurrency</span>:</span> usize</span>,</span></span>
    )</span> -></span> Pin</span><</span>Box</span><</span>dyn</span> Future</span><</span>Output</span> =</span> Vec</span><</span>Result</span><</span>ExecutionResult</span>>>></span> +</span> Send</span>>>;</span></span>
}</span></span>
</span>
// Implementation</span></span>
impl</span> StepExecutor</span> for</span> ParallelExecutor</span> {</span></span>
    fn</span> execute_prepared</span>(</span></span>
        &</span>self</span>,</span></span>
        requests</span>:</span> Vec</span><</span>PreparedRequest</span>>,</span></span>
        max_concurrency</span>:</span> usize</span>,</span></span>
    )</span> -></span> Pin</span><</span>Box</span><</span>dyn</span> Future</span><</span>Output</span> =</span> Vec</span><</span>Result</span><</span>ExecutionResult</span>>>></span> +</span> Send</span>>> {</span></span>
        let</span> executor</span> =</span> self</span>.</span>http_executor</span>.</span>clone</span>();</span>     // (1) snapshot fields</span></span>
        let</span> handler</span>  =</span> self</span>.</span>adapter_handler</span>.</span>clone</span>();</span>   //     before the async block</span></span>
</span>
        Box</span>::</span>pin</span>(</span>async move</span> {</span>                          // (2) build the future</span></span>
            let</span> sem</span> =</span> Arc</span>::</span>new</span>(</span>Semaphore</span>::</span>new</span>(max_concurrency</span>.</span>max</span>(</span>1</span>)));</span></span>
            let mut</span> set</span> =</span> JoinSet</span>::</span>new</span>();</span></span>
            for</span> req</span> in</span> requests {</span></span>
                let</span> exec</span> =</span> executor</span>.</span>clone</span>();</span></span>
                let</span> hdl</span>  =</span> handler</span>.</span>clone</span>();</span></span>
                let</span> s</span>    =</span> sem</span>.</span>clone</span>();</span></span>
                set</span>.</span>spawn</span>(</span>async move</span> {</span></span>
                    let</span> _p</span> =</span> s</span>.</span>acquire</span>()</span>.</span>await</span>.</span>ok</span>()</span>?</span>;</span></span>
                    exec</span>.</span>dispatch</span>(req, hdl)</span>.</span>await</span></span>
                });</span></span>
            }</span></span>
            set</span>.</span>join_all</span>()</span>.</span>await</span></span>
        })</span>                                             // (3) return the pinned box</span></span>
    }</span></span>
}</span></span></code></pre>
What each piece does:</p>
(1) Clone fields before async move</code>.</strong> The returned future is Send + 'static</code>. By the default object bounds</strong> rule (Rust Reference, Trait object types</em>), when a dyn Trait</code> appears inside Box<…></code>, Rc<…></code>, or Arc<…></code> without an explicit lifetime, the bound defaults to 'static</code>. So Pin<Box<dyn Future<Output = …> + Send>></code> is shorthand for Pin<Box<dyn Future<Output = …> + Send + 'static>></code>. async move</code> captures everything it references by move. If it captured &self.http_executor</code>, the future would need to outlive self</code>, which means its type would need a lifetime parameter (+ '_</code>). The trait said no such parameter. So the body cannot touch self</code> directly - it must capture owned clones of Arc-wrapped fields.</p>
(2) Box::pin(async move { ... })</code>.</strong> The async move { ... }</code> block produces some compiler-generated future type with the moved-in captures. Box::pin</code> heap-allocates it and pins it - pinning is required because futures may self-reference (an await point can borrow locals that live in the future's state machine), and moving such a future invalidates those borrows. Pinning prevents the move. Once allocated and pinned, we erase the concrete type by coercing to Pin<Box<dyn Future<Output = T> + Send>></code>.</p>
(3) The return type unifies every impl's future.</strong> ParallelExecutor::execute_prepared</code> returns one heap-allocated, pinned future. MockStepExecutor::execute_prepared</code> returns a different heap-allocated, pinned future. To the caller - through dyn StepExecutor</code> - they both look like Pin<Box<dyn Future<Output = ...> + Send>></code>. The vtable stores one function pointer; each impl's pointer builds and returns a different underlying future, but all wearing the same type-erased wrapper.</p>
That is the whole trick. The return type is the lingua franca that makes dispatch possible.</p>

4. Why the .clone()</code> dance is load-bearing, not just style</h2>
The trait signature controls what the returned future may and may not do. Two constraints matter:</p>
4.1 + Send</code></h3>
The future will cross thread boundaries - it will be spawned on a tokio runtime, passed to a JoinSet</code>, select!</code>-ed against other futures, etc. Send</code> is mandatory for that to be sound. Every value captured by the async move</code> must itself be Send</code>. If self.http_executor</code> is Arc<HttpExecutor></code> and HttpExecutor: Send + Sync</code>, then Arc<HttpExecutor>: Send</code>, and cloning it into a local gives you a Send</code> owned handle. If you tried to capture &self.http_executor</code>, you'd capture a &HttpExecutor</code> - which is Send</code> only if HttpExecutor: Sync</code>, and even then you'd tie the future's lifetime to self</code>.</p>
4.2 'static</code> (implicit in the absence of + '_</code>)</h3>
Inside Pin<Box<dyn Future<Output = T> + Send>></code>, the trait-object bound is 'static</code> by default. There is no lifetime parameter on the return type. The future must not contain any borrows that outlive the enclosing function - it must own all its captures.</p>
If you write:</p>
fn</span> execute_prepared</span>(</span>&</span>self</span>,</span> ...</span>)</span> -></span> Pin</span><</span>Box</span><</span>dyn</span> Future</span><</span>Output</span> =</span> T</span>></span> +</span> Send</span>>> {</span></span>
    Box</span>::</span>pin</span>(</span>async move</span> {</span></span>
        do_work</span>(</span>&</span>self</span>.</span>http_executor</span>)</span>.</span>await</span>  // captures &self!</span></span>
    })</span></span>
}</span></span></code></pre>
The compiler rejects this: self</code> has an anonymous lifetime bounded by the call, but the returned future needs 'static</code>. The error will be some variant of "self</code> does not live long enough" or "captured variable cannot escape FnMut</code> closure body" or "argument requires that '1</code> must outlive 'static</code>," depending on the exact shape.</p>
The fix is to replace the borrow with an owned clone:</p>
fn</span> execute_prepared</span>(</span>&</span>self</span>,</span> ...</span>)</span> -></span> Pin</span><</span>Box</span><</span>dyn</span> Future</span><</span>Output</span> =</span> T</span>></span> +</span> Send</span>>> {</span></span>
    let</span> executor</span> =</span> self</span>.</span>http_executor</span>.</span>clone</span>();</span>  // owned Arc, 'static</span></span>
    Box</span>::</span>pin</span>(</span>async move</span> {</span></span>
        do_work</span>(</span>&</span>executor)</span>.</span>await</span></span>
    })</span></span>
}</span></span></code></pre>
This is the same idiom Tokio documentation shows for tokio::spawn</code>, which has the same constraint (Send + 'static</code>). The spawn body clones Arcs before move</code> into the task. Trait-level dyn-safe async works the same way for the same reason.</p>
4.3 If you want to borrow self</code>, say so</h3>
You can write a dyn-safe async trait method that does</em> borrow self</code>, by adding the lifetime:</p>
fn</span> execute_prepared</span><'</span>a</span>>(</span></span>
    &</span>'</span>a</span> self</span>,</span></span>
    ...</span></span>
)</span> -></span> Pin</span><</span>Box</span><</span>dyn</span> Future</span><</span>Output</span> =</span> T</span>></span> +</span> Send</span> +</span> '</span>a</span>>>;</span></span></code></pre>
Now the future is permitted to borrow self</code> for the duration 'a</code>. The cost is that callers cannot store the future beyond the borrow; it cannot be tokio::spawn</code>ed as-is without some form of owned-handle wrapping. Most service-oriented traits choose the 'static</code> flavor (no 'a</code>) precisely so the futures are spawnable; they accept the clone-before-move cost as the price of spawn-ability.</p>

5. #[async_trait]</code> is the same thing, macroed</h2>
The async-trait</code> crate (proc macro) lets you write the sugared form:</p>
#[</span>async_trait</span>]</span></span>
pub</span> trait</span> StepExecutor</span>:</span> Send</span> +</span> Sync</span> {</span></span>
    async fn</span> execute_prepared</span>(</span></span>
        &</span>self</span>,</span></span>
        requests</span>:</span> Vec</span><</span>PreparedRequest</span>>,</span></span>
        max_concurrency</span>:</span> usize</span>,</span></span>
    )</span> -></span> Vec</span><</span>Result</span><</span>ExecutionResult</span>>>;</span></span>
}</span></span></code></pre>
At expansion time, the macro rewrites both the trait and every #[async_trait] impl</code> into the manual form we just showed. The return type becomes Pin<Box<dyn Future<Output = ...> + Send + 'async_trait>></code>, where 'async_trait</code> is a generated lifetime bound to &self</code>. That is the §4.3 borrowing form, not</strong> the 'static</code> form from §3 - the macro lets the future borrow self</code> for the duration of the call, so impls can write self.field.do_work().await</code> without cloning. By default the macro adds + Send</code>; opt out with #[async_trait(?Send)]</code> for futures that don't cross thread boundaries.</p>
That is:</p>

#[async_trait]</code> style and the §4.3 manual form produce equivalent</strong> desugaring; the macro is a purely syntactic shortcut and buys you nothing at runtime.</li>
It is not</strong> equivalent to the §3 'static</code> form. If you want a spawnable, owns-its-data future, the macro alone won't give you that - you still write the clone-before-async move</code> dance inside the impl, just without the outer Pin<Box<…>></code> ceremony.</li>
The cost of the macro is an extra dependency, some compile-time overhead, and a layer of obfuscation when reading expanded diagnostics.</li>
The cost of the manual form is ~5 more lines per method: one fn</code> signature with Pin<Box<…>></code>, one Box::pin(async move { … })</code>, one set of field clones.</li>
</ul>
Choosing between them is largely a judgment call about dependency hygiene and explicitness. For a library with a handful of dyn-safe async methods on one trait, the manual form is often preferable: no proc macro in the dep graph, the reader sees exactly what's happening, and rustc diagnostics are about your real code rather than generated code.</p>
For a codebase with dozens of such traits, #[async_trait]</code> amortizes its dep cost and reduces ceremony. Common Rust advice: prefer the manual form when it's small and contained; prefer #[async_trait]</code> when the volume justifies it.</p>

6. Alternatives and when to reach for them</h2>
The boxed form is not the only way to make async work across trait implementations. It is the most common one when you need dyn Trait</code>. Here are the alternatives worth knowing.</p>
6.1 Associated future type (the "tower" style)</h3>
pub</span> trait</span> Service</span> {</span></span>
    type</span> Response</span>;</span></span>
    type</span> Error</span>;</span></span>
    type</span> Future</span>:</span> Future</span><</span>Output</span> =</span> Result</span><</span>Self</span>::</span>Response</span>,</span> Self</span>::</span>Error</span>>></span> +</span> Send</span>;</span></span>
</span>
    fn</span> call</span>(</span>&mut</span> self</span>, req</span>:</span> Request</span>)</span> -></span> Self</span>::</span>Future</span>;</span></span>
}</span></span></code></pre>
Each implementation names its own future type. No boxing, no allocation per call. The catch: it is not dyn-compatible on its own - to use dyn Service</code>, you typically wrap it with a helper like tower::util::BoxService</code> that boxes the future at the object boundary. tower</code> takes this approach precisely to decouple the trait's abstract shape (zero-cost associated future) from the erasure-at-the-edge concern (box only when you need dyn).</p>
Good choice when you are writing a service that will usually</em> be composed generically and occasionally</em> boxed. Overkill for traits that always want dyn dispatch anyway.</p>
6.2 Native async fn</code> in traits (without dyn</code>)</h3>
If you do not need dyn Trait</code>, post-1.75 you can simply write:</p>
pub</span> trait</span> StepExecutor</span>:</span> Send</span> +</span> Sync</span> {</span></span>
    async fn</span> execute_prepared</span>(</span>&</span>self</span>, requests</span>:</span> Vec</span><</span>PreparedRequest</span>>)</span> -></span> Vec</span><</span>Result</span><()>>;</span></span>
}</span></span></code></pre>
Callers use generics: fn run<E: StepExecutor>(e: E)</code> rather than fn run(e: Box<dyn StepExecutor>)</code>. The compiler monomorphizes, inlines, and produces tight code with no boxed futures.</p>
Downside: you lose type erasure. Everywhere StepExecutor</code> appears in a signature, the concrete impl leaks through as a generic parameter. If you were using dyn</code> specifically to hide the impl from downstream code (test vs production, feature-gated variants), that hiding is gone.</p>
There is a second, more subtle downside - the Send bound problem</strong>. With native async fn</code> in traits, you cannot directly write "the returned future must be Send</code>" in the trait declaration. The desugared impl Future</code> is opaque; there is no straightforward syntax to constrain its auto-traits at the trait-definition site. A consumer that needs to tokio::spawn</code> the future therefore has no way to demand Send</code> from the trait alone. This is exactly why many codebases on Rust 1.75+ still reach for #[async_trait]</code> even when they use generics: the macro's expansion to Pin<Box<dyn Future + Send + 'async_trait>></code> makes Send</code> a contractual part of the trait signature.</p>
The language has partial answers - return-type notation</strong> (where T::method(..): Send</code>, still being stabilized) lets a caller demand Send</code> on a per-method basis at the use site, and the trait-variant</code></a> crate generates a parallel Send</code>-flavored trait from a single declaration - but neither is as ergonomic as the boxed form for the "every future must be Send</code>" case. If your trait is intended for spawning, the boxed dyn</code> form remains the path of least resistance.</p>
6.3 Both, via a helper Boxed<T></code> wrapper</h3>
The pattern tower::util::BoxService</code> uses: a thin wrapper that implements the trait by boxing the associated future at each call. You define the trait with the native/associated form, then provide a Boxed</code> adapter for the erasure case.</p>
More code to maintain, but you get both generic and dyn dispatch from the same abstraction.</p>
6.4 Returning impl Future</code> directly (no dyn, no macro)</h3>
pub</span> trait</span> StepExecutor</span> {</span></span>
    fn</span> execute_prepared</span>(</span>&</span>self</span>, requests</span>:</span> Vec</span><</span>PreparedRequest</span>>)</span></span>
        -></span> impl</span> Future</span><</span>Output</span> =</span> Vec</span><</span>Result</span><()>>></span> +</span> Send</span>;</span></span>
}</span></span></code></pre>
Available since 1.75. Equivalent to async fn</code> in a trait. Same dyn-incompatibility. Same monomorphization behavior.</p>

7. How to read a method written in the manual form</h2>
When you encounter code like this in a codebase:</p>
fn</span> do_thing</span>(</span></span>
    &</span>self</span>,</span></span>
    arg</span>:</span> SomeArg</span>,</span></span>
)</span> -></span> Pin</span><</span>Box</span><</span>dyn</span> Future</span><</span>Output</span> =</span> Result</span><</span>Thing</span>>></span> +</span> Send</span>>> {</span></span>
    let</span> state</span> =</span> self</span>.</span>state</span>.</span>clone</span>();</span></span>
    let</span> client</span> =</span> self</span>.</span>client</span>.</span>clone</span>();</span></span>
</span>
    Box</span>::</span>pin</span>(</span>async move</span> {</span></span>
        let</span> s</span> =</span> state</span>.</span>lock</span>()</span>.</span>unwrap</span>();</span></span>
        client</span>.</span>request</span>(s</span>.</span>derive_key</span>(</span>&</span>arg))</span>.</span>await</span></span>
    })</span></span>
}</span></span></code></pre>
Read it as:</p>

Signature</strong>: "This is async fn do_thing(&self, arg: SomeArg) -> Result<Thing></code>, written in the dyn-compatible desugared form. The returned future is Send + 'static</code> - spawnable, cross-thread-safe, owns its data."</li>
The field clones</strong>: "These are the captures the future needs. They are cloned because the future is 'static</code> and cannot borrow self</code>."</li>
Box::pin(async move { ... })</code></strong>: "This is the function body of the async fn</code>. It allocates one pinned future on the heap and erases its concrete type."</li>
The async block's contents</strong>: the real logic.</li>
</ol>
Once you have done this translation a few times, the extra ceremony recedes into background pattern. The first time, it looks like ritual; the second time, it looks like the compiler speaking through the code.</p>

8. When the pattern is right and when it is not</h2>
Use the manual Pin<Box<dyn Future + Send>></code> form when:</p>

You need a trait object (Box<dyn Trait></code>, &dyn Trait</code>, Arc<dyn Trait></code>) with async methods.</li>
You want to avoid the async-trait</code> proc-macro dependency for a small number of methods.</li>
You want the desugaring explicit in the source so readers can inspect the lifetime and Send</code> bounds directly.</li>
</ul>
Use #[async_trait]</code> when:</p>

You have many async trait methods and the repetition overhead is real.</li>
You want the sugared async fn</code> reading experience across a team that's less practiced in manual futures.</li>
You don't mind one proc-macro dep.</li>
</ul>
Skip the dyn form entirely (use generics + async fn in traits</code>) when:</p>

You never need dyn Trait</code>.</li>
All your trait consumers are generic code that monomorphizes.</li>
You want peak performance - no per-call boxing, no vtable indirection.</li>
</ul>
Use associated futures (type Future: Future<Output = …>;</code>) when:</p>

You are writing a library that wants to support both generic and boxed use without committing to one, at the cost of more scaffolding.</li>
You have performance-critical hot paths where the per-call Box::pin</code> allocation measurably matters.</li>
</ul>

9. Quick reference</h2>
// Dyn-safe async method, manual desugar:</span></span>
fn</span> foo</span>(</span>&</span>self</span>, x</span>:</span> T</span>)</span> -></span> Pin</span><</span>Box</span><</span>dyn</span> Future</span><</span>Output</span> =</span> R</span>></span> +</span> Send</span>>> {</span></span>
    let</span> state</span> =</span> self</span>.</span>state</span>.</span>clone</span>();</span>       // clone captures (no &self in body)</span></span>
    Box</span>::</span>pin</span>(</span>async move</span> {</span></span>
        state</span>.</span>do_work</span>(x)</span>.</span>await</span></span>
    })</span></span>
}</span></span>
</span>
// Dyn-safe async method, borrowing self:</span></span>
fn</span> foo</span><'</span>a</span>>(</span>&</span>'</span>a</span> self</span>, x</span>:</span> T</span>)</span> -></span> Pin</span><</span>Box</span><</span>dyn</span> Future</span><</span>Output</span> =</span> R</span>></span> +</span> Send</span> +</span> '</span>a</span>>> {</span></span>
    Box</span>::</span>pin</span>(</span>async move</span> {</span></span>
        self</span>.</span>state</span>.</span>do_work</span>(x)</span>.</span>await</span>         // can touch self; future tied to 'a</span></span>
    })</span></span>
}</span></span>
</span>
// #[async_trait] equivalent - compiler expands to the dyn-safe form:</span></span>
#[</span>async_trait</span>]</span></span>
trait</span> Foo</span> {</span></span>
    async fn</span> foo</span>(</span>&</span>self</span>, x</span>:</span> T</span>)</span> -></span> R</span>;</span></span>
}</span></span>
</span>
// Native async fn in trait (Rust 1.75+) - works for generics, NOT for dyn:</span></span>
trait</span> Foo</span> {</span></span>
    async fn</span> foo</span>(</span>&</span>self</span>, x</span>:</span> T</span>)</span> -></span> R</span>;</span></span>
}</span></span>
</span>
// Tower-style associated future - no box by default:</span></span>
trait</span> Foo</span> {</span></span>
    type</span> Future</span>:</span> Future</span><</span>Output</span> =</span> R</span>></span> +</span> Send</span>;</span></span>
    fn</span> foo</span>(</span>&</span>self</span>, x</span>:</span> T</span>)</span> -></span> Self</span>::</span>Future</span>;</span></span>
}</span></span></code></pre>

10. Takeaway</h2>
async fn</code> in traits and Box<dyn Trait></code> are two features that Rust individually supports and jointly conflict. Every implementation of an async trait method produces a different anonymous future type; vtables cannot dispatch over anonymous types; therefore dyn-safe async methods must return a concrete, type-erased representation of a future. The only such representation the language offers is Pin<Box<dyn Future<Output = T> + Send>></code> - a pinned, boxed, erased trait object of Future</code>.</p>
Everything else in the manual form is a consequence of that single decision:</p>

The Box::pin(async move { ... })</code> wrap produces the erased value.</li>
The clone-before-move on Arc</code>-wrapped fields is because the future must be 'static</code> (no lifetime parameter on the return type) and therefore cannot capture &self</code>.</li>
The #[async_trait]</code> macro expands to exactly this shape; reading it as generated code makes the behavior predictable.</li>
</ul>
Once the return type is recognized for what it is - the compiler's recommended lowering for "async in a dyn trait" - the rest of the ceremony reads as mechanics, not cleverness.</p>

References</h2>
Crates</h3>

tower</code></a> (repo</a>) - modular service/middleware abstraction built around the Service</code> trait with an associated future type. Source of the "tower style" in §6.1.</li>
tower::util::BoxService</code></a> - the adapter that boxes the future at the dyn boundary, so a tower service can be used behind dyn</code>.</li>
async-trait</code></a> (repo</a>) - the proc macro that expands sugared async fn</code> in traits into the manual Pin<Box<dyn Future + Send>></code> form.</li>
hyper</code></a> and tonic</code></a> - HTTP and gRPC libraries built on top of tower::Service</code>.</li>
</ul>
Language and standard library</h3>

Rust 1.75 release notes</a> - the release that stabilized async fn</code> in traits and -> impl Trait</code> in trait methods (RPITIT).</li>
Announcing async fn</code> and return-position impl Trait</code> in traits</a> - the lang team post explaining the feature, its limitations, and explicitly why it does not work with dyn Trait</code>.</li>
E0038: the trait is not dyn compatible</a> - the error code emitted when a trait cannot be made into a trait object, with the full list of reasons.</li>
Reference: object safety / dyn compatibility</a> - the language reference's definition of which traits can be used as dyn Trait</code>.</li>
std::pin</code></a> - module documentation for Pin</code>, including why self-referential futures need pinning.</li>
std::future::Future</code></a> - the trait being boxed.</li>
</ul>
Background reading</h3>

The Async Rust Book</a> - foundational material on Future</code>, async</code>/await</code>, executors, and pinning.</li>
Tokio tutorial: Spawning</a> - explains the Send + 'static</code> requirement for tokio::spawn</code>, which is the same constraint that drives the clone-before-async move</code> idiom in §4.</li>
</ul>
Dyn-Compatible Async Traits in Rust: Why the Manual Boxed Future Idiom is Required

6. Alternatives and when to reach for them</h2>
The boxed form is not the only way to make async work across trait implementations. It is the most common one when you need `dyn Trait</code>. Here are the alternatives worth knowing.</p>`

References</h2>

Ruminations of a Programmer

Evaluating PBT Frameworks: How Proptest and Hegel Differ in Algebraic Expressivity

Evaluating PBT Frameworks: How Proptest and Hegel Differ in Algebraic Expressivity</h1>

The RAII Drop-Guard Pattern in Rust

The RAII Drop-Guard Pattern in Rust</h1>

1. The Rust mechanics</h2>
There are three syntactic forms people confuse. They behave differently.</p>

3. Three flavors of the pattern in practice</h2>
These are three examples that came up in real code review comments on a single PR. Each uses the same underlying Rust mechanic; each looked surprising or wrong to a reviewer encountering it in a context they hadn't previously mapped to RAII.</p>

4. Why Rust uses this pattern</h2>
Rust deliberately doesn't have `try/finally</code>, defer</code>, or runtime-managed cleanup. RAII via Drop</code> is the uniform mechanism, and that is a design decision worth understanding.</p>`

6. Common misreadings</h2>
These are the shapes that trip readers who haven't fully absorbed the pattern. Each has a cheap remedy.</p>

Ruminations of a Programmer

Evaluating PBT Frameworks: How Proptest and Hegel Differ in Algebraic Expressivity

Evaluating PBT Frameworks: How Proptest and Hegel Differ in Algebraic Expressivity</h1>

The RAII Drop-Guard Pattern in Rust

The RAII Drop-Guard Pattern in Rust</h1>

1. The Rust mechanics</h2> There are three syntactic forms people confuse. They behave differently.</p>

3. Three flavors of the pattern in practice</h2> These are three examples that came up in real code review comments on a single PR. Each uses the same underlying Rust mechanic; each looked surprising or wrong to a reviewer encountering it in a context they hadn't previously mapped to RAII.</p>

4. Why Rust uses this pattern</h2> Rust deliberately doesn't have try/finally</code>, defer</code>, or runtime-managed cleanup. RAII via Drop</code> is the uniform mechanism, and that is a design decision worth understanding.</p>

6. Common misreadings</h2> These are the shapes that trip readers who haven't fully absorbed the pattern. Each has a cheap remedy.</p>

Dyn-Compatible Async Traits in Rust: Why the Manual Boxed Future Idiom is Required

6. Alternatives and when to reach for them</h2> The boxed form is not the only way to make async work across trait implementations. It is the most common one when you need dyn Trait</code>. Here are the alternatives worth knowing.</p>

References</h2>

1. The Rust mechanics</h2>
There are three syntactic forms people confuse. They behave differently.</p>

3. Three flavors of the pattern in practice</h2>
These are three examples that came up in real code review comments on a single PR. Each uses the same underlying Rust mechanic; each looked surprising or wrong to a reviewer encountering it in a context they hadn't previously mapped to RAII.</p>

4. Why Rust uses this pattern</h2>
Rust deliberately doesn't have `try/finally</code>, defer</code>, or runtime-managed cleanup. RAII via Drop</code> is the uniform mechanism, and that is a design decision worth understanding.</p>`

6. Common misreadings</h2>
These are the shapes that trip readers who haven't fully absorbed the pattern. Each has a cheap remedy.</p>

6. Alternatives and when to reach for them</h2>
The boxed form is not the only way to make async work across trait implementations. It is the most common one when you need `dyn Trait</code>. Here are the alternatives worth knowing.</p>`
