Skip to content

po4yka/rust-skills / skills/rust-callback-bounds

rust-callback-bounds

Verified

Use when choosing or repairing the bound on a callback parameter or a stored callable — Fn(&T) -> K, a for<'a> HRTB, a sort_by_key key projection, or a struct field that holds a closure (generic F, Box<dyn Fn>, fn pointer field). Triggers on "lifetime may not live long enough" from a closure, "one type is more general than the other", "borrowed data escapes outside of closure", "callback returns a reference", "store a closure in a struct", "function item types cannot be named directly", E0747, E0562, or "reached the recursion limit while instantiating".

Rust callback bounds

for<'a> FnMut(&'a T) -> &'a K is legal and compiles on stable. Only a separate generic parameter, as in FnMut(&T) -> K, cannot name the higher-ranked lifetime. For a callback that returns a plain borrow of its argument, do not reach for a GAT, a macro crate, or Box<dyn Fn>.

Every quoted diagnostic comes from rustc 1.98.1, edition 2024, on aarch64-apple-darwin.

Route the symptom to a section

Symptom or taskSection
Choosing a bound and nothing has failed yetPick the bound from the return type
error: lifetime may not live long enough, return type of closure is &'2 ...A free type parameter cannot name 'a
Callback must return a borrow of its argumentReturn a borrow of the argument
error[E0521]: borrowed data escapes outside of closurefor<'a> is a no-escape promise
error[E0308]: ... one type is more general than the otherClosure inference is positional
error[E0282]: type annotations needed on a closure argumentClosure inference is positional
E0282 or implementation of AsyncFn is not general enough on |o| async move { .. }Write async |o| ..; see Pick the bound
error[E0309] then error[E0621] then error[E0502] on one functionDo not hoist the lifetime
sort_by_key rejects |o| &o.fieldRead key-projections.md
Callback output is generic over 'a and your signature cannot name itRead key-projections.md
Deciding between F: Fn, Box<dyn Fn>, and fn(..) in a field; error[E0747]: constant provided when a type was expected, or error[E0562]: impl Trait is not allowed in field typesRead storing-callables.md
expected an Fn() closure, found Arc<dyn Fn()>Read storing-callables.md
reached the recursion limit while instantiating on a writer or visitor traitRead storing-callables.md
A move closure unexpectedly implements Fn, captures a whole owner, or changes drop timingRead closure-capture-semantics.md
New E0502, E0505, or E0506 on a closure after a toolchain bump, from match, if let, or letRead closure-capture-semantics.md
The callback is asyncPick the bound: AsyncFn, or a boxed Send future

Pick the bound from the return type

Read the row that matches what the callback returns. The argument is always &T.

The callback returnsWrite this boundAccepts a bare closure
Nothing borrowed, no reference at allimpl Fn(T) -> UYes
One concrete type, named in your signatureimpl Fn(&T) -> StringYes
A free type parameter K of the outer functionimpl Fn(&T) -> KNo for a projection that borrows from the argument. A projection through an inner reference (T = &U) is accepted
A borrow of the argumentimpl for<'a> Fn(&'a T) -> &'a K, plus K: ?SizedYes
A composite over 'a your signature can nameimpl for<'a> FnMut(&'a T) -> Reverse<&'a str>Yes
An output that stays a type parameter over 'aYour own trait with RPITIT, or with a GATNo. Pass a named unit struct
An async result, awaited on the caller's taskimpl AsyncFn(&T) -> R (Rust 1.85+)Yes, as async |o| ... |o| async move { .. } fails, annotated or not (Rust 1.99.1)
A future that must be Send because the task that awaits it is spawned (tokio::spawn), or a callback stored as Box<dyn ..>impl for<'a> Fn(&'a T) -> Pin<Box<dyn Future<Output = R> + Send + 'a>>Yes, when the body is Box::pin(async move { .. })

AsyncFn has no stable way to bound its future as Send, and Box<dyn AsyncFn(&T) -> R> is E0038; a generic field F: AsyncFn(&T) -> R compiles. A future that borrows &T is not 'static, so spawning the callback's own future fails with E0521; take the argument by value or as Arc<T> for that. The rust-async-internals skill, when installed, owns the other async callback rules; for example, a lock held across .await needs tokio::sync::Mutex.

Add K: ?Sized on every -> &'a K row. Without it |o| o.name.as_str() and |b| &b.bytes[..] fail, because str and [u8] are not Sized.

for<'a> is a no-escape promise

