Borrow-Check on Opensource internals

Two-Phase Borrows Are Just Dominator Queries: How `v.push(v.len())` Compiles

Jay Hubbert — Wed, 21 Oct 2026 10:45:00 +0000

TL;DR: v.push(v.len()) is the canonical example of a two-phase borrow. The obvious implementation is a dataflow analysis that tracks, at every point, whether each mutable borrow is “reserved but not yet active”. rustc does no such analysis. It finds the activation point by looking at the MIR, and then answers “is this borrow active at this location?” with two dominator-tree queries — O(1), no fixpoint, no extra domain.

Two-phase borrows are Rust’s answer to the classic aliasing problem:

 rust
 
 
let mut v = vec![1, 2, 3];
v.push(v.len()); // this compiles!

At the point where push is called, a &mut v must exist (it is the receiver). At the same time, v.len() needs a &v. Both are fine — but only if the &mut v is reserved rather than active while v.len() is evaluated. Two-phase borrows split the mutable borrow into two moments:

reservation: the &mut v is created, but reads of v are still allowed;
activation: the moment the reference is actually used as a mutable reference — in this case, the &mut v argument being passed to push.

The obvious implementation, and its cost

The textbook approach: add a dataflow analysis over a domain of “borrow activation states”, run it to fixpoint over the whole function, and answer “is borrow B active at point P?” from the computed state.

That is a full extra pass over the function body, with its own domain (a bitset over borrow indices), its own convergence cost, and its own memory. For a feature that only matters for a handful of call sites per function.

What rustc does instead

Step one: find the activation syntactically. When the borrow checker walks the MIR and encounters a two-phase borrow statement, it records the reservation and remembers the temporary it was assigned to:

 rust
 
 
// compiler/rustc_borrowck/src/borrow_set.rs:441-473

let idx = if !kind.is_two_phase_borrow() {
 debug!(" -> {:?}", location);
 self.insert_borrow(location, borrow(TwoPhaseActivation::NotTwoPhase))
} else {
 // When we encounter a 2-phase borrow statement, it will always
 // be assigning into a temporary TEMP:
 //
 // TEMP = &foo
 //
 // so extract `temp`.
 let Some(temp) = assigned_place.as_local() else {
 span_bug!(
 self.body.source_info(location).span,
 "expected 2-phase borrow to assign to a local, not `{:?}",
 assigned_place,
 );
 };

 // Consider the borrow not activated to start. When we find an activation, we'll update
 // this field.
 let idx = self.insert_borrow(location, borrow(TwoPhaseActivation::NotActivated));

 // Insert `temp` into the list of pending activations. From
 // now on, we'll be on the lookout for a use of it. Note that
 // we are guaranteed that this use will come after the
 // assignment.
 let prev = self.pending_activations.insert(temp, idx);
 assert_eq!(prev, None, "temporary associated with multiple two phase borrows");

 idx
};

Step two: the activation is the next use of that temporary:

 rust
 
 
// compiler/rustc_borrowck/src/borrow_set.rs:524-569

fn visit_local(&mut self, temp: Local, context: PlaceContext, location: Location) {
 if !context.is_use() {
 return;
 }

 // We found a use of some temporary TMP
 // check whether we (earlier) saw a 2-phase borrow like
 //
 // TMP = &mut place
 let Some(&borrow_index) = self.pending_activations.get(&temp) else {
 return;
 };
 let borrow_data = &mut self.borrows[borrow_index];

 // Watch out: the use of TMP in the borrow itself
 // doesn't count as an activation. =)
 if borrow_data.reserve_location == location
 && context == PlaceContext::MutatingUse(MutatingUseContext::Store)
 {
 return;
 }
 ...
 self.activation_map.entry(location).or_default().push(borrow_index);

 borrow_data.activation_location = TwoPhaseActivation::ActivatedAt(location);
}

No fixpoint, no worklist: a hash map from temporary to pending activation, and the first use of that temporary after the reservation is the activation. The comment “the use of TMP in the borrow itself doesn’t count as an activation” is the one subtlety — the store that creates the borrow is also a use of the temporary.

Step three: the dominator argument

Now the question the checker actually asks at each use site: “is this borrow active here?” — and the answer comes from the dominator tree:

 rust
 
 
// compiler/rustc_borrowck/src/path_utils.rs:60-120

