Skip to content
ry

Memory safety in the runtime

The interpreter keeps R values as raw pointers and keeps them valid by convention. This page proposes types that carry the conventions, so the compiler checks them:

  • A function that can run a collection takes &mut Cx. A value read out of the heap borrows &Cx, so keeping it across such a call without rooting it is a compile error.
  • A rooted value is a plain pointer with a lifetime, and rooting costs the one push it costs today.
  • A pointer’s type names its representation, so a write into an object with no element storage (an ALTREP wrapper) has no way to be written.
  • An object is written in place only through a guard that holds the context, so no R code and no other reader runs while it is being written.
  • unsafe stays in heap, in libr’s C entry points, in the helpers that generated code calls, and on a short allowlist in the interpreter.

The design aims at no added instruction on a hot path. Cost lists the constructs where that has to be measured before it is believed.

A builtin looks like this (shortened from do_nchar):

unsafe fn do_nchar(call: &Call<'_>) -> R<Sexp> {
let text = character_vector(call.arg(0))?;
let result = alloc(SexpType::Integer, length(text))?;
let counts = values::ints_mut(result);
for (index, slot) in counts.iter_mut().enumerate() {
*slot = text.element(index).bytes().len() as i32;
}
copy_shape(call.arg(0), result)?;
Ok(result)
}

Every line relies on a rule nothing checks. text must be rooted, because alloc can collect. ints_mut returns a slice with no lifetime, so counts can outlive result. result must be an integer vector with element storage. text.element runs a native method when text is an ALTREP string vector, and that method can allocate while counts is borrowed. The whole function is unsafe fn, so the compiler marks none of these.

The runtime has seven such rules. Each has produced a crash or a wrong answer that a test now pins:

Rule kept by hand What breaks Pinned by
A value held across an allocation or a call is rooted a freed object is read datetime__year_overflow, apply__lapply_closure_results_stay_rooted
A store into an old object runs the write barrier a young object is freed while an old one points at it datatable__setcolorder_young_columns, datatable__setorder_young_strings
An element read or write goes to an object of the right kind that has element storage the write lands on the next object, or the read takes another type’s bytes for pointers assignment__long_argument_copy_element_stores, strings__encoding_rejects_non_character
An object is modified in place only when nothing else can see it another variable changes assignment__dollar_in_place
A frame’s slots and its environment agree about each variable a stale or missing binding environments__unread_loop_variable
A new object is filled before anything can read or trace it uninitialized elements are traced the collector’s seeded tests (heap test_gc)
Two strings are compared by their text, not their address a name that is there is not found subset__non_ascii_names

The scale is the reason review does not hold these rules. Counted over each crate’s src:

Crate Lines unsafe fn unsafe blocks SAFETY comments
interp 137,354 3,291 593 216
libr 26,946 1,282 118 36
heap 13,336 356 227 64
typed 24,194 391 4 7
graphics 18,702 397 26 16
stats 22,177 249 8 8
jit 18,748 222 106 7
frames 4,304 144 3 2

Two more facts make the current code unsound even where it is careful. interp::heap() and interp::interp() are safe functions that return &'static mut, so any two calls alias, and the interpreter calls them about 1,600 times. And each runtime crate’s root sets #![allow(unsafe_op_in_unsafe_fn)], so inside those 3,291 functions no raw read carries an unsafe block. The migration deletes that line crate by crate.

A safepoint is a point where the heap may free an object or foreign code may run: an allocation (collections and the reference-count reconcile both run there), a call into R code, and a call into native code, which includes every ALTREP method. Between safepoints nothing is freed, which is the same promise R’s C API makes to native code.

Cx<'s> is the context: the heap, the interpreter’s state, and the current handle scope 's. It replaces the global accessors. The two ways to borrow it are the two capabilities:

Borrow Allows So it is taken by
&mut Cx<'s> a safepoint allocation, evaluation, calling a closure or a native routine, any ALTREP method, a variable lookup that can force a promise or fill an inline cache, defining a variable
&Cx<'s> one load from the heap, rooting, a store with its barrier field and element reads of standard objects, slices, comparisons, element stores into an object being built

