Skip to content

po4yka/rust-skills / skills/rust-variance

rust-variance

Verified

Use when a lifetime coercion is refused ("is invariant over the parameter", "borrowed for 'static", "lifetime may not live long enough" on a return or argument), when deciding whether a type is covariant, contravariant, or invariant, or when adding a lifetime parameter, a PhantomData variance marker, or interior mutability to a public type. Also for subtyping of a fn item that fails a trait bound (resize_with), dyn Fn lifetime parameters, and an unbounded lifetime from a raw pointer. Triggers on "phantomdata variance", "&mut is invariant", "sender is invariant".

Rust variance

Does a value that holds 'b fit where the compiler asks for 'a, given 'b: 'a? The type constructor around the lifetime decides. A trait bound matches by equality, so nothing coerces through it.

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

Route the symptom to a section

Symptom or taskSection
The variance of a type you own; mutable references are invariant; an invariant type that accepts a shorter lifetime through dyn or an unsizeSettle it with a probe
note: the struct X<T> is invariant over the parameter TThe variance table
A raw-pointer deref returns &'a T with no 'a in the inputs, or raw pointer casts of trait objects cannot extend lifetimesUnbounded lifetimes
A Sender, handle, or queue refuses to coerceCoerce the message
You add Cell, RefCell, or Mutex to a published structVariance is public API
E0597 at resize_with, map, or a callback argument, with the 'static note on a trait boundTraits match by equality
error[E0106]: missing lifetime specifier on fn() -> &strThree fixes
lifetime may not live long enough on a Box<dyn Fn(&'a T)> fieldA free lifetime in dyn Trait
type annotation requires that ... is borrowed for 'static at a &mut argumentA &mut parameter
Scripted probes, every exact note, a rejected and repaired pair, or the unsound channelRead references/variance-tables.md

Settle it with a probe

Do not reason about variance. Compile these three functions and read the result.

// probe.rs — replace `C` with the type under test, `S` with a type that has a lifetime.
fn cov<'a, 'b: 'a>(x: C<&'b u8>) -> C<&'a u8> { x }   // compiles => covariant in T
fn con<'a, 'b: 'a>(x: C<&'a u8>) -> C<&'b u8> { x }   // compiles => contravariant in T
fn cov_lt<'a, 'b: 'a>(x: S<'b>) -> S<'a> { x }        // compiles => covariant in 'a

Run one command with a real output path. Never pass -o /dev/null: as root, rustc replaces the device with a regular file and exits 0.

rustc --edition 2024 --crate-type lib --emit=metadata probe.rs -o probe.rmeta
covconVerdict
compilesrejectedcovariant in T
rejectedcompilescontravariant in T
rejectedrejectedinvariant in T

Vec<T> passes cov. fn(T) passes con. Cell<T> fails both, and rustc names the rule: the struct `Cell<T>` is invariant over the parameter `T` . Read references/worked-examples.md when you need a cited program or diagnostic in full.

Two traps make a probe lie. Never put 'static in the outer position: &'static mut &'b u8 forces 'b: 'static; use a fresh 'x. Never let a probe unsize-coerce: a std pointer or cell that holds dyn Trait + 'b shortens even when invariant, so wrap it in Vec<...>. Read references/variance-tables.md for both traps and the per-version unsize table.

The variance table

