po4yka/rust-skills / skills/rust-variance
rust-variance
VerifiedUse 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 task | Section |
|---|---|
The variance of a type you own; mutable references are invariant; an invariant type that accepts a shorter lifetime through dyn or an unsize | Settle it with a probe |
note: the struct X<T> is invariant over the parameter T | The variance table |
A raw-pointer deref returns &'a T with no 'a in the inputs, or raw pointer casts of trait objects cannot extend lifetimes | Unbounded lifetimes |
A Sender, handle, or queue refuses to coerce | Coerce the message |
You add Cell, RefCell, or Mutex to a published struct | Variance is public API |
E0597 at resize_with, map, or a callback argument, with the 'static note on a trait bound | Traits match by equality |
error[E0106]: missing lifetime specifier on fn() -> &str | Three fixes |
lifetime may not live long enough on a Box<dyn Fn(&'a T)> field | A free lifetime in dyn Trait |
type annotation requires that ... is borrowed for 'static at a &mut argument | A &mut parameter |
| Scripted probes, every exact note, a rejected and repaired pair, or the unsound channel | Read 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
cov | con | Verdict |
|---|---|---|
| compiles | rejected | covariant in T |
| rejected | compiles | contravariant in T |
| rejected | rejected | invariant 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
| Constructor | Variance in T | Variance in 'a |
|---|---|---|
&'a T | covariant | covariant |
&'a mut T | invariant | covariant |
*const T, fn() -> T, Box<T>, Vec<T>, Rc<T>, Arc<T>, Option<T>, [T; N], (T, U) | covariant | — |
*mut T | invariant | — |
fn(T) | contravariant | — |
fn(T) -> T | invariant | — |
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> | covariant | covariant |
PhantomData<fn(T)> | contravariant | — |
PhantomData<*mut T>, PhantomData<Cell<T>>, PhantomData<&'a mut T> | invariant | covariant |
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 afn() -> Tfield next to afn(T)field. - Everything built on
UnsafeCell<T>is invariant inT, because a shared reference to it permits a write:Cell,RefCell,Mutex,RwLock,AtomicPtr, and everystdchannel.
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.
- 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; overunsafecode the same signature is the unbounded-lifetime hazard. - Wrap the call,
|| static_name(), when the producer is in another crate. Inference gives the fresh closure the shortOutput. - Coerce to a function pointer:
let f: fn() -> &'static str = static_name;.fnpointers are covariant in the return type;fnitems are not. Write the lifetime out:fn() -> &strgiveserror[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.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 198k | Updated | Claude CodeCodex | Verified | Install |
| 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: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| 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: 194k | Updated | Claude CodeCodex | Verified | Install |