A read takes &Cx only when it is a single load. Anything that can dispatch (an element of an ALTREP vector, the length of one, a variable whose binding is active or a promise) takes &mut Cx.

Cx is a capability, not a reference to the heap’s memory. It holds raw pointers to the heap and to the interpreter’s state, and each method dereferences them for one operation. A C entry point reached from native code (Rf_eval inside .Call) therefore makes its own Cx without creating a second &mut to the same memory, and the caller, which lent its &mut Cx to the native call, holds no unrooted value or slice across it.

All four are one machine word, the same word a SEXP is, because the heap does not move objects.

Type Meaning Made by Lives until
Gc<'a, T> read from the heap, not rooted a load through &'a Cx the next safepoint: it borrows the context
Local<'s, T> rooted in scope 's cx.root(gc), every constructor, every argument, every register operand the scope ends
Fresh<'s, T> a new object nothing else can see cx.alloc::<T>(n), handles::duplicate finish() turns it into a Local
Write<'a, 's, T> exclusive access to an existing object the interpreter’s ownership checks it borrows the context mutably

Gc and Local are Copy. Fresh and Write are not: each is the only way to reach its object while it lives, which is what makes writing through it safe.

Holding an unrooted value across a safepoint does not compile:

let first = list.get(cx, 0); // Gc<'_, Value>, borrows cx
let copy = cx.alloc::<Real>(n)?; // error[E0502]: cannot borrow `*cx` as mutable
use_both(first, copy); // because it is also borrowed as immutable

The fix is the root the hand-written rule asks for, and it is the same push:

let first = cx.root(list.get(cx, 0)); // Local<'s, Value>
let copy = cx.alloc::<Real>(n)?;

cx.root takes &Cx, not &mut Cx: pushing onto the handle stack is not a safepoint, and it must be callable while the Gc it roots still borrows the context.

T is the object’s kind: Real, Integer, Logical, Complex, Raw, Str, Chars, List, Expression, Symbol, Environment, Closure, Promise, Language, Pairlist, Alt and Value for any of them. A vector kind means a standard vector, with its length in the header and its elements behind it. An ALTREP object is an Alt, whatever R type it reports, so a Local<Real> always has elements and len(), get(cx, i) and as_slice(cx) on it are plain loads.

A Local<Value> becomes a typed pointer through one checked downcast, the test a builtin already makes when it dispatches on kind(). Code that accepts “a double vector” asks for the view it can work with:

match reals(cx, value)? { // one test of the kind and the ALTREP bit
Reals::Standard(vector) => sum(vector.as_slice(cx)),
Reals::Sequence { first, step, len } => closed_form(first, step, len),
Reals::Lazy(alt) => each(cx, alt), // alt.get(cx, i) takes &mut Cx
}
let dense = dense::<Real>(cx, value)?; // &mut Cx: Local<Real>, materialized once
let slice: &[f64] = dense.as_slice(cx); // borrows cx, so no safepoint while it lives

The views live in interp::handles, because expanding an ALTREP object runs the hook libr installs, and heap knows only that an Alt is not a vector. dense always returns a standard vector, as values::materialize does: the vector itself, the one a wrapper wraps, the one a compact sequence or deferred string vector expands into and keeps, or a copy for a class a package registers. No slice ever points at memory a class owns. A loop that only reads a few elements uses the Lazy arm, so a class’s Elt method runs for the elements asked for and a long sequence is not expanded.

This replaces a test of the ALTREP bit on every Sexp::element call with one test per vector, and it is the rule that removes the write into an object without storage: element writes exist only on standard kinds.

A copy says which kind it returns. R has two copies, and by hand they look alike:

Copy Raw function Typed form Returns
An owning copy, for a caller that writes elements values::duplicate, values::shallow_duplicate handles::duplicate(cx, vector), handles::shallow_duplicate(cx, vector) Fresh<'s, T>: a standard vector nothing else sees
A copy for a caller that changes only attributes values::shallow_duplicate_attr handles::attribute_copy(cx, value) Local<'s, Value>: for a vector of 64 or more elements, a wrapper that shares the original’s data