ConstructorVariance in TVariance in 'a
&'a Tcovariantcovariant
&'a mut Tinvariantcovariant
*const T, fn() -> T, Box<T>, Vec<T>, Rc<T>, Arc<T>, Option<T>, [T; N], (T, U)covariant—
*mut Tinvariant—
fn(T)contravariant—
fn(T) -> Tinvariant—
Cell<T>, UnsafeCell<T>, RefCell<T>, Mutex<T>, RwLock<T>, mpsc::Sender<T>invariant—
dyn Trait + 'a—covariant
dyn Fn(&'a T), dyn Fn() -> &'a T with a free 'a—invariant
PhantomData<T>, PhantomData<&'a T>, PhantomData<fn() -> T>covariantcovariant
PhantomData<fn(T)>contravariant—
PhantomData<*mut T>, PhantomData<Cell<T>>, PhantomData<&'a mut T>invariantcovariant

Two rules generate the whole table:

  • A struct or enum computes variance per parameter from its fields. Uses of different variances make the parameter invariant: one Cell<T> field, or a fn() -> T field next to a fn(T) field.
  • Everything built on UnsafeCell<T> is invariant in T, because a shared reference to it permits a write: Cell, RefCell, Mutex, RwLock, AtomicPtr, and every std channel.

A parameter that no field stores needs a PhantomData that states the intent: PhantomData<&'a T> to borrow, PhantomData<T> to own, PhantomData<fn(T)> for contravariance, PhantomData<*mut T> or PhantomData<Cell<T>> for invariance. PhantomData<fn(T)> is sound only for a type that never stores or drops a T. PhantomData<fn(T) -> T> gives invariance and keeps Send and Sync; PhantomData<*mut T> removes both. Read the PhantomData table in references/variance-tables.md when the auto traits matter.

Unbounded lifetimes come from a raw pointer

An output lifetime that appears in no input is unbounded: every call site picks its own. A raw-pointer deref is the usual source: unsafe fn deref_unbounded<'a, T>(p: *const T) -> &'a T compiles, lets the result outlive its owner, and Miri reports a use-after-free. So do <*const T>::as_ref, <*mut T>::as_mut, NonNull::as_ref and as_mut, as_ref_unchecked and as_mut_unchecked (stable since 1.95), slice::from_raw_parts, and CStr::from_ptr.

Borrowing the pointer variable proves that the pointer is alive, not its pointee. Tie the output to the actual owner (&self on a wrapper that owns the pointer), or return a guard that keeps the allocation alive. An unsafe constructor must state and enforce the pointee-validity contract. Run cargo +nightly miri test --locked on every path that turns a raw pointer into a reference when nightly Miri is installed; without it, report that path as not checked by Miri.

Since Rust 1.94 a raw-pointer cast cannot extend the lifetime bound of a trait object (note: raw pointer casts of trait objects cannot extend lifetimes). Keep 'a in the stored type. Read references/variance-tables.md when you need the exact-owner accessor, or before a transmute that erases the bound: it gives the two facts the SAFETY comment must state.

Coerce the message, not the handle

std::sync::mpsc::Sender<T> is invariant in T, so the first call site that demands 'static pins the whole channel, and every borrowed source fails with E0597. The message stays covariant: write each consumer as Sender<Message<'_>>, never Sender<Message<'static>>, and coerce at the send site. When a consumer moves the sender into thread::spawn, make the element type own its data; no variance trick helps.

Never repair this with a hand-rolled handle whose only mention of T is PhantomData<fn(T)>. It coerces to Sender<Message<'static>>, escapes with short-lived values still queued, and drops them after the borrow ends: a use-after-free under Miri. Read references/variance-tables.md when you need the rejected and repaired pair, or the unsound channel and its Miri output.

Variance is public API

Wrapping a field in Cell, RefCell, Mutex, RwLock, or any UnsafeCell flips the struct from covariant to invariant, and downstream code that shortened the lifetime stops compiling. Treat it as a breaking change and record it in the changelog. A *mut &'a T field breaks the same coercion; a *mut T field does not. A Box<dyn Fn(&'a T)> field in place of fn(&'a T) makes the struct invariant over 'a. A &'a mut T field breaks only a type coercion. Code that shortens a lifetime through a &mut unsize coercion inside Cell, RefCell, or UnsafeCell needs rust-version = "1.98"; run cargo +<msrv> check when the MSRV is lower.

Lock the variance of each public type with a lifetime parameter, so cargo check fails before a downstream crate does. Keep the covariant probe as a private function whose name starts with _: fn _config_is_covariant<'a, 'b: 'a>(c: ConfigV1<'b>) -> ConfigV1<'a> { c }. To lock intended invariance, put a compile_fail doctest on the public type and run cargo test --doc. It passes on any compile error, a wrong import path included, so keep a compiling twin with the same import.

Traits match their parameters by equality

A trait bound is an equality constraint, not a subtyping constraint. F: FnMut() -> &'a str is satisfied only by a callable whose Output is &'a str. A named function has its own item type, whose Fn impl fixes Output = &'static str, so names.resize_with(10, service_name) on a Vec<&str> that holds a local borrow fails with E0597. Read the note:: it points at the bound that made the demand, not at the caller. A trait of your own behaves the same: S: Sink<&'static u8> is not S: Sink<&'a u8>.

Three fixes for a producer whose output lives too long

Prefer fix 1.

  1. Give the producer an unbounded output lifetime, fn any_name<'a>() -> &'a str, whenever you own it. In safe code the compiler checks the body for every 'a; over unsafe code the same signature is the unbounded-lifetime hazard.
  2. Wrap the call, || static_name(), when the producer is in another crate. Inference gives the fresh closure the short Output.
  3. Coerce to a function pointer: let f: fn() -> &'static str = static_name;. fn pointers are covariant in the return type; fn items are not. Write the lifetime out: fn() -> &str gives error[E0106]: missing lifetime specifier.

A free lifetime in dyn Trait makes it invariant

A lifetime written inside a trait object's parameters matches by equality, so Box<dyn Fn(&Event<'a>)> makes a struct invariant in 'a, where a fn(&Event<'a>) field kept it contravariant. Keep the object higher-ranked: Box<dyn for<'x> Fn(&Event<'x>)>, which elision inside dyn Fn(&Event) also produces, drops the struct's lifetime parameter and serves every caller. Write a free lifetime into a trait object's parameters only when you intend invariance.

A &mut parameter pins the caller's lifetime

fn push_str_ref<'a>(v: &mut Vec<&'a str>, s: &'a str) on a Vec<&'static str> local gives E0597 at the annotation. Drop the 'static from it, or take the container by value and return it (fn with_str_ref<'a>(mut v: Vec<&'a str>, s: &'a str) -> Vec<&'a str>) so covariance applies. Prefer the by-value form, or an owned element type, in a public API.

Related skills

When installed: rust-unsafe owns raw-pointer validity, rust-compiler-errors covers E0597, E0521, and E0106 beyond these shapes, rust-callback-bounds picks the callable bound, and rust-send-sync owns the auto-trait half of the PhantomData table.

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