pub(super) fn is_active<'tcx>(
 dominators: &Dominators<BasicBlock>,
 borrow_data: &BorrowData<'tcx>,
 location: Location,
) -> bool {
 debug!("is_active(borrow_data={:?}, location={:?})", borrow_data, location);

 let activation_location = match borrow_data.activation_location {
 // If this is not a 2-phase borrow, it is always active.
 TwoPhaseActivation::NotTwoPhase => return true,
 // And if the unique 2-phase use is not an activation, then it is *never* active.
 TwoPhaseActivation::NotActivated => return false,
 // Otherwise, we derive info from the activation point `loc`:
 TwoPhaseActivation::ActivatedAt(loc) => loc,
 };

 // Otherwise, it is active for every location *except* in between
 // the reservation and the activation:
 //
 // X
 // /
 // R <--+ Except for this
 // / \ | diamond
 // \ / |
 // A <------+
 // |
 // Z
 //
 // Note that we assume that:
 // - the reservation R dominates the activation A
 // - the activation A post-dominates the reservation R (ignoring unwinding edges).
 //
 // This means that there can't be an edge that leaves A and
 // comes back into that diamond unless it passes through R.
 //
 // Suboptimal: In some cases, this code walks the dominator
 // tree twice when it only has to be walked once. I am
 // lazy. -nmatsakis

 // If dominated by the activation A, then it is active. The
 // activation occurs upon entering the point A, so this is
 // also true if location == activation_location.
 if activation_location.dominates(location, dominators) {
 return true;
 }

 // The reservation starts *on exiting* the reservation block,
 // so check if the location is dominated by R.successor. If so,
 // this point falls in between the reservation and location.
 let reserve_location = borrow_data.reserve_location.successor_within_block();
 if reserve_location.dominates(location, dominators) {
 false
 } else {
 // Otherwise, this point is outside the diamond, so
 // consider the borrow active. This could happen for
 // example if the borrow remains active around a loop (in
 // which case it would be active also for the point R,
 // which would generate an error).
 true
 }
}

The diamond diagram is the whole idea. The borrow is inactive only in the region between the reservation and the activation — and that region is exactly characterized by two dominator facts:

the activation dominates the location → the borrow is active;
the reservation’s successor dominates the location → we are in the “between” window → the borrow is inactive;
otherwise → outside the diamond → active.

The soundness argument is in the comment: the reservation dominates the activation, and the activation post-dominates the reservation, so no edge can leave the diamond and come back without passing through the reservation.

And the borrow checker calls it like this:

 rust
 
 
// compiler/rustc_borrowck/src/lib.rs:1324-1329

