Skip to content

existential-birds/beagle / plugins/beagle-rust/skills/rust-code-review

rust-code-review

Verified

Reviews Rust code for ownership, borrowing, lifetime, error handling, trait design, unsafe usage, and common mistakes. Use when reviewing .rs files, checking borrow checker issues, error handling patterns, or trait implementations. Covers Rust 2024 edition patterns and modern idioms.

references/lifetime-variance.md

View on GitHub
# Lifetime Variance

## Variance Fundamentals

Variance describes when a subtype can substitute for a supertype. A lifetime `'b` is a subtype of `'a` if `'b: 'a` (outlives). There are three kinds:

- **Covariant**: a subtype can substitute freely. `&'a T` is covariant in both `'a` and `T`.
- **Invariant**: must match exactly. `&mut T` is invariant in `T`; `Cell<T>` is invariant in `T`.
- **Contravariant**: flipped relationship. `fn(T)` is contravariant in `T` (a function accepting less-specific args is more useful).

### Quick Reference Table

| Type | Variance in `'a` | Variance in `T` |
|------|-------------------|------------------|
| `&'a T` | covariant | covariant |
| `&'a mut T` | covariant | **invariant** |
| `Cell<T>` / `RefCell<T>` | — | **invariant** |
| `*const T` / `NonNull<T>` | — | covariant |
| `*mut T` | — | **invariant** |
| `fn(T) -> U` | — | **contra** in `T`, covariant in `U` |
| `Box<T>` / `Vec<T>` | — | covariant |
| `UnsafeCell<T>` | — | **invariant** |

## When Variance Causes Bugs

### Invariance Behind `&mut`

**Flag when**: a type uses a single lifetime where two are needed, and one appears behind `&mut`.

```rust
// BAD — single lifetime forces invariance, won't compile
struct MutStr<'a> {
    s: &'a mut &'a str,
}

// GOOD — two lifetimes decouple the mutable borrow from the inner reference
struct MutStr<'a, 'b> {
    s: &'a mut &'b str,
}
```

With one lifetime, the compiler cannot shorten the mutable borrow independently of the inner `&str` because `&mut T` is invariant in `T`. Two lifetimes let the outer borrow end while the inner `&str` lifetime remains `'static`.

### `Cell<&'a T>` Is Invariant

**Flag when**: `Cell` or `RefCell` wraps a reference and code assumes lifetime covariance.

```rust
// This won't compile — Cell<&'a T> is invariant in 'a
fn bad<'a>(cell: &Cell<&'a str>) {
    let local = String::from("temp");
    cell.set(&local); // would allow dangling ref if covariant
}
```

Invariance is correct here: if `Cell<&'a str>` were covariant, you could store a short-lived reference that outlives its source.

## Memory Regions and Lifetime Implications

- **Stack**: references to stack frames cannot outlive the frame. Check that returned references don't point to locals.
- **Heap** (`Box`, `Arc`): lifetime is unconstrained until deallocation. `Box::leak` produces `&'static`.
- **Static memory**: `'static` references to `static` variables or string literals are always valid.

**Check for**: `'static` bounds on type parameters (e.g., `T: 'static`) — this means `T` must be owned or itself `'static`, not that it lives forever. Common in `thread::spawn` and `tokio::spawn` closures.

## Lifetime Annotation Review Rules

### Flag When

- **Unnecessary `'static` on parameters**: `fn process(name: &'static str)` when `&str` suffices. This forces callers to provide only compile-time strings or leaked allocations.
- **Missing multiple lifetimes**: a struct holds references to two independent sources but uses one lifetime, causing invariance-related compilation failures or overly restrictive APIs.
- **Lifetime on return but not needed**: functions returning owned data (`String`, `Vec<T>`) that carry a phantom lifetime parameter.
- **Single lifetime on iterator types**: types like `StrSplit` that yield references from one field but borrow a different field need separate lifetimes so the yielded reference isn't tied to the shorter-lived field.

### Valid Patterns

- **Elided lifetimes**: when the three elision rules apply, explicit annotations are noise. Don't flag missing annotations when elision handles it.
- **`'a` on `&self` returns**: rule 3 of elision assigns `self`'s lifetime to outputs. Explicit annotation is optional.
- **`'static` for `thread::spawn` and `tokio::spawn`**: required by the API, not a code smell.
- **`'static` trait bounds**: `T: 'static` on generic parameters is standard for owned, self-sufficient types.

## Common Mistakes

### Conflating `'static` with "lives forever"

`T: 'static` means `T` contains no non-static borrows. An owned `String` is `'static`. This is a bound, not a lifetime annotation on a reference.

### Ignoring Drop's interaction with lifetimes

If a type implements `Drop` and is generic over `'a`, dropping counts as a use of `'a`. Code that shortens borrows before the drop site may fail to compile.

```rust
// If Wrapper<'a> implements Drop, this won't compile:
let mut x = 42;
let w = Wrapper(&mut x);
x = 0; // x is still mutably borrowed because w.drop() might use it
```

**Check for**: types with `Drop` that hold references — the borrow extends to the drop point, not the last explicit use.

### **Edition 2024**: RPIT captures all lifetimes by default

In edition 2024, `-> impl Trait` captures all in-scope lifetime parameters. Use `+ use<'a>` to narrow capture when the return value doesn't actually borrow all parameters.

## Review Questions

1. Does the type need multiple lifetime parameters, or does a single lifetime cause invariance issues?
2. Are `'static` annotations on parameters genuinely required, or would an elided lifetime work?
3. Do types implementing `Drop` account for the extended borrow at the drop site?
4. Are `Cell`/`RefCell` wrapping references with correct variance expectations?
5. **Edition 2024**: Do RPIT return types need `+ use<...>` to avoid capturing unrelated lifetimes?
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 322kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 197kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 197kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 197kUpdated Claude CodeCodexVerifiedInstall