The second has no storage of its own when it is a wrapper, so a Sexp::slice_mut on it is an empty slice, and an indexed write through that slice lands on the next object in the heap. That is the write assignment__long_argument_copy_element_stores pins: tier 0’s matrix element store copied a shared argument with the attribute copy and then stored into it.

With the typed forms that store has no spelling. A Local<Value> has no element access at all. The two ways from it to a mutable slice both refuse a wrapper:

  • downcast::<Real>() returns None for an ALTREP object, so there is no Local<Real> to hand to an ownership check, and Cx::assume_exclusive accepts only vector kinds.
  • dense::<Real> returns the standard vector the wrapper shares, as a Local<Real>, which reads but does not write. Writing needs a Write, and the ownership check fails because the wrapper holds a reference to that vector, so the caller takes handles::shallow_duplicate, the owning copy.

The attribute setters accept any Local<Value>, so a caller that only changes attributes keeps the cheap copy.

Write API Why it is sound
Fill a new atomic vector fresh.as_mut_slice() Fresh is the only pointer and takes &mut self. No context is needed, because the object holds no pointers
Fill a new list, string vector or pairlist fresh.set(cx, i, value) with &Cx the store runs the barrier and the count inside heap. A safepoint between two stores can promote the object, and the barrier covers that. There is no &mut [Gc] to fill without it
Change an existing object in place write.split(), or write.split_elements() for a list Write holds &mut Cx, so no slice taken earlier is alive, no R code runs, and nothing can share the object meanwhile
Store into an object with reference semantics cx.define(env, sym, value) (&mut Cx), promise and external-pointer fields (&Cx) the barrier and the count run inside heap

A store is not a safepoint: a count that drops to zero is only noted, and the object is freed at the next allocation. That is why element stores need only &Cx, and why copying elements from one list into a new one roots nothing:

let mut out = cx.alloc::<List>(n)?;
for index in 0..n {
out.set(cx, index, input.get(cx, index));
}

Lists and string vectors hand out no slice of their elements, only single loads, so a store through &Cx never invalidates a borrowed slice.

In-place modification. Whether an object may be changed in place is a fact about the interpreter: its count is one, and no register, handle or escaped list holds it uncounted (slot_owns, a call’s reusable test). The functions that establish that fact live in interp and are the only callers of Cx::assume_exclusive, an unsafe constructor that returns the Write. Because a Write borrows the context mutably, the fact cannot go stale: no R code runs between the check and the write. When the check fails, the caller duplicates (handles::duplicate returns a Fresh, never an ALTREP wrapper), stores the copy in the variable and checks again.

write.split() gives an atomic vector’s element storage and a reader for the sources. The reader compares storage addresses and returns None for a source that shares the target’s storage, which also covers a wrapper around the target. The caller then reads from the mutable slice itself, so x[i] <- x[j] is elements.copy_within(..). For a list, write.split_elements() gives barriered single stores and a reader of single elements, and the same object may be read and written.

let mut write = own_slot(cx, state, slot)?; // interp: the ownership check
let (elements, reader) = write.split();
match reader.slice(value) {
Some(source) => elements[position] = source[0],
None => elements.copy_within(0..1, position),
}

Write also carries the operations that change an object’s shape: setting attributes, and shortening or growing within capacity. Logical and Integer have the same Atomic::Element, so a copy that is generic over the element type serves both.

nchar is written in this shape (crates/interp/src/strings.rs). Its core:

fn do_nchar<'s>(context: &mut Cx<'s>, arguments: &Args<'_, 's>) -> R<Local<'s>> {
let x = arguments.value(0);
let text = handles::character_vector(context, x)?; // a standard Local<Str>
let mut result = context.alloc::<Integer>(text.len())?;
for (slot, chars) in result.as_mut_slice().iter_mut().zip(text.iter(context)) {
*slot = chars.bytes().len() as i32;
}
handles::copy_shape(context, x, &mut result)?; // attributes go onto the Fresh
Ok(result.finish().value())
}

Strings compare by text, symbols by identity

Section titled “Strings compare by text, symbols by identity”

Two strings with the same text can be two objects: the heap interns a text once per encoding mark, so "é" marked latin1 and "é" marked UTF-8 differ as pointers. A name lookup that compares pointers therefore misses a name that is there (subset__non_ascii_names). The bug is not a memory error, but it has the same cause: a Sexp compares with ==, and nothing says whether identity is the question.

A handle has no ==. Gc and Local implement Copy and nothing else, and each comparison names what it compares:

Question Spelling Defined for
Do two strings hold the same text? handles::same_text(left, right) Chars
Is a string NA? handles::is_na(chars) Chars
Are these the same object? left.is(right) every kind except Chars

same_text is values::same_string: equal pointers are equal text, two interned ASCII strings with different pointers differ, NA equals only itself, and any other pair compares its decoded text, so the common case stays one compare.

A Symbol compares by identity, and that is correct by construction: the only way to make one from a string is handles::install(cx, chars), which installs a string of any encoding under its UTF-8 text. Two spellings of one name are then one symbol, so code that matches names against symbols (argument matching, $ on an environment) needs no text comparison.

A Gc<Chars> still widens to Gc<Value>, and is accepts that, so an identity comparison of two strings can be written on purpose. It cannot be written by reaching for ==.

A constructor returns its object already rooted in the current scope, as values::alloc does, so returning a value from a &mut Cx function does not extend the borrow. A callee that wants to release its temporaries runs in a nested scope:

let total = cx.scope(|cx| { // cx: &mut Cx<'inner>
let parts = split(cx, input)?; // Local<'inner, _>
sum(cx, parts) // the result is rooted again in the outer scope
})?;

The closure is generic over 'inner, so a Local<'inner, _> cannot leave it except as the result. This is interp::scope with the lifetime that proves what its comment asks for. An unwind (Error, Return, Break) carries its values unbranded, and the scope it leaves roots them again in the enclosing one, as it does a result: the error type implements Reroot, whose one unsafe impl for Unwind says that every object it gives access to is rooted afterwards.

The bytecode loop does not pay that second root. Its registers are traced, so an instruction that can root runs in cx.scope_to(register, ..), which writes the result into the destination register and releases the handles, as the loop’s release does by hand.

Operands need no handle either. Only the running activation’s own instructions write its expression registers, so a value in one stays put for the length of the instruction that reads it. The loop’s operand accessor returns it as a Local under the instruction’s brand, and a builtin’s arguments arrive the same way. That accessor is one unsafe adoption resting on the bytecode’s own invariant. A variable slot is different: a nested closure’s <<- can overwrite it during a call, so a slot read is a Gc and reaches an operand through an expression register.

Values kept in the interpreter’s own state (frames, the handler stack, caches) sit in Held<T> fields, readable as Gc through &Cx. Each such structure has one unsafe impl Trace that marks its fields.

Place Why Bound
heap the object layout, the allocator, the collector, and the handle types themselves the crate
libr C entry points a SEXP from C carries no proof; each entry makes a Cx and adopts its arguments one block per entry point
Helpers called from JIT and typed code generated code passes raw words one block per helper
Ownership checks they assert the fact Write rests on the few functions that call assume_exclusive
The bytecode loop’s registers operand adoption, the raw register pointers an activation keeps, and unchecked indexing only if bounds checks measure above noise one accessor module
Calling a native routine, operating-system calls foreign code an allowlist of files in interp
unsafe impl Trace the collector trusts it one per structure that holds values

Everything else in interp, stats, graphics and frames is safe Rust, and #![deny(unsafe_op_in_unsafe_fn)] makes each remaining operation carry a block and a SAFETY comment.

Construct Machine cost Today Status
Gc, Local, Fresh one word, passed in a register Sexp, the same word equal by construction
cx.root one push heap.root, the same push equal by construction
Register operands none: adopted as Local none: registers are traced equal by construction
Instruction scope a compare and a truncate the same, in release equal by construction
Downcast one compare on the kind byte the match kind() the builtin already has equal by construction
Views one test of the ALTREP bit per vector one test per element less work
Element stores barrier and count the same equal by construction
Write one address compare per source vector hand-written alias checks to measure
&mut Cx parameter one more live register through every call a load from a static in heap(); the bytecode loop keeps the heap pointer in its activation no cost in a builtin (measured below); to measure on the call path and in the bytecode loop, where register pressure has cost this interpreter before (lookup_outside is forced inline for that reason)
Slice access bounds checks where an index is not an iterator mostly slices already no cost in an element walk (measured below)

nchar is measured against its raw form, both compiled into one release build and counted with callgrind:

Program Raw form Safe form
nchar(s) on one string, 200,000 calls: instructions in the builtin per call 249 233
The same, with the .Internal call around it 1,390 1,374
sum(nchar(y)) on 100,000 strings, 20 times: instructions per element 284.8 278.8

The safe form is shorter because a dense view tests the ALTREP bit once per vector, where the raw accessors test it per element. One rule came out of the measurement: a wrapper in interp::handles whose common case is a test keeps the test #[inline] and its slow path #[inline(never)]. With the whole wrapper generic and out of line (the attribute copy for a value that has no attributes, the coercion of an argument that is already a character vector), the safe nchar ran 42 instructions per call longer than the raw one.

Each migration change measures its builtins the same way before the raw form is deleted, and a change that reaches the call path or the bytecode loop reports just bench-mechanisms and tier 1’s instruction counts (test_tiers) before and after. A regression is fixed by changing the API (for the context parameter: keeping it in the activation, or making Cx a zero-sized token whose methods load the static as heap() does), not by keeping the raw version.

Design How it keeps a value alive Verdict for ry
Handle scopes with indirect handles (V8) every value is a pointer to a slot the collector updates Reject. The indirection exists because V8 moves objects. ry cannot move an object native code holds, so it would pay a slot and a load per value for nothing. Scopes are also unchecked: a handle that outlives its scope is a use after free. V8’s direct handles drop the slot and pair with conservative stack scanning, the row below (not checked against current V8)
Branded arena lifetimes with collection only between mutations (gc-arena) nothing needs rooting, because the collector runs only when no mutator frame is on the stack Reject as the mechanism, adopt the brand. R evaluation is recursive Rust that re-enters from C (Rf_eval inside .Call), so there is no point with an empty stack to collect at. The invariant-lifetime brand is what Cx<'s> and Local<'s, T> use
Rooted and Handle, with a static analysis for hazards (SpiderMonkey) explicit roots on the stack; a separate tool finds values held across a call that can collect Adopt the model, replace the tool. SpiderMonkey’s Rust bindings mark “can collect” with &mut JSContext; borrowing does the hazard analysis in the compiler. Josephine (Servo) and shifgrethor have the same shape, a context borrow plus branded roots, and their known difficulty is a second context made on re-entry from foreign code, which is why Cx is a capability and not a reference
CAMLparam and CAMLlocal (OCaml) every local is registered by macro Reject. It is the PROTECT discipline, unchecked. ocaml-interop shows the borrow-checked form of the same idea
Reference counting with in-place mutation when unique (Roc) the count Reject for liveness, adopt uniqueness. Environments and closures form cycles, and native code, registers and handles hold pointers they never count, so a count cannot free at the decrement: ry frees from counts only at an allocation, after checking the roots. Write is the type-level form of Roc’s “mutate when unique”
Conservative stack scanning (JavaScriptCore, Ruby) the collector treats every word on the native stack as a possible pointer Reject. It needs no roots and would remove the handle pushes, and the heap can afford it because nothing moves. But a dead value in a stale stack slot stays alive for as long as the compiler happens to leave it there, which breaks finalizer timing that R6 and lgr rely on and that the evaluation__*finalizer* cases pin, and it makes that timing depend on code generation. It also covers one rule of seven, does not see values in Rust heap containers, and rests on the optimizer keeping a recognizable pointer
Borrow-checked safepoints with scope-branded direct handles a root-stack slot, proved by the type Adopt. Described above

The expectation going in was branded handles at no runtime cost, and it holds with one correction. The brand alone (a lifetime on a rooted pointer) proves a rooted value does not outlive its scope. It does not catch the unrooted value, the first rule in the table at the top. That needs the second half: unrooted values borrow the context, and safepoints take it mutably. And lifetimes do nothing for the third rule, a write into an object without storage, which needs the kind to name the representation.

Arena indices stay where the layout already uses them (frames in the frame arena, registers in the window, slots in a record). They are not a replacement for object pointers: an index needs a table between it and the object, and native code needs the object’s address.

Rule Why not Caught by
Each unsafe impl Trace marks every field a missed field is an unrooted value in the interpreter’s state seeded stress with verification over the oracle cases, each run twice in one process
An ownership check is right before it calls assume_exclusive the fact depends on counts, registers and frames the replacement contract in interp test_fuzz, assignment__dollar_in_place and its siblings
An expression register is written only by its own activation a property of the bytecode the compiler emits the tier differential, seeded stress
Native code keeps the C API’s rules foreign code can do anything libr test_fuzz_native for ry’s side of the boundary; nothing checks a package’s C code
A libr entry point adopts what C gave it correctly C can pass anything libr test_fuzz_native, the PROTECT balance check
Generated code keeps its values in the register window across helpers machine code has no types ry-jit-gctorture, the tier differential
A frame’s slots agree with its environment a relation between two structures the replacement and shadowing contracts in interp test_fuzz, the differential fuzzer’s repeated calls
A count is not undercounted counts gate copies and deferred frees, and the stores that keep them sit inside heap RY_GC_VERIFY on every reconcile

Robustness describes those harnesses.

heap::handle holds the handle types and Cx, with a compile-fail doctest for each rule above and crates/heap/tests/test_handles.rs running them on a heap that collects before every allocation. interp::handles is the interpreter’s side: a safe builtin has the signature fn(&mut Cx<'s>, &Args<'_, 's>) -> R<Local<'s>>, the safe! macro makes the raw entry the builtin table holds, and each value helper a safe builtin calls has a safe form there that wraps the raw one and says why the handle types make the call sound. The wrappers are where a migrated function meets an unmigrated one, so that boundary is visible and counted, and a wrapper disappears when the helper under it is migrated.

The order:

  1. interp leaf builtins (strings, numbers, sorting, arithmetic kernels), then values.rs, then subsetting and assignment, then the evaluator and the bytecode loop.
  2. stats, graphics, frames.
  3. libr, jit, typed: entry points make a Cx; raw access leaves their bodies.
  4. heap stops exporting the raw accessors outside a raw module that only the boundary imports, and interp::heap() and interp::interp() are deleted.

tools/unsafe-baseline.txt records the count of unsafe per source file outside the crates that own it. just gate fails when a file’s count rises (tools/unsafe.py check), and a change that lowers one lowers the baseline with it, so the count only falls. interp::handles is the one file that may rise, and by less than the other files lose in the same change: a migrated builtin that needs a helper with no safe form adds the wrapper there and removes more unsafe than the wrapper holds.

The guarantee covers a function that names neither Sexp nor interp::heap(). While the raw API is public (until step 4), safe code can leave the handle types and come back: raw() on any pointer yields a Sexp, Sexp compares by address, interp::heap() is a safe function that returns the whole heap, and an unwind carries raw values in public fields. A migrated function that does any of these compiles, and nothing but review rejects it. Step 4 removes the paths (raw() becomes visible only to the boundary crates, and an unwind holds Held values), and until then a migrated file is one in which tools/unsafe.py counts no unsafe and a reader finds no Sexp.

  • Whether a kind should refuse a vector that carries the array flag. dense and downcast admit one, so a migrated fast path over a slice skips the strict checks the array code makes unless it tests the flag itself, as the raw fast paths must. A kind per flagged representation would make the test a type.
  • Whether the bytecode loop’s register access measures the same with bounds checks.
  • Which form of the context parameter measures best on the call path: a pointer in a register, a field of the activation, or a zero-sized token.
  • How Held<T> fields in structures that native code also reaches (the precious list, external pointer protection) share one definition with libr.
  • The spelling for linking a pairlist cell after it is visible to other code, which the evaluator does when it builds argument lists incrementally.
  • A bulk fill for a new list or character vector. fresh.set runs the barrier and the count per element, and the raw code fills such a vector through its slice and counts once (Heap::count_written_elements), which measured several times faster in as.character and strsplit-style builders. The safe form is one call that takes an iterator of elements.