(Read(kind), BorrowKind::Mut { .. }) => {
 // Reading from mere reservations of mutable-borrows is OK.
 if !is_active(this.dominators(), borrow, location) {
 assert!(borrow.kind.is_two_phase_borrow());
 return ControlFlow::Continue(());
 }

The dominator tree is already computed — mir::basic_blocks::Cache caches it — so this is free.

The cost

Approach	Cost
Dataflow analysis over borrow activation states	One extra fixpoint pass over the body, a domain of `O(#borrows)` bits, per function
Dominator queries	Two `dominates()` calls per borrow use site, O(1) each with the cached tree

And there is a bonus: the dominator formulation gives a much better explanation when the borrow checker does complain. “This borrow is active here because you used v between the reservation and the activation” is a message a human can act on.

The admitted inefficiency in the comment — “this code walks the dominator tree twice when it only has to be walked once. I am lazy. -nmatsakis” — is still vastly cheaper than a dataflow pass.

Where it lives

compiler/rustc_borrowck/src/borrow_set.rs — finding the reservation and the activation.
compiler/rustc_borrowck/src/path_utils.rs — is_active and the dominator argument.
compiler/rustc_borrowck/src/lib.rs — the check itself.
tests/ui/borrowck/two-phase-baseline.rs — the canonical test, including v.push(v.len()).

Takeaway

This is a good example of a feature that looks like it needs a new analysis but does not. The question “is the borrow active here?” has a purely local answer if you frame it in terms of dominance instead of “which side of the activation are we on”. Framing it right turned an O(functions × borrows × points) analysis into two tree queries.

No Queue At All: rustc's Dataflow Engine Uses a Bitset and a Rank

Jay Hubbert — Wed, 21 Oct 2026 10:40:00 +0000

TL;DR: Every dataflow framework has a worklist: a queue of dirty blocks. rustc’s has none. The dirty set is a DenseBitSet indexed by reverse postorder rank, and the algorithm always processes the lowest-numbered dirty rank. When a back edge dirties an earlier block, the cursor rewinds. The result: loop-free MIR is analysed in a single pass, and the “queue” is a bit scan.

Dataflow analysis — liveness, maybe-initialization, borrow kills — is everywhere in a compiler. The textbook implementation is a worklist:

text

while worklist not empty:
 block = worklist.pop()
 new = transfer(block)
 for successor in successors(block):
 if join(successor, new) changed:
 worklist.push(successor)

It is simple, correct, and does a lot of redundant work: a block can be re-evaluated many times, each time re-running the transfer function over its whole body. And it allocates: a VecDeque per analysis, per body.

The algorithm rustc uses instead

 rust
 
 
// compiler/rustc_mir_dataflow/src/framework/mod.rs:307-325

// Forward analyses use a reverse postorder (`rpo`). Every reachable basic block has a
// *rank*: its position within `rpo`. Rank order is dataflow order: for every edge A -> B
// that is not a back edge, rank(A) < rank(B). This is independent of basic block numbering
// (which depends on the vagaries of CFG construction).
//
// The CFG traversal uses a "min-rank" algorithm. First, all reachable basic blocks are
// marked as dirty. The loop-head invariant is that `curr_rank` always points to the
// minimum-rank dirty block in `rpo`. Before processing that block we mark it as clean. If
// the processing dirties a block with a rank lower than or equal to `curr_rank` (via a
// back edge, which could be an edge-to-self) then `curr_rank` is set to that
// lower-or-equal rank. After the block is processed, if `curr_rank` doesn't point to a
// dirty block it is moved to the next dirty block, and we iterate again.
//
// This algorithm ensures each basic block is processed only after all its dirty
// predecessors (ignoring back edges). When a back edge dirties an earlier block we return
// to that earlier block immediately, which avoids processing later blocks with possibly
// soon-to-be-stale information. Loop-free code is processed in a single pass.

That comment is the algorithm specification, and it is unusually precise about the invariant. Let me restate it:

Every reachable block has a rank: its position in reverse postorder.
Rank order is dataflow order: for every non-back edge A→B, rank(A) < rank(B).
curr_rank always points at the minimum-rank dirty block.
When processing a block dirties a block of lower-or-equal rank (a back edge, including a self-loop), curr_rank rewinds to that rank.

The implementation

 rust
 
 
// compiler/rustc_mir_dataflow/src/framework/mod.rs:336-382

let rpo: &[BasicBlock] = body.basic_blocks.reverse_postorder();
let last = rpo.len() - 1;

let mut ranks: IndexVec<BasicBlock, Option<BasicBlockRank>> =
 IndexVec::from_elem_n(None, body.basic_blocks.len());
for (i, &bb) in rpo.iter().enumerate() {
 let rank = if Self::Direction::IS_FORWARD { i } else { last - i };
 ranks[bb] = Some(BasicBlockRank::new(rank));
}

let mut dirty: DenseBitSet<BasicBlockRank> = DenseBitSet::new_filled(rpo.len());
let mut curr_rank = BasicBlockRank::ZERO;

// `state` is not actually used between iterations; this is just an optimization to avoid
// reallocating every iteration.
let mut state = self.bottom_value(body);

loop {
 let i = curr_rank.as_usize();
 let bb = rpo[if Self::Direction::IS_FORWARD { i } else { last - i }];
 debug_assert!(dirty.contains(curr_rank)); // check invariant
 dirty.remove(curr_rank); // invariant temporarily broken

 state.clone_from(&entry_states[bb]);
 let prop = |target: BasicBlock, state: &Self::Domain| {
 ...
 let set_changed = entry_states[target].join(state);
 if set_changed {
 dirty.insert(target_rank);
 curr_rank = curr_rank.min(target_rank);
 }
 };
 Self::Direction::apply_effects_in_block(&self, body, &mut state, bb, &body[bb], prop);

 match dirty.first_set_at_or_after(curr_rank) {
 Some(rank) => curr_rank = rank, // broken invariant re-established
 None => break, // no more dirty blocks; finish
 }
}

Four things to notice:

The dirty set is a bit set, not a queue. dirty.insert(target_rank) is O(1) with no allocation. dirty.first_set_at_or_after(curr_rank) finds the next dirty block with a word scan and a trailing_zeros.
The rewind is one min. curr_rank = curr_rank.min(target_rank) is the entire back-edge handling. Because the cursor is always at the minimum dirty rank, a back edge that dirties an earlier block immediately sends the analysis back there — no stale states propagate forward.
state is reused. The comment says it plainly: the state is not used between iterations, so it is clone_from’d rather than reallocated. The domain’s allocation is reused across the whole analysis.
Backward analyses fake a postorder. mir::basic_blocks::Cache only stores reverse postorder, because that is what the forward analyses need. Rather than adding a postorder field, the rank map is flipped (last - i). One line, and it gives backward analyses exactly the ordering they need.

Why this beats a worklist

A worklist has two problems. It re-evaluates blocks whose predecessors have not all been processed yet, which means re-running the transfer function over the whole block — and the transfer function is the expensive part (it usually walks statements and updates a bitset domain). And it has no ordering guarantee at all, so it can process a block, then its successor, then discover the block changed, and go back.

The min-rank scheme fixes the ordering: a block is only processed when all of its dirty predecessors (ignoring back edges) have been processed. For loop-free code, that means exactly one pass — every block is visited once, and every transfer function runs once per block. For code with loops, the number of passes is bounded by the loop nesting structure rather than by the convergence of a fixpoint.

The cost is that a DenseBitSet is allocated per analysis (size = number of blocks), where a worklist would have been allocated lazily. But it is one allocation, and it replaces the worklist’s allocation plus its push/pop churn.

The other half of the trick: direction as a type

 rust
 
 
// compiler/rustc_mir_dataflow/src/framework/direction.rs:7-40

pub trait Direction {
 const IS_FORWARD: bool;
 const IS_BACKWARD: bool = !Self::IS_FORWARD;

 /// Returns the first statement index for this direction. (0 when going forward and
 /// `statements.len()` when going backward.)
 fn first_index(block_data: &mir::BasicBlockData<'_>) -> EffectIndex;

 /// Returns the next index for this direction.
 fn next_index(idx: EffectIndex) -> EffectIndex;
 ...
}

Analysis::Direction is an associated type, so if Self::Direction::IS_FORWARD in the hot loop is a compile-time constant, not a runtime branch. Forward and backward analyses are separate monomorphizations of the entire engine.

And the “two effects per statement” trick — early and primary — is encoded as a two-variant Ord enum:

 rust
 
 
// compiler/rustc_mir_dataflow/src/framework/mod.rs:466-486

// NOTE: DO NOT CHANGE VARIANT ORDER. The derived `Ord` impls rely on the current order.
#[derive(Clone, Copy, Debug, PartialEq, Eq, PartialOrd, Ord)]
enum Effect {
 /// The "early" effect (e.g., `apply_early_statement_effect`) for a statement/terminator.
 Early,

 /// The "primary" effect (e.g., `apply_primary_statement_effect`) for a statement/terminator.
 Primary,
}

so the cursor can walk either direction over a statement’s two effects with one next_index:

 rust
 
 
// compiler/rustc_mir_dataflow/src/framework/direction.rs:52-58

fn next_index(idx: EffectIndex) -> EffectIndex {
 match idx.effect {
 Effect::Early => Effect::Primary.at_index(idx.statement_index),
 Effect::Primary => Effect::Early.at_index(idx.statement_index - 1),
 }
}

The early/primary split is exactly what lets the borrow checker implement two-phase borrows without a separate analysis: the reservation is the early effect, the activation is the primary effect.

Results are stored per block, not per point

 rust
 
 
// compiler/rustc_mir_dataflow/src/framework/results.rs:8-20

/// The results of a dataflow analysis that has converged to fixpoint. It holds the domain values
/// (states) at the entry of each basic block. Domain values in other parts of the block are
/// recomputed on the fly by visitors (i.e. `ResultsCursor`, or `ResultsVisitor` impls).
pub struct Results<'tcx, A>
where
 A: Analysis<'tcx>,
{
 pub analysis: A,
 pub entry_states: EntryStates<A::Domain>,
}

Only block entry states are stored. Everything inside a block is recomputed on demand by re-running the transfer function from the block entry. Memory is O(blocks × domain), not O(points × domain) — for a MixedBitSet<MovePathIndex> domain with 20 000 move paths, that is the difference between megabytes and tens of megabytes.

Where it lives

compiler/rustc_mir_dataflow/src/framework/mod.rs — iterate_to_fixpoint.
compiler/rustc_mir_dataflow/src/framework/direction.rs — the Direction trait and the effect index.
compiler/rustc_mir_dataflow/src/framework/results.rs — the per-block storage.
compiler/rustc_index/src/bit_set.rs — DenseBitSet and first_set_at_or_after.

Takeaway

A dataflow worklist is a priority queue you did not need. If your graph has a natural order in which information flows — reverse postorder is the standard one — then “process the lowest dirty rank” is both simpler and strictly less work than an unordered worklist, and it gives you the single-pass property for acyclic code for free.

The Borrow Checker Blames the Most Interesting Constraint: BFS, Then a Ranking

Jay Hubbert — Wed, 21 Oct 2026 10:35:00 +0000

TL;DR: Lifetime errors are hard to explain because there are usually many constraints that could be blamed. rustc picks one in two steps: a breadth-first search finds the shortest path through the constraint graph (fewest constraints), and then a hand-tuned “interest” score picks the most user-facing constraint on that path — scanning from the source end or the target end depending on which side is being blamed.

A borrow checker error looks like this:

text

error[E0597]: `x` does not live long enough
 --> src/main.rs:5:20
 |
5 | drop(x);
 | ^ borrowed value does not live long enough

The “borrowed value does not live long enough” part is easy. The hard part is picking which constraint in the chain of lifetime requirements to blame. A function with six lifetime parameters can have dozens of outlives constraints between them, and most of them are compiler-generated noise.

Step one: shortest path

 rust
 
 
// compiler/rustc_borrowck/src/region_infer/region_context.rs:453-475

let mut context = IndexVec::from_elem(Trace::NotVisited, &self.definitions);
context[from_region] = Trace::StartRegion;

let fr_static = self.universal_regions().fr_static;

// Use a deque so that we do a breadth-first search. We will
// stop at the first match, which ought to be the shortest
// path (fewest constraints).
let mut deque = VecDeque::new();
deque.push_back(from_region);

while let Some(r) = deque.pop_front() {

The choice of VecDeque + pop_front over Vec + pop is deliberate and commented: BFS, not DFS. A DFS would find a path, and the path it finds would be arbitrary — often long, often winding through irrelevant constraints. BFS finds the path with the fewest constraints, which is already a decent proxy for “the constraint the user most likely intended”.

Step two: the interest ranking

But shortest is not the same as most useful. rustc goes further and scores each constraint by how interesting it is for a human:

 rust
 
 
// compiler/rustc_borrowck/src/region_infer/region_context.rs:684-768

// To pick a constraint to blame, we organize constraints by how interesting we expect them
// to be in diagnostics, then pick the most interesting one closest to either the source or
// the target on our constraint path.
let constraint_interest = |constraint: &OutlivesConstraint<'tcx>| {
 // Try to avoid blaming constraints from desugarings, since they may not clearly match
 // match what users have written. As an exception, allow blaming returns generated by
 // `?` desugaring, since the correspondence is fairly clear.
 let category = if let Some(kind) = constraint.span.desugaring_kind()
 && (kind != DesugaringKind::QuestionMark
 || !matches!(constraint.category, ConstraintCategory::Return(_)))
 {
 ConstraintCategory::Boring
 } else {
 constraint.category
 };

 let interest = match category {
 // Returns usually provide a type to blame and have specially written diagnostics,
 // so prioritize them.
 ConstraintCategory::Return(_) => 0,

The scores are hand-assigned integers. Zero is “a return expression”, which gets priority because it has a type to show and a dedicated diagnostic message. Everything else is worse, in increasing order, ending with solver-internal constraints.

The final selection picks the best-scoring constraint, scanning the path from one end or the other:

 rust
 
 
// compiler/rustc_borrowck/src/region_infer/region_context.rs:1510-1513 (region_context.rs:750-768)

let best_choice = if blame_source {
 path.iter().enumerate().rev().min_by_key(|(_, c)| constraint_interest(c)).unwrap().0
} else {
 path.iter().enumerate().min_by_key(|(_, c)| constraint_interest(c)).unwrap().0
};

min_by_key finds the lowest interest number, i.e. the most interesting constraint. The only difference between the two branches is the direction of the scan:

blame_source → scan the path in reverse, preferring constraints near the source;
otherwise (blaming a placeholder or a target) → scan forward, preferring constraints near the target.

That asymmetry matters. When you are blaming a sub-type bound, the interesting constraint is near the source; when you are blaming a higher-ranked placeholder, the interesting constraint is near the target.

The cold path is deferred

One more detail worth stealing: the constraints themselves are not built during the search. The search walks a Trace graph, and the actual OutlivesConstraint values are only materialized at the end, on the error path:

 rust
 
 
// compiler/rustc_borrowck/src/region_infer/region_context.rs:477-509

let mut result = vec![];
let mut p = r;
// This loop is cold and runs at the end, which is why we delay
// `OutlivesConstraint` construction until now.
loop {
 match context[p] {
 Trace::FromGraph(c) => {
 p = c.sup;
 result.push(*c);
 }
 ...

The comment is the whole justification: constraint construction involves spans, categories and variance info, and building it for every successful borrow check would be pure waste. The search therefore carries a lightweight Trace enum — NotVisited, StartRegion, FromGraph, FromStatic — and only converts it into real constraints when it is about to complain.

Why not just blame the constraint that failed?

Because there usually isn’t one. The constraint that “failed” is often a derived fact — the region grew too large because of a chain of other constraints. Blaming the derived failure gives the user a message about something they never wrote.

Instead rustc picks the constraint on the path that is closest to the user and most likely to be the real intent. If you have ever seen a lifetime error that pointed at a ? operator, at a return statement, or at an explicit type annotation rather than at the compiler’s internal machinery, this is why.

Where it lives

compiler/rustc_borrowck/src/region_infer/region_context.rs — the BFS (best_blame_constraint), the constraint_interest closure, and the deferred construction of OutlivesConstraint.
compiler/rustc_borrowck/src/region_infer/region_context.rs — ConstraintCategory, the enum the ranking is built on.

Takeaway

Error messages are a performance problem too: they run on the cold path, but they run on the path that users actually see, and a confusing error costs a user far more time than a slow compile. Spending a BFS plus a hand-tuned ranking to pick the right constraint is a good trade, and the “build the expensive thing only on the error path” pattern makes it cheap enough to always do.

end(X) Doesn't Live in the CFG: How rustc Splits Region Values Into Three Dimensions

Jay Hubbert — Wed, 21 Oct 2026 10:30:00 +0000

TL;DR: To ask “does 'a outlive 'b?”, the borrow checker needs a way to refer to the end of a universally quantified region 'b. The obvious encoding is a distinguished point in the CFG — but that would break the interval-set compression that region liveness depends on. rustc instead keeps three independent sparse dimensions per region (program points, free regions, placeholders), and end(X) is simply “X is in the free-region row”.

Region inference produces, for each region, the set of program points where the region is live. That’s the classic picture: a region is a set of CFG points.

But the borrow checker also has to answer questions of the form “does 'a outlive 'b?” where both are named lifetime parameters. To express that, you need a marker for the end of 'b — a distinguished point that says “‘b’ is over here”. And here the design gets interesting.

The naive encoding and why it hurts

If end(X) is a program point, then every region value has to contain the end markers of every region it outlives. A region that outlives five named lifetimes carries five extra points in its set.

That sounds cheap. It is not, because region liveness is stored as an interval set, and the whole reason it is an interval set is that the liveness of a region is contiguous:

 rust
 
 
// compiler/rustc_index/src/interval.rs:19-24

#[derive(Debug, Clone)]
pub struct IntervalSet<I> {
 // Start, end (both inclusive)
 map: SmallVec<[(u32, u32); 2]>,
 domain: usize,
 _data: PhantomData<I>,
}

Two intervals inline, a SmallVec that spills to the heap only if you have more than two runs. If you inject a handful of scattered “end marker” points into every region’s set, you shatter those runs: a region that used to be two intervals becomes ten, the SmallVec spills, and every union gets more expensive.

The other problem is space. The point index space would grow by the number of named lifetimes, and every region’s interval set would grow with it, even the regions that have nothing to do with those lifetimes.

The actual representation

rustc splits the value into three independent dimensions:

 rust
 
 
// compiler/rustc_borrowck/src/region_infer/values.rs:267-276

pub(crate) struct RegionValues<'tcx, N: Idx> {
 location_map: Rc<DenseLocationMap>,
 placeholder_indices: PlaceholderIndices<'tcx>,
 points: SparseIntervalMatrix<N, PointIndex>,
 free_regions: SparseBitMatrix<N, RegionVid>,

 /// Placeholders represent bound regions -- so something like `'a`
 /// in `for<'a> fn(&'a u32)`.
 placeholders: SparseBitMatrix<N, PlaceholderIndex>,
}

Three matrices:

points — where in the CFG the region is live. Interval sets, because this dimension is contiguous.
free_regions — which named lifetimes the region outlives. A bit matrix, because this dimension is sparse and scattered by nature.
placeholders — which higher-ranked binders the region outlives.

Each dimension uses the representation that fits its data. That is the whole trick: the CFG dimension gets interval compression, and the “outlives named lifetime X” dimension gets a sparse bit matrix, and neither pays for the other’s shape.

`end(X)` becomes free

Now look at how free regions are seeded:

 rust
 
 
// compiler/rustc_borrowck/src/region_infer/region_context.rs:143-175

// Initializes the region variables with their initial live points.
for (region, definition) in definitions.iter_enumerated() {
 let scc = constraint_sccs.scc(region);

 // For each universally quantified region (lifetime parameter). The
 // first N variables always correspond to the regions appearing in
 // the function signature (both named and anonymous) and in where-clauses.
 match definition.origin {
 // For each free, universally quantified region X:
 NllRegionVariableOrigin::FreeRegion => {
 // Add `end(X)` into the set for X.
 scc_values.add_free_region(scc, region);
 }

 NllRegionVariableOrigin::Placeholder(placeholder) => {
 scc_values.add_placeholder(scc, placeholder);
 }

 NllRegionVariableOrigin::Existential { .. } => {
 // For existential, regions, nothing to do.
 }
 }

The comment says “Add end(X) into the set for X” — but the implementation is add_free_region, which sets a bit in the free_regions matrix. There is no point, no offset, no sentinel. end(X) is the presence of X in the free-region row of that SCC.

And the consumption side reads it back out of the same dimension:

 rust
 
 
// compiler/rustc_borrowck/src/region_infer/region_context.rs:1466-1474

/// Checks the final value for the free region `fr` to see if it
/// grew too large. In particular, examine what `end(X)` points
/// wound up in `fr`'s final value; for each `end(X)` where `X !=
/// fr`, we want to check that `fr: X`. If not, that's either an
/// error, or something we have to propagate to our creator.

The prose still talks about “end(X) points”, because that is the mental model from the classic papers. But the data structure has no such thing anymore: universal_regions_outlived_by is a bit-matrix row lookup.

 rust
 
 
// compiler/rustc_borrowck/src/region_infer/region_context.rs:1510-1513

// Find every region `o` such that `fr: o`
// (because `fr` includes `end(o)`).
for shorter_fr in self.scc_values.universal_regions_outlived_by(longer_fr_scc) {

Why the union has to touch all three dimensions

The propagation step unions all three:

 rust
 
 
// compiler/rustc_borrowck/src/region_infer/values.rs:298-304

pub(crate) fn add_region(&mut self, r_to: N, r_from: N) -> bool {
 self.points.union_rows(r_from, r_to)
 | self.free_regions.union_rows(r_from, r_to)
 | self.placeholders.union_rows(r_from, r_to)
}

The | matters: all three unions must happen, and the result is “did anything change”, which is what the SCC propagation loop uses to decide whether the propagation is finished. (It always unions, in the one-pass SCC algorithm — but the boolean is used elsewhere, for example when deciding whether a region’s value actually grew.)

The same split shows up in the diagnostic path

The blame machinery needs to walk the “outlives” relation too, and it uses the same matrix:

rust

// compiler/rustc_borrowck/src/region_infer/region_context.rs:1510-1513

Once you see the dimension split, the awkwardness of the old design disappears: “which regions does this one outlive?” is a bit-matrix row scan, which is exactly as cheap as it should be.

Where it lives

compiler/rustc_borrowck/src/region_infer/values.rs — RegionValues and the three matrices.
compiler/rustc_borrowck/src/region_infer/region_context.rs — seeding and consumption of the free-region dimension.
compiler/rustc_index/src/interval.rs — SparseIntervalMatrix.
compiler/rustc_data_structures/src/sparse.rs — the sparse bit matrix.

Takeaway

This is a general technique worth stealing: when a data structure needs to carry two kinds of facts that have different shapes — one dense and contiguous, one sparse and scattered — do not force them into one representation. Split the space, give each part the encoding that suits it, and then define the “cross-cutting” queries (like “is X in my set?”) in terms of the part that owns X.

The payoff is that end(X) costs zero extra points in the CFG, so the interval sets that make region inference fast stay small.

One Pass, No Fixpoint: How rustc Solves Borrow Regions by Condensing Them Into SCCs

Jay Hubbert — Wed, 21 Oct 2026 10:25:00 +0000

TL;DR: Region constraints ('a: 'b) form a graph that is usually cyclic. The borrow checker does not iterate to a fixpoint over that graph. It condenses the graph into strongly connected components — where every member is equal by construction — and then walks the condensation in dependency order, unioning values once per edge. One pass, no worklist, no convergence argument.

The old, pre-NLL borrow checker computed region constraints by iterating: it had a set of region variables, a set of constraints, and it looped until nothing changed. Every loop was a full re-scan of every constraint, and the loop count was unbounded in principle. NLL replaced that with a region inference pass that is structurally different: it computes, for each region, the set of program points where it must be live.

The algorithm

 rust
 
 
// compiler/rustc_borrowck/src/region_infer/region_context.rs:858-886

impl<'tcx> UnsolvedRegionInferenceContext<'tcx> {
 /// Propagate the region constraints: this will grow the values
 /// for each region variable until all the constraints are
 /// satisfied. Note that some values may grow **too** large to
 /// be feasible, but we check this later.
 #[instrument(skip(self), level = "debug")]
 fn propagate_constraints(&mut self) {
 ...
 // To propagate constraints, we walk the DAG induced by the
 // SCC. For each SCC `A`, we visit its successors and compute
 // their values, then we union all those values to get our
 // own. This one-shot approach works because iteration is in
 // dependency order. I.e. a chain A: B: C will visit C, B, A.
 for scc_a in self.constraint_sccs.all_sccs() {
 // Walk each SCC `B` such that `A: B`...
 for &scc_b in self.inner.constraint_sccs.successors(scc_a) {
 debug!(?scc_b);
 self.inner.scc_values.add_region(scc_a, scc_b);
 }
 }
 }
}

That comment is the whole algorithm. Two properties make it work:

Within an SCC, all regions are equal. If 'a: 'b and 'b: 'a, then 'a and 'b must have the same value. So one value per SCC is enough, and it is exactly right.
The condensation is a DAG, and rustc walks it in dependency order. The SCC data structure guarantees this:

 rust
 
 
// compiler/rustc_data_structures/src/graph/scc/mod.rs:129-137

/// Returns an iterator over the SCCs in the graph.
///
/// The SCCs will be iterated in **dependency order** (or **post order**),
/// meaning that if `S1 -> S2`, we will visit `S2` first and `S1` after.
/// This is convenient when the edges represent dependencies: when you visit
/// `S1`, the value for `S2` will already have been computed.
pub fn all_sccs(&self) -> impl Iterator<Item = S> + 'static {
 (0..self.scc_data.len()).map(S::new)
}

Tarjan’s algorithm naturally emits SCCs in reverse topological order, which is exactly dependency order for this graph. So the walk is: for each SCC, all successors are already final; union them in; move on.

What “union” costs

The value of a region is not a boolean, it is a set of program points. And the union of two such sets is not free:

 rust
 
 
// compiler/rustc_borrowck/src/region_infer/values.rs:298-304

/// Adds all elements in `r_from` to `r_to` (because e.g., `r_to:
/// `r_from`).
pub(crate) fn add_region(&mut self, r_to: N, r_from: N) -> bool {
 self.points.union_rows(r_from, r_to)
 | self.free_regions.union_rows(r_from, r_to)
 | self.placeholders.union_rows(r_from, r_to)
}

Three separate sparse matrices — program points, free regions, placeholders — unioned independently. (The dimension split is the subject of its own article: end(X) doesn’t live in the CFG.)

The points dimension is an interval matrix, not a bitmatrix, because region liveness is contiguous:

 rust
 
 
// compiler/rustc_index/src/interval.rs:345-358

/// This data structure optimizes for cases where the stored bits in each row
/// are expected to be highly contiguous (long ranges of 1s or 0s), in contrast
/// to BitMatrix and SparseBitMatrix which are optimized for
/// "random"/non-contiguous bits and cheap(er) point queries at the expense of
/// memory usage.
#[derive(Clone)]
pub struct SparseIntervalMatrix<R, C>
where
 R: Idx,
 C: Idx,
{
 rows: IndexVec<R, IntervalSet<C>>,
 column_size: usize,
}

And the union itself is careful about operand order:

 rust
 
 
// compiler/rustc_index/src/interval.rs:313-330

pub fn union(&mut self, other: &IntervalSet<I>) -> bool
where
 I: Step,
{
 assert_eq!(self.domain, other.domain);
 if self.map.len() < other.map.len() {
 let backup = self.clone();
 self.map.clone_from(&other.map);
 return self.union(&backup);
 }
 ...

If the left side is smaller, it swaps the operands and recurses, so the loop always iterates over the larger set’s intervals while inserting into the smaller one. That is the standard “merge into the smaller container” trick, and it matters when one region has two intervals and the other has two hundred.

The fixpoint that isn’t

Compare with the old design. The classic formulation is a worklist algorithm: put every region in the worklist, pop one, union its successors’ values into it, and if it grew, re-enqueue its predecessors. That is O(R·E) set unions in the worst case, and — worse — it re-does work that the SCC structure makes unnecessary.

The condensation changes the shape of the problem:

before: R regions, E constraints, up to R rounds;
after: S SCCs (S ≤ R), E unions on SCC values, one round.

For the common case where most regions are not in cycles, S ≈ R and the constant factor is what you save. For the pathological case — a big cycle of mutually borrowing regions, which happens with self-referential structs and closures — the old algorithm would spin; the new one computes the answer once.

The SCC computation is not free either

There is one subtlety: the SCC computation happens before the propagation, and the propagation can add constraints. If a new constraint merges two SCCs, the SCCs have to be recomputed. The borrow checker avoids this by folding the higher-ranked (“placeholder”) analysis into the SCC computation itself, as an annotation:

 rust
 
 
// compiler/rustc_borrowck/src/handle_placeholders.rs:154-169

impl scc::Annotation for RegionTracker {
 fn update_scc(&mut self, other: &Self) {
 trace!("{:?} << {:?}", self.representative, other.representative);
 self.representative = self.representative.min(other.representative);
 self.update_reachable(other);
 }

 fn update_reachable(&mut self, other: &Self) {
 self.max_nameable_universe = self.max_nameable_universe.min(other.max_nameable_universe);
 ...
 }
}

The scc::Annotation trait is a commutative-merge interface that Tarjan’s DFS calls automatically as it pops nodes off its stack. So the borrow checker gets, in the same O(V+E) traversal, the representative region for each SCC, the largest nameable universe reachable from it, and the set of reachable placeholders. All of that used to be a separate fixpoint.

And when a genuinely unnameable placeholder turns up, the constraint set is rewritten and the SCCs are recomputed — once:

 rust
 
 
// compiler/rustc_borrowck/src/handle_placeholders.rs:283-302

let added_constraints = rewrite_placeholder_outlives(
 &constraint_sccs,
 &scc_annotations,
 fr_static,
 &mut outlives_constraints,
);

let (constraint_sccs, scc_annotations) = if added_constraints {
 let mut annotations = SccAnnotations::init(&definitions);

 // We changed the constraint set and so must recompute SCCs.
 // Optimisation opportunity: if we can add them incrementally (and that's
 // possible because edges to 'static always only merge SCCs into 'static),
 // we would potentially save a lot of work here.
 (compute_sccs(&outlives_constraints, &mut annotations), annotations.scc_to_annotation)
} else {
 // If we didn't add any back-edges; no more work needs doing
 debug!("No constraints rewritten!");
 (constraint_sccs, scc_annotations.scc_to_annotation)
};

Note the “Optimisation opportunity” comment: the authors know this is a second pass and have written down why it is rare.

Where it lives

compiler/rustc_borrowck/src/region_infer/region_context.rs — propagate_constraints.
compiler/rustc_data_structures/src/graph/scc/mod.rs — the dependency-order SCC iterator.
compiler/rustc_borrowck/src/region_infer/values.rs — the region value representation and add_region.
compiler/rustc_index/src/interval.rs — the interval matrix.
compiler/rustc_borrowck/src/handle_placeholders.rs — the SCC annotation trick.

The takeaway is a nice one: a fixpoint over a graph is often a fixpoint over a condensation of that graph, and if you can prove the members of each strongly connected component are equal, the condensation is a DAG and the fixpoint is a single topological sweep.

Borrow-Check on Opensource internals

Two-Phase Borrows Are Just Dominator Queries: How `v.push(v.len())` Compiles

The obvious implementation, and its cost

What rustc does instead

Step three: the dominator argument

The cost

Where it lives

Takeaway

No Queue At All: rustc's Dataflow Engine Uses a Bitset and a Rank

The algorithm rustc uses instead

The implementation

Why this beats a worklist

The other half of the trick: direction as a type

Results are stored per block, not per point

Where it lives

Takeaway

The Borrow Checker Blames the Most Interesting Constraint: BFS, Then a Ranking

Step one: shortest path

Step two: the interest ranking

The cold path is deferred

Why not just blame the constraint that failed?

Where it lives

Takeaway

end(X) Doesn't Live in the CFG: How rustc Splits Region Values Into Three Dimensions

The naive encoding and why it hurts

The actual representation

end(X) becomes free

Why the union has to touch all three dimensions

The same split shows up in the diagnostic path

Where it lives

Takeaway

One Pass, No Fixpoint: How rustc Solves Borrow Regions by Condensing Them Into SCCs

The algorithm

What “union” costs

The fixpoint that isn’t

The SCC computation is not free either

Where it lives

`end(X)` becomes free