for<'a> on a callback bound is machine-checked: the callback cannot store the reference anywhere that outlives the call. E0521 means the caller's closure wants to keep a reference that your API promised it would not keep. Fix the caller, not the bound. Never widen for<'a> to a fixed 'a (impl FnMut(&'a T) -> K with arr: &'a [T]): when the body does not mutate the collection, it compiles and silently permits the store from then on. Read hrtb-diagnostics.md when you need the side-by-side example and the full E0521 text.

E0521 also fires for 'static escapes out of thread::spawn. That variant is a different cause with a different fix; see the rust-compiler-errors skill.

Verify

A bound error appears at the call site, not in your signature. cargo check on the library alone proves nothing about the closures callers write.

ClaimCheck
The bound accepts the closures callers writeA caller test or doctest that passes inline, unannotated closures: |o| &o.field, |o| o.name.as_str(), and one that captures a local. Run cargo test
The API promises no escapeA compile_fail doctest whose closure stores the argument in an outer variable (E0521); a widened 'a makes it compile and fail. Stable rustdoc ignores the error code, so pair it with a passing doctest that differs only in the store line
A size or allocation claim for a stored callableA size_of assertion, or the size and counting-allocator probes in storing-callables.md
A writer or visitor trait that takes impl TraitA test that calls the method with a concrete writer (t.ser(Vec::new())), then cargo test or cargo build --all-targets. A library-only cargo build, cargo check, and cargo clippy miss the recursion-limit error
The MSRV accepts the syntaxcargo +<msrv> check when rust-version is below 1.85 (AsyncFn, async |..|) or 1.87 (use<..> in a trait)

Checklist

  • No 'a was hoisted onto the function, and no for<'a> was widened, to silence a closure error.
  • sort_by, iter().max_by_key, or Vec<&T> was considered before any projection trait.
  • A public generic type that stores behaviour declares its own trait with a blanket FnOnce impl. No public struct hands users a value through -> S<impl Fn(..)>.
  • Every Verify row the change touches passed.

A free type parameter cannot name 'a

impl FnMut(&T) -> K desugars to for<'a> FnMut(&'a T) -> K. The binder introduces 'a, but K was fixed at the outer function's scope, before 'a existed. No closure that returns a borrow of its argument can satisfy it.

std has the same shape. Vec::sort_by_key is FnMut(&T) -> K, so v.sort_by_key(|o| &o.country) reports the same error. No annotation on the closure repairs it. The bound is wrong, not the closure. Read hrtb-diagnostics.md when you need the failing code and the full diagnostic.

Do not hoist the lifetime

Hoist 'a into impl FnMut(&'a T) -> K and rustc reports E0309 (add T: 'a), E0621 (add arr: &'a mut [T]), and E0502. Each help: is locally correct; follow both and E0502 remains, because a fixed 'a keeps every element borrowed past the loop body. Stop at the first error, restore the elided argument, and pick a row from the decision table. Read hrtb-diagnostics.md when you need the terminal code and the three diagnostics.

Return a borrow of the argument

Put the output inside the binder: mut key: impl for<'a> FnMut(&'a T) -> &'a K with K: Ord + ?Sized. The bound accepts an unannotated closure such as |o| &o.country. The &mut [T] receiver stays mutable inside the body, because the higher-ranked 'a ends at each call and no borrow of an element survives to block arr.swap. Read hrtb-diagnostics.md when you need a complete function and caller, or a second reference argument.

Write the binder explicitly when the callback takes two references: elision refuses that with error[E0106].

Closure inference is positional

A reference-projecting closure must be written inline at the call site. Bind the identical text to a let first (let g = |o: &Order| &o.country; register(g);) and it stops satisfying the identical bound: lifetime may not live long enough on the let, then error[E0308]: ... one type is more general than the other on the call. The call site supplies a higher-ranked expectation; a bare let supplies none. Annotate the let (let g: fn(&Order) -> &String = |o| &o.country; for a closure that captures nothing, &dyn for<'a> Fn(&'a Order) -> &'a String for a capturing one), or route it through one generic identity function for the whole crate:

fn hrtb_ref<In, Out: ?Sized, F>(f: F) -> F
where
    F: for<'a> FnMut(&'a In) -> &'a Out,
{
    f
}

struct Order { country: String }
fn register<F: for<'a> FnMut(&'a Order) -> &'a String>(_f: F) {}

fn main() {
    let g = hrtb_ref::<Order, String, _>(|o| &o.country);
    register(g);
}

Do not add a macro crate for this, and do not write a per-type force_hrtb. The turbofish is needed only when the surrounding call leaves In or Out ambiguous.

Only an Fn, FnMut, or FnOnce obligation supplies the expectation. With the bound on your own trait (where for<'a> F: MyTrait<&'a T>), every closure form fails, annotated or not. Pass a named fn, whose item type is already higher-ranked, or wrap the closure in hrtb_ref(..). Read hrtb-diagnostics.md when you need the worked examples and the full diagnostics.

Related skills

When installed: rust-discipline reviews stored callbacks (Box<dyn Fn> over Box<dyn FnMut>, &'a mut fields), rust-compiler-errors owns general E0521 and E0277 triage, rust-iterator-impl owns lending iterators, and rust-performance measures the build cost of a by-value impl Trait (cargo build --timings).

slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall