Skip to content
ry

The R runtime

This is a design draft: how ry becomes an R implementation of its own, in what order to build it, and why. Built so far are the object model and collector in crates/heap, the C API as libR.so in crates/libr (the whole measured surface, ALTREP and connections), package installation in crates/rcmd, an interpreter in crates/interp with a tier-0 bytecode (ry run), a first Cranelift JIT in crates/jit (section 5, “What tier 1 does today”), and a table engine in crates/table. Not built are compiled-to-compiled calls of general (non-scalar) functions, ry’s own base R (base R’s R code still comes from a GNU R installation), and the table type’s use from the interpreter. ry run runs on ry’s runtime, and ry R drives GNU R. The C API measurements in section 2 are real and reproducible. Where section 4 describes something built, .agents/memory/decisions/heap-gc.md (“the runtime’s object model, collector and native boundary”) records the settled details.

The rest of the page argues for each of these, and section 10 orders them into a build plan.

  • Implement R’s C API as an ABI-compatible libR. A package’s compiled code must load and run unchanged, including binaries built against GNU R’s headers. This is cheap to promise, because since R 4.2.0 the public headers treat SEXP as an opaque pointer, so ry’s object layout stays its own. The surface is the whole public header set of R 4.6, not a subset: the benchmark’s dependency closure uses 792 distinct API names (plus 150 BLAS and LAPACK routines), and covering even half of its compiled packages takes the 495 most widely used ones.
  • Keep the object model close to GNU R where native code can see it, and free everywhere else. Objects that native code touches do not move, PROTECT keeps its stack semantics, strings are interned so pointer equality works, and ALTREP is a first-class mechanism. Inside the interpreter and the JIT, scalars stay unboxed and environments are materialized only when something needs one.
  • Write the runtime in Rust, with a thin C layer at the native boundary that turns R’s longjmp-based errors into Rust results and back.
  • Execute in two tiers: a bytecode interpreter with inline caches and type feedback, then an optimizing JIT on Cranelift with speculation and deoptimization. A baseline tier between them was measured and removed, because tier 0’s dispatch is too small a share of the time. ry’s static types seed the speculation, so code runs fast before it has warmed up.
  • Load packages lazily from ry’s own analysis index. A top-level function definition becomes a binding that compiles on first use; other top-level code runs eagerly in collation order. Reloading replaces exactly the items that changed and removes deleted ones, which loadfast cannot do.
  • Build the table type on Polars, linked as a Rust crate, and expose its columns to R and to native code as ALTREP vectors. Typed columns come from ry’s record types.
  • Share one type model between checker and runtime. The runtime consumes the checker’s types through a small, stable projection. Types are hints by default; in strict mode they become guarantees wherever a runtime check backs them.
  • Get real packages running first. The interpreter and the C API come before the JIT, the table type and the inline syntax, because nothing else can be measured until the benchmark code runs.

The scripts are in tools/research/. r_api_usage.py resolves the dependency closure of the benchmark’s Imports (following Depends, Imports and LinkingTo, recursively, but not Suggests) against CRAN, the extra repository ak-finccam.github.io/r-packages (which supplies azidentity, polars and Rblpapi), and the two GitHub remotes. It downloads every source package and scans the compiled code under src/ and inst/include/ for identifiers declared in R 4.6.2’s public headers (R.h, Rinternals.h, Rdefines.h, Rembedded.h, Rinterface.h, Rconnections.h, Rmath.h and every R_ext/*.h). r_api_summary.py turns the result into the figures below. The raw data is in tools/research/data/: symbols.csv has one row per name with its class, declaring header and the packages that use it, packages.csv one row per package, r_calls.csv the R-level foreign calls, and summary.txt the output every figure here is quoted from.

R classifies its own entry points, and the scan keeps that classification:

  • API and experimental are the names Writing R Extensions documents with @apifun, @apivar, @eapifun and @eapivar.
  • Embedding is the API for programs that embed R.
  • Non-API is the list tools:::nonAPI that R CMD check warns about.
  • BLAS/LAPACK is every routine declared in R_ext/BLAS.h, Lapack.h and Linpack.h. These are Fortran libraries to link against, not R API to reimplement, so they are reported separately.
  • Header is everything else declared in a public header: mostly types (SEXP, R_xlen_t), type codes (INTSXP), constants, the Rmath distribution functions and the graphics engine.

The scan is lexical, and its limits matter when you read the numbers:

  • A file counts only if it can see R’s headers. That means it includes one, or it is connected to such a file through the package’s own #include edges in either direction, which is how Rcpp’s umbrella header reaches the many files that use the API without including anything. A vendored C library that no R-facing file includes stays out.
  • Unprefixed names such as length count only where R would remap them. They do not count in C++ files (since R 4.5.0, R CMD INSTALL compiles C++ with -DR_NO_REMAP), in packages that define R_NO_REMAP, or for Rmath’s short names (dt, df, beta) in files that do not include Rmath.h.
  • Both branches of an #if are counted, so a fallback branch for an older R counts as much as the modern one. Names that R 4.6 removed from its public headers (TRUELENGTH, SETLENGTH, IS_GROWABLE) are not counted at all, so the measured surface is R 4.6’s, not what those fallbacks need.
  • A package-local macro that shadows an API name still counts as that name. Two known cases are data.table’s own BODY macro and simdjson’s OBJECT enumerator.
  • polars and azidentity fetch their Rust dependencies with Cargo at build time. Only the code in the tarball is scanned, which includes each package’s own glue but not savvy-ffi or libR-sys, where their calls into the API live.
Packages in the closure, base packages excluded 232
… whose compiled code uses the R API 121
Direct (non-base) dependencies 67; 36 ship code that uses the API (35 compile, and progress ships a header)
Compiled source lines: C / C++ / headers 1.21M / 0.64M / 3.97M
Compiled source lines: Fortran / Rust 24.7K / 11.6K

The header count is dominated by vendored libraries: BH (Boost), RcppArmadillo, stringi’s ICU and the SuiteSparse copy inside Matrix. That code never sees SEXP, but it has to compile and link, so ry’s package build must handle large C++ code bases and Fortran.

Most packages call the C API directly rather than through a binding layer:

Binding layer Packages
The C API directly 91
Rcpp 19 (rugarch, rmgarch, RcppDE, FLSSS, Rblpapi, RcppSimdJson, odbc, openxlsx, pdftools, httpuv, later, …)
cpp11 9 (readr, readxl, vroom, tzdb, systemfonts, …)
Rust 2 (polars through savvy, azidentity through extendr)

The closure uses 942 distinct names from R’s headers, 131,275 times in total. 150 of them are BLAS and LAPACK routines, which leaves 792 names of R API proper (130,074 occurrences). By class, 307 are API, 102 experimental, 5 embedding, 30 non-API and 348 header-only. Of the 570 names R documents as API or experimental API, the closure uses 409.

The most widely used names are the ones any implementation starts with:

Name Class Packages Occurrences
R_registerRoutines, R_useDynamicSymbols api 117 133 each
SEXP header 107 41,844
Rf_error api 83 5,836
R_NilValue api 82 2,429
PROTECT / UNPROTECT (Rf_protect / Rf_unprotect) api 79 / 78 5,092 / 3,144
Rf_allocVector api 77 2,791
INTEGER api 71 3,391
STRING_ELT api 70 1,717
CHAR (R_CHAR) api 68 1,449
Rf_length api 65 2,568
REAL api 61 3,777
TYPEOF api 59 1,333
SET_VECTOR_ELT / VECTOR_ELT api 50 / 47 1,635 / 1,519
Rf_setAttrib / Rf_getAttrib api 48 / 39 664 / 590
Rf_mkChar api 47 651
Rf_install api 45 843
Rf_eval api 38 195
R_RegisterCCallable api 25 276
R_ExternalPtrAddr api 25 469

But the distribution has a long tail, and the tail is not optional. 499 names are used by at least two packages, 249 by at least five, 145 by at least ten, and only 24 by fifty or more. The coverage curve shows what that means: if ry implemented the N most widely used names, this many of the 121 compiled packages would have every name they use.

Names implemented 25 50 100 150 200 300 400 500 all 942
Packages fully covered 2 5 9 19 24 33 43 62 121

Covering half of the compiled packages takes the 495 most widely used names. The curve charges a package with the names of every header-only layer in its LinkingTo as well as its own, which overstates Rcpp’s share: Rcpp’s headers mention 358 names, most of them Rmath distribution functions it wraps, and an unused inline wrapper never reaches a package’s binary. In their own code, the packages that use the most names are the ones the benchmark cannot do without: Rcpp (358), Matrix (257), vctrs (250), pak (237), rlang (233) and data.table (202). So the target is the public header set as a whole, and a “most common 200” subset would leave the core of the tidyverse and data.table unable to load.

Grouped by subsystem (by declaring header, then by name; the rules are in r_api_summary.py):

Subsystem Names Packages using any
Registration and cross-package C calls 8 117
Vector data access (INTEGER, REAL, VECTOR_ELT, lengths, resizable vectors) 50 96
Non-local exits, errors and interrupts 19 93
Allocation, coercion, duplication 24 85
Protection and GC 13 82
Strings and encodings 33 82
Math and RNG (Rmath, R_ext/Random.h, Arith.h, Applic.h) 172 77
Attributes, classes and S4 30 58
Evaluation, calls and pairlists 45 57
Environments, closures, promises 57 39
External pointers, weak references, finalizers 18 28
BLAS, LAPACK and LINPACK 150 10
ALTREP 31 9
Connections 5 5
Graphics engine and devices 112 5
Types, constants and everything else 175 121

A few interfaces are used by fewer packages but constrain the design far more than their counts suggest:

  • ALTREP (9 packages: cli, cpp11, data.table, lazyeval, pak, rlang, stringi, vctrs, vroom). Four of them define ALTREP classes of their own (vroom builds its lazily parsed columns on it, and cli, vctrs and pak define classes too), and the rest test for ALTREP objects or read them through the region and element accessors.
  • Cross-package C callables (27 packages register or fetch them with R_RegisterCCallable and R_GetCCallable, among them Rcpp, rlang, vctrs, xts, zoo, Matrix and data.table). xts calls zoo’s C functions this way (R_GetCCallable("zoo", "zoo_lag")), so native libraries must be able to find each other through the runtime.
  • External pointers and finalizers (27 packages). Every handle to a database connection, HTTP session, git repository or parser lives in one.
  • Non-local exits (15 packages use R_UnwindProtect, R_ToplevelExec, R_tryEval or their relatives). Rcpp and cpp11 call R_UnwindProtect directly so that C++ destructors run when an R error unwinds through their frames; savvy and extendr do the same for Rust from crates the scan does not see.
  • Connections (readr, vroom and xml2 read and write R connections; curl and pak create custom ones), which exposes the Rconnection struct layout, versioned by R_CONNECTIONS_VERSION.
  • Graphics (5 packages: ragg implements a device, and systemfonts, farver, later and pak use smaller parts). The device API can come late, but the graphics headers also declare Rf_ucstoutf8 and the interrupt-suspension macros, which rlang, readxl and later use, and Rcpp, rlang and vctrs include them, so the headers themselves and those few names are needed early.

At the R level, 104 packages call .Call (4,255 call sites), 18 use .C (443), 5 use .Fortran (127), and 8 use .External or .External2 (58). Three call .Internal directly (pkgload, processx, renv), which means ry must also expose some of base R’s internal entry points by name.

The non-API surface is shrinking, and ry should follow it

Section titled “The non-API surface is shrinking, and ry should follow it”

30 non-API names appear in the closure, used by 28 packages. The heaviest users are rlang, vctrs, lazyeval (which vendors rlang) and magrittr (promise and environment internals such as PRVALUE, SET_PRENV, ENCLOS), data.table (DATAPTR, LEVELS, IS_UTF8) and Rcpp (STRING_PTR, PRCODE, CLOENV, BODY).

Many of these uses are fallbacks. R 4.5 and 4.6 added API replacements for the internals packages used to reach for, such as R_ParentEnv, R_getVar, R_ClosureFormals and the resizable-vector functions R_allocResizableVector, R_resizeVector and R_mapAttrib, and the packages switched with version guards. rlang’s env.h returns R_ParentEnv(env) under #if R_VERSION >= R_Version(4, 5, 0) and ENCLOS(env) only otherwise, cli maps R_getVar to Rf_findVar only before R 4.5, and data.table 1.18 keeps its TRUELENGTH-based growable vectors only as a backport for older R. The TRUELENGTH family is no longer declared in R 4.6’s public headers at all.

So ry should present itself as R 4.6, which makes every guarded package take the modern branch. That means R_VERSION and Rversion.h, and also R_SVN_REVISION: data.table’s guard is R_VERSION < R_Version(4, 6, 0) || R_SVN_REVISION < 89077 (and < 89194 for R_mapAttrib), so ry must report a revision of at least 89194 or data.table takes the backport.

In practice the runtime runs the base R code of the GNU R installation its R home links, so ry presents that installation’s version. R.version, getRversion() and the home’s generated Rversion.h all come from its library/base/DESCRIPTION, and the revision is raised to at least 89194. Linked to R 4.6, ry presents 4.6 as recommended here. Linked to an older R, such as the 4.3.3 the corpus baseline runs on, it presents that version, because a package whose C code takes the 4.6 branches while its R code runs on a 4.3 base breaks (rlang’s ns_registry_env() is one example).

A real non-API surface remains after that, unguarded: the promise accessors in rlang, vctrs, lazyeval and magrittr and PRCODE/PRENV in Rcpp’s Promise.h, ATTRIB and SET_ATTRIB, IS_UTF8 and IS_ASCII in stringi, fansi and data.table’s forder.c, Rf_findVarInFrame in S7, BODY in Rcpp’s Function.h, OBJECT in reshape2 and R_Outputfile in Rmpfr. later declares R_GlobalContext itself rather than taking it from a header. ry should implement all of these, because a package that does not load is a failed benchmark, whatever R core’s policy says.

SEXP is opaque. Since R 4.2.0, defining USE_RINTERNALS no longer exposes R’s internal structures. In R 4.6’s Rinternals.h, SEXP is typedef struct SEXPREC *SEXP with no definition of the struct, and every accessor (INTEGER, LENGTH, TYPEOF, CAR) is a function. A compiled package therefore depends on R’s function ABI, not its object layout, which is what makes an ABI-compatible reimplementation possible at all.

What native code does rely on, and ry must keep:

  • Pointer identity. Code compares x == R_NilValue, compares symbols by pointer after Rf_install, and compares CHARSXP strings by pointer, because Rf_mkChar returns the one interned copy of each string. So handles must be canonical: one object, one pointer.
  • Stable, writable data pointers. INTEGER(x) returns a pointer into the vector’s storage, and code keeps it across later allocations and writes through it. Objects reachable from native code must not move, and a pointer handed out by a writable accessor must point at memory that native code may write.
  • Writes that ignore reference counts. Correct code checks MAYBE_SHARED before mutating, but some code mutates in place on purpose: data.table’s :=, set() and setattr() write into the object they are given. The runtime cannot assume a vector’s contents survive a native call.
  • Precise rooting through PROTECT. An unprotected object may be collected at the next allocation, and correct packages protect everything they keep. PROTECT_WITH_INDEX, R_PreserveObject and the protected slot of an external pointer are the other roots.
  • Pairlists. Calls (LANGSXP), .External arguments and attribute lists are walked with CAR and CDR, so these stay linked lists at the boundary.
  • Value semantics by reference count. Since R 4.0, copy-on-modify uses reference counts, and packages check MAYBE_SHARED before mutating in place.
  • Struct layouts that are part of the API: Rcomplex, R_CallMethodDef and its siblings, Rconnection (versioned), the graphics DevDesc, ALTREP class handles, and the bit patterns of NA_integer_ (INT_MIN) and NA_real_ (a NaN with payload 1954).
  • longjmp errors. Rf_error never returns; it jumps to the nearest context. Code between the error and the handler is skipped without running destructors, which is why C++ bindings wrap their calls in R_UnwindProtect.

None of this pins down how ry stores an object internally. The constraints are on the objects native code can reach, which are exactly the objects passed to or created by it.

ry should ship a shared library that exports R’s public function and data symbols with GNU R’s calling conventions (libR.so, libR.dylib, R.dll), plus a header set that is source-compatible with R 4.6’s. Packages are built with ry’s headers, and binaries built against GNU R’s headers load too. The alternative, source compatibility only, saves almost nothing, because the opaque SEXP already forces ry to provide every accessor as a real function. What ABI compatibility adds is the data symbols (R_NilValue, R_GlobalEnv, R_NaInt, R_NamesSymbol, …), stable struct layouts for the few structs above, and the exact type-code numbering. In return it buys three things:

  • Prebuilt binaries. Posit Package Manager and r-universe ship compiled Linux, macOS and Windows binaries. Being able to install them skips compiling stringi’s ICU, Boost-heavy and Armadillo-heavy packages, which is the slowest part of setting up the benchmark environment.
  • A differential oracle. The same compiled package binary can run under GNU R and under ry, so a behavioral difference is ry’s bug, not a build difference.
  • A migration path for users, who can point an existing library tree at ry.

The cost is that ry’s internal object header is free, but the handle it hands out is a raw pointer to a non-moving object, so the GC design follows (section 4).

Every serious attempt at a faster R either forked GNU R, and inherited its C API for free but also its limits, or reimplemented R and then struggled with packages. That pattern is the main lesson.

Project Approach Native packages Outcome
GNU R + compiler AST interpreter plus a stack bytecode compiler (Tierney), JIT on by default since R 3.4.0 Native: it is the API The baseline; the bytecode removes interpretive overhead on scalar loops but keeps R’s environments, promises and boxed values
pqR (Neal) Fork of R 2.15 with a faster interpreter, deferred evaluation on helper threads, and lower allocation Native, as a fork Real speedups, but it never followed mainline R, so it fell behind the packages
CXXR / Rho Incremental C++ rewrite of R’s internals, later with an LLVM JIT Kept R’s API by construction Discontinued
Riposte (Talbot et al.) Tracing JIT and parallel VM for vector code None Research prototype; showed large gains from fusing vector operations, beside scalar trace compilation
Renjin JVM interpreter; GCC-Bridge compiled C and Fortran to JVM bytecode Recompiled, with no raw memory model No longer maintained; packages relying on pointer-level behavior broke
FastR (Oracle) Truffle AST interpreter with Graal partial evaluation Emulated C API over Java objects, so a raw data pointer required native memory to be kept in sync with the Java-side vector Large speedups on R code, but the native boundary was slow and incomplete; no longer actively developed, last release 22.3
TERR (TIBCO, now Spotfire) Closed-source clean-room engine from the S-PLUS lineage Own implementation of the C API Commercial and still shipped; checks CRAN compatibility on every release, which is the cost of not being a fork
Ř / rir (Vitek group) Bytecode tier plus an optimizing tier with an SSA IR (PIR), speculation, deoptimization and contextual dispatch, LLVM backend Native: built on a patched GNU R Large speedups on R-level code in the published evaluations; remains a research VM tied to its GNU R base
rcp (Kocourek, Křikava, Vitek, 2025) Copy-and-patch JIT from GNU R bytecode, as a package Native, inside GNU R 1.15x to 1.91x over GNU R on 57 programs, at about 980 bytecode instructions per millisecond of compile time

What carries over to ry:

  • The C API is the gate. FastR and Renjin had excellent engines and lost on packages, because emulating raw pointers (copying data out to native memory, or translating C to the JVM) was slow and leaky. ry avoids that by making its native representation the real one: an R vector is a contiguous buffer that INTEGER() returns directly.
  • Forks do not keep up. pqR and Ř get the API for free but cannot follow upstream R. ry should not fork GNU R’s C sources. It reimplements the runtime, and treats GNU R as an oracle, not a codebase.
  • Most of R’s cost is semantic, not instruction dispatch. Ř’s papers show that the wins come from removing environment allocation, promise creation and argument matching through speculation and deoptimization. rcp’s 1.15x to 1.91x for a fast template JIT is consistent with it: compiling R’s bytecode faster does not remove the R semantics it encodes.
  • Riposte’s lesson is that vector code wants fusion (sum(x * y + z) without temporaries), which a scalar JIT does not give you.
  • TERR shows the reimplementation path is viable commercially, at the price of a permanent compatibility test against CRAN. ry should build that test from day one (section 10).

The runtime is Rust, in new crates beside the analysis: heap for the object model and GC, one for the interpreter and the base library, one for the JIT, and libr for the C API. libr builds the shared libR and contains a small amount of C, for the reason in “Errors across the boundary” below. Because a package built against GNU R records libR.so as a needed library, libR is the whole runtime: the interpreter and the JIT link into it, and the ry binary loads it. The repl crate drives both: GNU R behind ry R, and ry’s runtime behind ry run.

Every R value is a heap object with a header that ry defines: type code, flags (object bit, S4 bit, named or shared bits), a reference count, the attribute pairlist and the GC bits. Vectors store their elements inline after the header, so INTEGER() and REAL() return a pointer into the object. Long vectors use R_xlen_t lengths throughout.

  • Interned strings. CHARSXPs live in a global, weakly held intern table keyed by bytes and encoding, so pointer equality means string equality, as native code expects. Encoding flags (IS_UTF8, IS_ASCII) are stored at interning time. The table is one open-addressed array of slots that pack each address with hash bits, so a lookup touches a string only when the hash bits match and its cost does not grow with the number of live strings.
  • Symbols are interned SYMSXPs with a cached global binding cell, which is what makes base function lookup and JIT watchpoints cheap.
  • Pairlists are kept for language objects, attributes and .External arguments, because native code walks them. Ordinary function calls inside the interpreter never build them.
  • Environments are a hashed frame of binding cells, with a fast path for small frames. A binding cell is a heap object of its own holding the symbol, the value and the active-binding and locked flags, so its address is stable for as long as anything references it and the JIT can watch it for redefinition. The base environment’s cells hang off the symbols.
  • ALTREP is native. An ALTREP object is a vector whose methods table decides length, element access, region access and dataptr materialization. Package-defined classes use the R API; ry’s own compact sequences, memory-mapped vectors and table columns (section 6) use the same mechanism. The interpreter reads an element of a long ALTREP vector through its Elt method, so x <- seq_len(2^31 - 1); x[c(1, 2^31 - 1)] reads two elements instead of expanding 8 GB.

The GC is a non-moving, generational mark-sweep collector with size-segregated pages, which is the design GNU R uses, kept because native code holds raw pointers to object data. Reference counts drive copy-on-modify exactly as MAYBE_SHARED expects. The roots are the PROTECT stack, the precious list behind R_PreserveObject, global variables, the interpreter’s frames, and JIT frames through Cranelift’s stack maps. A minor collection marks only the root-stack entries pushed since the previous collection, because marks stay set until the next major one, so the cost of a minor collection does not grow with the roots that lazy-loading base leaves behind.

Collections run on GNU R’s schedule, so a script’s peak memory follows GNU R’s. Objects age one generation per collection: a minor collection makes a young survivor old, and a deeper collection makes an old survivor tenured. An intermediate collection frees dead old objects that are not yet tenured and takes tenured ones as roots through the remembered set. A major collection frees everything dead. The heap has two limits, as GNU R’s R_VSize and R_NSize do: one on large vectors (at least 64 MB) and one on small objects (at least 32 MB). When a minor collection leaves less than a fifth of a limit’s minimum free, an intermediate collection runs, then a major one if that is still not enough. An intermediate collection is skipped when it would not free enough: the share of the younger old objects (old but not yet tenured) that the last intermediate collection found dead predicts what it frees now, so a program that keeps what it builds goes straight to the major collection instead of tracing its young structure twice. A major collection does not update that share, because a dead tenured object keeps its younger children alive for an intermediate collection, and after four predicted major collections in a row an intermediate one runs anyway to measure again. After each major collection the limits move with GNU R’s fractions: a limit grows by a fifth when the survivors plus that fifth fill more than 70% of it, and shrinks by a fifth when they fill less than 30%. A major collection that escalation forced before the program allocated a limit’s worth of vectors grows the vector limit too, because the working set it keeps promoting is larger than the survivors show. GNU R’s R_GC_MEM_GROW and its fraction variables set the same numbers (CLI reference). The nursery’s budget for small objects scales with the old small objects only, as GNU R’s cons-cell trigger ignores vector memory, so a few big live vectors do not let as many bytes of small garbage pile up.

R_PreserveObject sets a flag bit in the object’s header and appends the object to a dense vector of preserved objects with their counts, so a frame release asks the header, not a hash table, whether native code preserved the environment or one of the promises the frame holds. R_ReleaseObject searches the vector from its newest entry, as GNU R’s precious list does.

The write barrier is one load and one compare on the parent’s header: a store into a young object, or into an old one that is already remembered, does nothing more. An old object that receives a younger child joins the remembered set, and a minor collection rescans only what in it can point at young objects. A list or character vector too large for the small-object pages (2 KB) keeps one card byte per 128 elements after its data, so its stores keep reaching the barrier while it is remembered and the rescan visits only the dirty cards. An environment’s spilled frame keeps a watermark instead, because its bindings are only appended or compacted: the rescan marks the cells appended since the last scan, which keeps a namespace that is filled during a load from being rescanned whole at every collection.

Native code gets no barrier, so its element pointers escape. Every C API function that hands out a pointer into a list’s or character vector’s elements (DATAPTR, DATAPTR_RO, DATAPTR_OR_NULL, STRING_PTR, STRING_PTR_RO, VECTOR_PTR, VECTOR_PTR_RO, an ALTREP class’s Dataptr or Dataptr_or_null over such a vector) marks the vector escaped, read-only pointers included. Packages write through read-only pointers: data.table’s setcolorder and setorder permute columns and character data with memcpy through DATAPTR_RO. GNU R remembers a whole object, so a permutation inside one vector is harmless there, but ry remembers per card, and moving a young element from a dirty card to a clean one hides it from the next minor collection, which then frees it. Every collection marks all of an escaped vector’s children (a minor collection does so for a character vector by marking every young string), and a writable pointer to an old vector remembers it at once, because native code may store a young element through it. When the outermost native call returns, an old escaped vector that may hold a younger child has all its cards marked dirty and joins the remembered set, so the next minor collection rescans it once and its later stores go through the barrier again. It may hold one when it is remembered (which covers barriered stores and writable pointers) or when a collection ran during the escape, which can age its children without remembering it. Any other old vector held only old children throughout, and permuting them cannot change that, so the read-only pointers data.table takes on every column it only reads cost no rescan. Deferring the rescan to the next collection, rather than rescanning at return, costs one scan however many native calls touched the vector between two collections. RY_GC_VERIFY=1 checks this contract before every collection short of a major one (Robustness).

The escape lasts until the outermost native call returns, so a pointer native code keeps after that, across two .Calls or taken by an embedding host outside any call, is unprotected if it later moves elements.

Reference counts are settled per list, from an entry the escape records. A writable pointer takes a snapshot of the list’s elements, because native code may replace elements uncounted, and the retirement counts what the list then holds and releases what the snapshot names. A SET_VECTOR_ELT into that list in between counts the new value at once, so copy-on-modify sees it shared, and adds it to the snapshot; the value it replaced keeps its count until the retirement releases it. Collections keep every value the snapshot names allocated until then, which RY_GC_VERIFY=1 checks. A read-only pointer records only a digest of the elements that ignores their order, because permuting them leaves the counts right and copying a large list on every DATAPTR_RO would cost more than the call that reads it. If the digest differs, native code stored something other than a permutation through the read-only pointer, and every element the list then holds is counted once more: the counts err high, which keeps objects alive and makes copy-on-modify copy, but never frees anything still held. The first counted change to such a list (a SET_VECTOR_ELT or a resize) checks the digest that way and takes the snapshot, because a counted store releases what the slot held, which native code may have put there uncounted. A resize of a list with a snapshot leaves the dropped slots to the retirement. A list that dies, or whose elements move to a grown list, before its escape retires is settled from the same entry. Pointers into atomic vectors need none of this, because their elements are not objects.

A lazy-load fetch allocates pretenured: what it reads is a package’s functions and data, which live as long as the session, so a minor collection would trace them only to promote them. Small objects come from separate allocation runs whose pages hold no young objects, and no collection runs while a fetch reads. Their bytes stay out of the nursery’s budget, which bounds young garbage, and count toward the small-object limit once flushed. The next collection flushes them: it makes them old and marked, and remembers each one that points at a young object. Stores into a pretenured object pass no barrier before that flush, because the object still looks young, so the flush’s check of every child is what keeps the remembered set exact. A large object is made old when the fetch ends, with the same check. R code that the reader calls (a namespace or package hook) allocates young, since its temporaries are garbage.

Vectors of 1 MB or more get an anonymous mapping each. A dead one’s mapping is kept for the next large vector while the kept mappings fit the vector limit, and resized with mremap, so a loop’s temporaries reuse resident pages instead of page-faulting in fresh ones. Keeping them never raises the peak, because a kept mapping is reused before any new one is mapped.

Reference counts also free large temporaries before any collection finds them. A store that drops a list’s or a large atomic vector’s count to zero puts it in a zero-count table, and once the table’s vectors add up to 4 MB, the next allocation reconciles it. Reconciling marks the roots one level deep (the protect stack, the precious set, handles, the interpreter’s frames and bytecode registers, the fields of objects whose stores do not count, and the elements of lists native code has seen). Then it frees each entry still at zero and unmarked, so a dead list gives up its elements and a dead large vector’s mapping goes back at once. It runs only at an allocation because C code may hold an unprotected SEXP until its next one. Environments, closures and promises stay with the tracing collector, which also takes care of cycles. Counts only ever overcount, so a missed decrement leaves an object to tracing and never frees one early. RY_GC_VERIFY=1 makes a reconcile free nothing and run a full collection instead, which panics if the collection reaches an object the reconcile would have freed.

Vectors of a megabyte or more get an anonymous mapping each (crates/heap/src/large.rs), which goes back to the kernel when the vector dies, as glibc’s mmap threshold returns GNU R’s large vectors. libR’s global allocator does the same for its own blocks of that size, so the buffers a builtin fills before copying them into a vector go back too. A small pool of freed mappings, resized with mremap, saves the next vector’s page faults. It holds at most a quarter of the collection limit, and when no kept mapping is long enough for a new vector it grows the longest and unmaps the rest, so it never holds memory idle while a vector adds pages. Between those moments the idle mappings do count toward resident memory, and a major collection trims the pool to its limit.

The JIT recovers what a moving nursery would buy in other VMs by not allocating in the first place: unboxed scalars, scalar-replaced temporaries, and vectors fused across a loop (section 5). If profiling later shows fragmentation, Immix-style regions with opportunistic, pinning-aware compaction of objects that native code has never seen are the upgrade path, and they need no API change.

Native calls get a handle scope. Every object passed into .Call stays alive until that call returns, and so do the objects the API most recently handed to native code: at least the last 1,024 of them, as if they were protected. This makes ry strictly more forgiving than GNU R (code that forgets to PROTECT a recent temporary keeps working, where GNU R could collect it at the next allocation) while PROTECT itself keeps its exact semantics for objects that outlive the call through globals or preserved references. A loop that allocates and drops millions of temporaries still runs in bounded memory, because older handouts leave the scope. The scope roots results, not allocations, so the temporaries of an Rf_eval that native code calls stay collectable, and a result reachable through the argument it was read from (a list element, a cell’s CAR, an attribute) takes no handle at all. A view ry builds of something GNU R stores in the argument, such as FRAME’s pairlist, stays rooted until the call returns, because correct code walks it unprotected. Each native call also owns a region of the PROTECT stack: unprotecting below it is an error, and a region left unbalanced on return is a warning and is cut back.

Hot accessors are inline. Rinternals.h defines INTEGER, REAL, LOGICAL, RAW, COMPLEX, their _RO and _ELT forms, DATAPTR, DATAPTR_RO, STRING_ELT, VECTOR_ELT, TYPEOF, LENGTH, XLENGTH, Rf_length, Rf_xlength, Rf_isNull, R_CHAR, CAR, CDR, TAG, CADR, CDDR and CADDR as inline functions that read the object header and fall back to libR for anything unusual (an ALTREP instance, a wrong type, an index out of bounds). DATAPTR and DATAPTR_RO are inline for atomic vectors only, and STRING_PTR_RO is not inline at all, because a pointer into a list or character vector must reach libR to escape the vector (see the write barrier above). A package built against older ry headers inlines those pointers, so ry refuses to load it until it is reinstalled (RyAbi:, in Packaging). The exported functions take the same fast paths before entering the API, so binaries built against GNU R’s headers benefit too. A package that defines RY_NO_INLINE_ACCESSORS gets plain calls.

Ready finalizers run when a native call returns and on R_gc, not inside the collection that found them, because a collection happens deep inside an allocation, where no native code may run.

R_alloc is an arena. R frees R_alloc memory when the .C, .Call or .External call that allocated it returns, and vmaxget/vmaxset let code reset it earlier, so it is a stack of nested watermarks. ry implements it as a bump allocator that keeps R’s alignment and restores the watermark on return and on a longjmp.

Interpreter hot paths make no Rust allocations. Every R object comes from the heap’s own allocator, so a Rust Vec or String that lives only for one call is pure overhead: a malloc, a free, and a cache line the next call does not reuse. Three rules keep them off the hot paths:

  • A list that is usually short lives on the stack (SmallVec), such as the dims of an array, a match’s capture groups, a parsed gsub replacement and the pieces of a strsplit element.
  • Data that already exists is borrowed: a pattern is looked up by &str, a replacement refers to slices of its template, and return() or break unwinds with the jump inline in Unwind.
  • Text of unbounded length is assembled in one scratch buffer the interpreter owns (Interp::text_buffer, through strings::with_text_buffer). It is an explicit allocator, not a thread-local cache: each use takes it, clears it and puts it back, so a nested use gets a fresh buffer and the outer one is never clobbered.

A pairlist result is linked cell by cell as it is built (PairlistBuilder), with the head rooted, instead of collected into a vector first. A handler that withCallingHandlers or tryCatch establishes comes from a pool of at most 64 entries on the interpreter, and returns to it when its frame exits unless something still shares it. crates/interp/tests/test_rust_allocations.rs pins the property: it runs pinned shapes (return(), break, c(), group dispatch, sprintf, paste, gsub, handler setup and others) warm under a counting allocator, and each must stay within its budget. The budget is zero for all but two shapes: gsub with capture groups, whose regex engine allocates one capture set per match, and mapply, whose closure calls build their call and frame through the general call protocol.

R signals an error with longjmp, and a longjmp across Rust frames is undefined behavior. So the boundary is a thin C layer with two directions:

  • ry calling native code (.Call, .External, ALTREP methods, finalizers, C callables) goes through a C trampoline that sets up a jump target. A native Rf_error or an R error raised in a nested Rf_eval jumps back to the trampoline, which returns an error value to Rust.
  • Native code calling ry (every API function) enters Rust through a wrapper that catches the Rust-side error (and any panic), drops everything, and only then calls the C function that performs the longjmp to the innermost native context. The jump skips only the wrapper’s frame and the exported function’s, which hold nothing with a destructor at that point. No Rust frame with pending destructors is ever crossed.

R_UnwindProtect, R_ToplevelExec, R_ExecWithCleanup and R_tryCatch are C contexts of their own, because the callbacks native code hands them are native code too, and a C++ exception that a binding throws from an R_UnwindProtect cleanup to run its destructors must unwind only C frames. R_tryEval is plain Rust, because inside Rust an error is already a value. R conditions, restarts and on.exit are implemented natively in Rust, with the C layer only as the bridge. The variadic functions (Rf_error, Rprintf and their family) are C too, because stable Rust cannot define a C variadic function.

Package libraries load with dlopen, then R_init_<pkg> runs and registers its routines. useDynLib resolves registered symbols first, and C callables live in a global table keyed by package and name. ry builds source packages itself (R CMD INSTALL semantics, Makevars, the compiler flags R CMD config reports), and installs prebuilt binaries when the platform matches.

A package library built by GNU R must bind its API calls to ry’s libR, not GNU R’s. On Linux it names its dependency by soname, libR.so, and ry’s library carries that soname and is loaded with RTLD_GLOBAL first, so the dynamic loader reuses it. Mach-O binds each symbol to a named library instead (the two-level namespace), and CRAN’s binaries name /Library/Frameworks/R.framework/Versions/4.x-arm64/Resources/lib/libR.dylib while Homebrew’s name its own libR.dylib. ry therefore loads a copy of each such library whose libR load command is rewritten in place to @rpath/libR.dylib, the install name of ry’s libR.dylib, and re-signed ad hoc (crates/libr/src/macho.rs, crates/libr/src/dynload.rs). dyld matches that load command against the already loaded image with the same install name, so the package binds to ry. A dependency the package finds relative to itself must resolve from the copy too, so the cache mirrors the original’s surroundings with links: the copy’s directory links to every file beside the original, and when a load command or rpath climbs (@loader_path/../lib), as many ancestor directories are mirrored as it climbs, each linking to the original’s entries. Packages that rcmd builds on macOS link with -undefined dynamic_lookup and record no libR at all, so the same build loads under ry and under GNU R. decisions/libr-rcmd.md (“macOS packages bind to ry’s libR”) has the reasoning.

Windows needs no rewriting. A package DLL that Rtools built imports from R.dll by module name, and the Windows loader satisfies that from an already loaded module with the same base name, so naming ry’s library R.dll and loading it first is enough. Package DLLs load with LoadLibraryExW and LOAD_WITH_ALTERED_SEARCH_PATH, so a package’s own dependent DLLs in libs/x64/ resolve.

R’s API is single-threaded, and so is ry’s R-level evaluation. Packages such as RcppParallel, data.table (OpenMP) and polars run threads that never call the API, which needs no support beyond the API not being reentrant. parallel, callr, future and doParallel use processes, so ry must be a working Rscript replacement that worker processes can start.

Bun’s speed comes from three things, and only one of them is the JIT. JavaScriptCore runs four tiers (the LLInt interpreter, a baseline JIT, the DFG optimizer and the FTL backend) with inline caches, value profiling and watchpoints, so code warms up gradually and optimized code is invalidated when an assumption breaks. Bun adds fast startup (a transpiler cache by default, and opt-in bytecode caching with bun build --bytecode), and it implements its hot builtins in a systems language instead of in JavaScript. ry’s equivalents are:

  • A fast first tier and bytecode built ahead of time, so ry run script.R starts in milliseconds and a package’s compiled code is reused across sessions (see “Where bytecode comes from” below).
  • Base R’s primitives in Rust, with vectorized kernels (SIMD where it pays) for arithmetic, comparison, subsetting, sum, cumsum, match, order and paste. Much real R code is a sequence of calls to these, and no JIT can make a slow primitive fast.
  • An optimizing JIT for the R code in between, which is what the rest of this section is about.

Where ry stands against that bar on untyped code: the application workloads (just bench applications: S3 objects, conditions, validation, strings, lapply pipelines, records, tables, xts and zoo, and a testthat suite of small test_that() blocks) run faster than on GNU R, but far from the bar (benchmarks.mdx has the current geometric means). The rest is decided by tier 0, the call path and builtins, because their hot closures run a few hundred to a few thousand times, under tier 1’s threshold. A user’s profile of a package test suite agrees: builtins 33% of the time, tier 0 26%, call setup 22%, GC 8%, and compiled code under 1%, with every closure running inside testthat’s calling handlers. The testthat workload stands in for that suite.

Bytecode is build output, never a cache, so nothing checks whether a stored copy is still valid:

  • Installed packages. ry install and R CMD INSTALL compile every closure of the package and write the bytecode beside its lazy-load database, stamped with the ry build that wrote it. A different ry build ignores a stamp it did not write and compiles at first call instead, which is always correct; reinstalling refreshes it. This is the code image, described below.
  • Base R. The base and recommended packages are compiled when the base image is built and live in a section of the image beside the heap arenas, keyed by the same runtime hash that keys the image (base-image.md).
  • Code under development. ry load and scripts compile each closure at its first call. That first tier must be cheap enough that compiling a session’s working set costs less than reading a cache would, which is the bar ry load’s lazy loading sets.

Compiled code calls the base functions GNU R’s compiler inlines (+, <-, if, [, c and the rest of its 233 inline handlers) without looking them up, exactly where GNU R 4.6.2 at its default optimization level would have compiled the code. A function that masks one of them afterwards does not reach that code, as in GNU R:

minus <- function(a, b) base::`-`(a, b)
total <- 0
for (i in 1:40) {
if (i == 10) attach(list(`+` = minus), name = "masking_plus")
total <- total + 1
}
print(total)
#> [1] 40

When GNU R compiles. ry follows R_CheckJIT, with the JIT_score of the body (a loop scores MIN_JIT_SCORE, 50):

closure score ≥ 50 score < 50
over the global environment first call second call
over any other environment second call never
in a namespace first call second call

GNU R installs a package’s closures compiled; ry compiles them at their first call with a loop and otherwise at their second, binding as GNU R’s installed code does. A loop the tree walker evaluates in the global environment compiles when it starts. A function defined inside compiled code compiles with it, against its compile-time frames. A closure GNU R never compiles compiles at its second call, and a typed one at its first, with a guard on every base function it inlines, so it looks each name up as it runs.

Closures over one body. Every closure made from one function expression shares the body, and so do R6’s copies of each method. Code compiled for one of them serves the others whose formals and srcref are the same, from their first call. Guarded code serves any closure that would also guard. Code that binds serves a closure only under GNU R’s jit_env_match: its top environment is the one the code compiled under, and every name its formals and local frames bind was bound in the compiling closure’s frames too. A closure that masks a base function in its own frames therefore never runs a sibling’s code that bound it. It compiles its own code with guards, as GNU R marks such a closure never to compile.

What binds. At compile time, a call binds to base when its head is a symbol that is not one of the function’s locals (GNU R’s findLocals: formals, <-, =, for variables, literal assign targets) or an enclosing compiled function’s, and whose first binding outward from the enclosure is:

  • in a namespace’s code, base’s binding, for any inline handler;
  • elsewhere, baseenv()’s binding for one of GNU R’s languageFuns (+, <-, if, function, [ and so on); a mask in the global environment or an attached frame keeps the call dynamic.

:: and ::: never bind, local binds only with one argument, and function does not bind when its body may call browser. Everything else looks the function up as it runs, including every name without an inline handler (sqrt, paste).

Known differences. Promise code of a call’s arguments compiles when the call site first runs, not with its function, so it binds what the names find then, against the function’s locals only. GNU R’s JIT also shares code between two global closures whose bodies are structurally equal, so the later one inherits the earlier one’s bindings; ry compiles each body object on its own. Pinned by the oracle case base__compile_time_binding.

R CMD INSTALL writes R/<package>.<build>.ryc beside R/<package>.rdb (crates/interp/src/code_image.rs). After the R code is installed, a fresh session loads the namespace, fetches every binding from the lazy-load database, and compiles each closure the fetches made, nested function bodies included. When a later session fetches the same record, it notes where each closure’s code lies in the image, and the call that would compile the closure (its second, or its first when the body has a loop) decodes that code instead. Decoding costs about as much as compiling, so the image does not move compilation earlier: a namespace fetches many closures it never calls, such as every S3 method it registers, and calls many others only once. What the image adds is what compiling cannot produce, the trained profile below. An image holds no machine code (decisions/jit-ssa.md, “No baseline tier, and code images hold bytecode only”).

  • Identity. A record is identified by its offset and length in the database, and a closure within the record by the order the stream reader creates closures. The image is stamped with the database’s length and modification time, so an image written for another database (a reinstall by GNU R, another version) is ignored whole. A copy that does not keep modification times loses the image, never serves a stale record.
  • Streams. The image also holds the serialized stream of every record the install fetched, uncompressed, after the payloads. A fetch from a database with an image reads that stream in place from the mapped file: it does not read the database, inflate the record or copy it, and processes that load the same package share the pages. A record the install did not fetch is read from the database. Each stream carries a hash that is checked the first time the stream is read (stream_hash, a word-at-a-time hash, since only one build ever reads the image); a mismatch is damage, below, and the fetch reads the database instead.
  • No copy of the source. A code object points into its closure’s body, so the image stores those pointers as the preorder position of the object in the body. The body itself comes from the database, as without an image.
  • Stamp. The file starts with a layout magic and the runtime build’s identity; any other build reads the image as absent and compiles at the second call as usual.
  • Formals. The compiler’s output depends on the closure’s formals as well as its body (which names the frame can bind, which call updates its first parameter in place), and formals<- or as.function makes a closure that shares a fetched body under other formals. Each noted closure therefore keeps its formals, and only a closure with those same formals takes the code; any other compiles its own.
  • Damage. The image only saves compiling, so a damaged one never stops a package from loading. A file that cannot be read or parsed, a payload whose hash does not match (checked when the first closure of its record is called), a stream whose hash does not match, a record whose closures do not match the database’s, or code the decoder rejects each print one warning to the console (cannot use the code image ..., so its functions compile as they run; reinstall the package to repair it). The warning is not signalled as a condition, so neither a handler nor options(warn = 2) can turn the damage into an error. The image is then ignored for the rest of the session, and its waiting code is dropped.
  • Verified code. Tier 0 reads instruction operands, registers, inline-cache slots and jump targets without bounds checks, so decoded code passes a linear verifier (verify in crates/interp/src/bytecode.rs) before it runs: every opcode is known, every operand is below its table’s size, every jump lands on an instruction start, the last instruction cannot fall through, and the side tables (loops, feedback, hints, profile) have the lengths the code implies. The payload hash is FNV-1a, which catches damage but not a crafted file, so the verifier is what keeps a bad image from reading out of bounds. It checks tier 0’s assumptions only: an instruction’s register dataflow is guarded at run time where that is cheap, and the optimizing tier trusts the shape the compiler produces. Record instructions carry process-local layout ids, so code that holds one is not written, and field and item shape caches are written empty. The decoder also keeps only the object bits the encoder can write (the S4 bit) of each constant.
  • Lifetime. Waiting code holds its body, its formals and the mapped file. lazyLoadDBflush, which unloadNamespace calls, drops all three for its database.
  • Writing. The image is written to R/<package>.<build>.ryc.partial, synced to disk, and renamed over the old image, so a crash leaves the old image or the new one. It is never rewritten in place: a process that maps the old file would see its pages change under it, or die with SIGBUS once the file shrank. A failed write removes the staging file.
  • Off switches. RY_CODE_IMAGE=0 ignores images when loading; R CMD INSTALL --ry-no-code-image writes none. A failure while writing an image warns and installs the package without one.

The image is uncompressed and about six times the size of the compressed database (MASS: 706 KB against 120 KB). It is mapped, not read, so a session pays only for the pages of the records it fetches.

Tier 0 is a register-based bytecode interpreter. A closure body compiles to bytecode at its second call, or its first if it has a loop, unless its bytecode was built ahead of time. Calls count per body expression, not per closure, and the compiled code belongs to the expression: every closure made from one function expression, and every copy environment<- makes (as R6 does for each object’s methods), runs it from its first call when its formals and srcref are the same objects. The code is freed with the last closure that runs it. A body changed in place through the C API compiles again for new closures, as in GNU R’s JIT cache. Each call site, variable lookup and arithmetic operation carries an inline cache and a small type profile: observed SEXPTYPE, length one or not, attributes or none, NA seen or not.

Tier 0 gets its speed from facts fixed before the code runs, not from caches that have to be checked and refilled:

  • Op words carry their operand count. Each instruction word holds the opcode in its low 8 bits and the operand count above them, so the next instruction’s position is one shift and one add, with no table lookup.
  • One dispatch loop. interpret in crates/interp/src/bytecode.rs keeps the frame, the code, the registers and the heap in locals for the whole run, and an error leaves the loop through one exit (the tri! macro) that hands it to the code’s handler table. Single-stepping for the debugger is the same loop, compiled with SINGLE = true.
  • Slot hints. Every call of one function binds its formals and locals in the same order, so a GetVar or SetVar site remembers the position in the frame where it last found its symbol. The frame’s symbol filter is checked first, because most probes miss, and a hint that no longer matches falls back to a search and is updated. A wrong hint costs a search, never a wrong answer.
  • Lookups skip function frames. A function lookup past the local frame walks only the frames that can bind the symbol, using the same hints.
  • The call entry reads its fixed facts raw. The compiler builds the constant pool and the vectors in its fixed entries (register count, profile, feedback, slots), so none is ALTREP and the entry indexes them directly. The tiers’ schedule is checked against one counter, and only a call that reaches it leaves the inlined fast path.
  • A new register window is cleared. Each call’s window is filled with NULL when it grows, so a register the frame has not written yet never holds what an earlier call left there, and a collection inside the window frees exactly what GNU R would.
  • Base .Internal wrappers are inlined. A call of one of GNU R’s “safe base internals” (nchar, typeof, inherits, identical, match, rep_len, vector, which.max and the rest of the list in GNU R’s cmp.R), or of a frame-free wrapper ry adds (paste, paste0, sprintf, character and the rest of the vector family, startsWith, make.unique, .row_names_info), compiles to a guard that the name still means base’s closure, the internal’s arguments evaluated in the caller, and the internal called directly. It applies only when the closure’s body is exactly .Internal(f(...)) over its formals and literals, and every default is a constant. A ... formal takes the arguments R’s matching gives it and is passed on as the internal’s own arguments (sprintf) or as list(...) (paste). The internal sees base’s namespace as its environment, as it would from the closure’s frame, and reports errors and warnings against the original call, so a message reads Error in nchar(x, ...) as in GNU R. A failed guard makes the ordinary call, so a replaced base binding is always reached, where GNU R’s compiled code keeps the original.
  • Builtin checks are derived at registration. Arity, names, replacement form and which arguments a builtin accepts as native values are computed once per builtin (Checks in crates/interp/src/builtins.rs), so a call does not re-derive them from the builtin’s name.

Tier 1 is an optimizing compiler on Cranelift. Hot functions and hot loops (through on-stack replacement) compile from bytecode to an SSA IR with R-specific operations, in the style of Ř’s PIR. The IR represents environments, promises and boxed values explicitly, so they can be optimized away:

  • Speculation with deoptimization. The compiler assumes what the profile and the static types say (this x is a length-one double without attributes, + is base +, f is the closure seen before) and guards each assumption. A failed guard rebuilds the interpreter frame, including any environment and promises it elided, and continues in tier 0.
  • Watchpoints instead of guards for facts that change rarely: a binding cell for +, c or a package function carries a watch set, and redefining it invalidates the dependent compiled code.
  • Environment elision. A function whose body never reflects on its frame needs no environment object. Reflection is visible statically (environment(), sys.function, eval, assign, parent.frame in a callee that the compiler cannot see) and dynamically through the callee check.
  • Promise elision. An argument that is always forced, and whose expression has no effects, is evaluated eagerly, which removes the promise. This is where ry’s static analysis helps most, because effects and strictness are facts the checker can compute per function.
  • Unboxing and scalar replacement. Length-one vectors without attributes become machine integers and doubles. NA_integer_ is INT_MIN, so integer NA checks are a compare and overflow checks are the hardware flag.
  • Vector fusion. Element-wise chains over vectors of equal length compile into one loop, without intermediate allocations, writing into a result allocated once at its final size (construction in place, as in goose).
  • Reference-count elision. Inside compiled code, counts are tracked precisely and increments and decrements that cancel are dropped, as Roc does with Perceus. A binding in an elided environment still counts as a reference, so y <- x; x[1] <- 0 copies, and deoptimization rebuilds the exact counts. A loop like for (i in ...) x[i] <- v copies at most once, on entry if x is shared, and the per-iteration sharing check is hoisted out. Every elided count is materialized before a native call, and native code may write into any vector it is given (section 2), so the JIT assumes nothing about a vector’s contents across one.
  • Borrowed arguments. An argument the callee only reads is passed without touching its count, as Bend’s and Roc’s borrow inference do. This is a speculation: it applies only when the whole callee is compiled and visible, any call to unknown R code or to .Call or .External counts as an escape, and deoptimization restores the counts.
  • Bounds-check elimination over difference constraints between loop indices and vector lengths, as goose does, so for (i in seq_along(x)) y[i] <- x[i] runs without per-iteration checks. Only positive in-range subscripts are bounds facts; zero, negative and NA subscripts, [[, and classed vectors with their own [ methods stay behind guards, and a fact about length(x) dies when x is rebound in the loop body.
  • Closure specialization at higher-order call sites. A call like vapply(xs, function(x) x * 2, double(1)) with a known closure compiles to a loop that calls it directly (ordinary callback inlining, inspired by Roc’s lambda sets), guarded so that reflection on the closure still works. This covers base R’s higher-order functions, which ry implements itself; purrr::map runs its loop in the package’s own C code, which the JIT cannot see into.

Cranelift is the right backend: it is a Rust crate, it was designed to compile much faster than LLVM’s optimizing pipeline, and it supports the stack maps the GC needs. LLVM would add a large C++ dependency and compile latency in exchange for low-level optimizations that matter less than the R-level ones above. A baseline tier between the two, in the style of V8’s Sparkplug, was built, measured and removed: tier 0’s dispatch is too small a share of the time for one to pay off (see the roadmap below).

crates/jit implements the core of this design for loops; the rest of the list above is still ahead. The JIT is on by default, and RY_JIT=off turns it off.

  • When it compiles. Tier 0 counts entries and backward jumps per body. A body compiles on its 3000th entry, and a running loop compiles after 10,000 backward jumps and continues in compiled code at the loop header (on-stack replacement). A body waits one more threshold per 250 instruction words before it compiles, because compile cost grows with size (about 10 µs per word, 200 ms for rbind) and the saving per entry does not, and the wait doubles with each recompile. Tier 0 records type feedback only over the last eighth of the entry threshold, from half the back-edge threshold, after a body’s compiled code is discarded, and in the first activation of a body with a loop; a body with compiled code records nothing. Each call compares its entry count with the one at which the next tier decision is due, so a call with no decision due costs one comparison. The thresholds are high because Cranelift is an optimizing compiler: a lower one compiled the methods package’s code that a package load runs only a few dozen times, which made the load slower, and on a test suite, whose bodies mostly run a few hundred to a few thousand times, 1000 entries cost more to compile than it saved. A fully typed closure, one with an inline type on every formal, compiles on its first entry instead: the declared types seed the type feedback of the instructions that have not run yet, and the guards on them stay. A base builtin call or an element-wise operation that has not returned yet takes the type the builtin computes for its argument types (seq_len(n) an integer vector, sum of doubles a double, x * y on double vectors a double vector), checked after the call like any fed-back type. When an operand’s type is still unknown (the result of an untyped closure, say), the first-call compile is declined without counting against the body, which then follows the thresholds.
  • What it compiles. A hot body compiles only when compiled code would save work. The planner counts three kinds of work in the body: instructions it runs natively, calls it removes or makes direct, and instructions it hands back to tier 0 one at a time. A native instruction saves about 130 machine instructions and a removed call about 1000. A step back to tier 0 costs about 300 more than tier 0 running the instruction itself, and entering compiled code costs about 570 more than starting the body in tier 0. A loop-free body whose balance is not positive stays in tier 0 for good, function(x) x^2 for one, and so does a loop whose iterations would mostly step, where an instruction in an inner loop weighs eight times one in the loop around it. A refused body keeps its type feedback, so a compiled caller can still inline it, and its loops stop counting and recording. RY_JIT_LOG=1 prints each decision with its counts.
  • The IR. The analysis turns the bytecode and its type feedback (one byte per instruction) into a typed plan: one action per instruction plus the abstract state before it, which records each register’s and variable’s type and where each variable’s value lives. The translator builds the plan into the mid-level SSA IR of crates/ssa, which the typed core builds too, and that crate’s one lowering emits it through Cranelift. A guard in the IR is an instruction whose failure branches to a cold deoptimization block. The optimizations that need an R-level IR above it (vector fusion, bounds-check elimination) are not built.
  • Unboxing. Integers, doubles and logicals of length one without attributes live in machine registers, with R’s NA and overflow rules. Element reads and writes on integer, double and logical vectors are inline, and a write copies only when the vector is shared. So are m[i, j] and m[[i, j]] reads with scalar subscripts on an ordinary matrix; a subscript out of range, NA or below 1 hands the read to tier 0, which raises the error.
  • Loops over sequences. A for loop over a compact sequence such as 1:n or seq_len(n) never expands it: both tiers compute each element from the first element and the increment, so for (i in 1:1e8) runs in constant memory. The loop state carries the index, the count, the first element and the increment (an increment of 0 means the loop reads the vector’s storage), and deoptimization hands all four to tier 0.
  • Variables. A body that never reflects on its frame keeps its variables in slots instead of its environment. The environment object still exists, but compiled code writes a variable back only before something that could observe it runs (a generic call, a dispatching operation, the first read of a formal whose default is an expression, a return, a deoptimization) and reloads it after something that could change it. A scalar written back goes into the box the variable holds when that box is a plain scalar of the same type that nothing else references, so a loop that calls a closure on every iteration does not allocate for its counters.
  • Calls without a frame. A call of a known closure runs inside the caller’s compiled code with no interpreter frame, environment or promises, behind a guard on the callee’s code. The call must bind as tier 0 would bind it without code running: positional, named and omitted arguments and literal defaults qualify, and ..., a default that is code and is read, a loop in the callee, a recursive call and a callee without type feedback do not. Every argument the callee reads is computed before the call as an unboxed scalar, and the callee’s free variables are read from its enclosing frames inline. The callee’s frame exists only in the frame states of its exits: when one is taken, the runtime builds the interpreter frames of the inlined calls from the saved values and tier 0 continues inside the callee. The start of such a call is one leaf helper that checks what would make a real frame necessary (a calling handler, the debugger, a changed closure), and when it declines, tier 0 runs the call instruction.
  • Other calls. A call to an effect-free closure whose binding was resolved at compile time is direct: effect-free arguments are evaluated eagerly and passed as already forced promises, bound by position without the general matcher. Evaluating early is invisible only if nothing can assign what an argument reads before the callee forces it, so the callee must be effect-free (the fact tier 0 also reads, crates/interp/src/effects.rs): its body and defaults call only itself, a fixed list of base builtins and other effect-free closures, and assign only its own locals. When a calling handler is established, a handler could run R code in between, so compiled code then runs tier 0’s call instruction, which makes the call lazily, and continues after it. A test harness always has handlers, so leaving the body for tier 0 there would interpret most of it. A call of a closure that computes a scalar from scalars without effects is inlined on unboxed registers, whether the closure is made in the same body or bound globally (then guarded by the binding epoch), and whether its body is one expression or a block of local assignments ending in a value or return(value). A failed guard inside the inlined body hands the whole call back to tier 0, which reruns it lazily; nothing is lost, because the body has no effects. A closure whose whole body is such a computation, branches, locals and calls of itself or other such closures included, is compiled once per argument type to a native function on unboxed values with no frame (crates/jit/src/native.rs), so a recursive scalar function runs entirely in machine code. It counts the expression-depth limit down itself, and anything that would warn or raise returns a failure status before anything visible happens, so tier 0 reruns the call. A typed closure’s checks are decided when its native function compiles. Function bindings are speculated against one global binding epoch, which the heap bumps whenever a watched binding changes or a watched name is defined in a function frame. Any other closure call is a step: tier 0 enters the callee in its own dispatch loop and hands the result back to the compiled code.
  • Returns. A compiled return writes the assigned locals back to the frame only when something can still read it: the frame has an environment, registered exit code, or a promise or closure that captured it. Otherwise the locals are dropped with the frame.
  • Speculation and deoptimization. A guard checks each fed-back type, and a function lookup is speculated against the binding epoch. A failed guard boxes the live values, writes back the dirty variables and the loop states, and continues in tier 0 at the guarded instruction; the code is then invalidated and may recompile, up to four times per body. An R error, break or next raised inside a helper leaves compiled code the same way, so tier 0 handles every non-local exit. Compiled code returns to tier 0’s loop to deoptimize rather than calling into it, so repeated deoptimization never deepens the native stack.
  • Warnings. A warning can run a calling handler, which may read or assign the frame’s variables. The fast paths that can warn (integer overflow, an out-of-range read, sqrt or log of a negative number) leave for tier 0 at that instruction without invalidating the code, and plain arithmetic or a pure builtin writes the frame back and reloads it afterwards whenever a calling handler is established.
  • The C API and the collector. Every boxed value compiled code holds is stored in the register window or a slot’s root cell, which the collector scans, so every object is a valid SEXP at every allocation and every helper call.
  • Measured and removed: a baseline tier. ry had a Sparkplug-style baseline tier below tier 1: per instruction, a call to tier 0’s step for it, emitted by ry’s own x86-64 and aarch64 assembler. It ran 6.7% more instructions than tier 0 on testthat_full at run time and 3.1% more with its compile excluded, while tier 0’s whole dispatch is about 3.1% of that workload, which bounds what any baseline could save. It was deleted, together with writing its code into the code image (decisions/jit-ssa.md, “No baseline tier, and code images hold bytecode only”).
  • Not yet built: calls from compiled code straight into the callee’s compiled code (a direct call still enters through tier 0’s call path and allocates a frame and forced promises), result types for multi-index subscripts such as m[i, ], and freeing the machine code of invalidated bodies.

Plain untyped R decides how ry compares with GNU R, because most hot R code sits in closures called a few thousand times, under tier 1’s entry threshold. This table lists every idea ry has adopted, plans or rejected for that code, in the order it is built. A status changes with the pull request that changes it. prior-art.md gives the reasoning behind each source engine’s verdict.

The gaps come from ry run --profile-summary on the application workloads (JIT on: tier-0 instructions 23 to 44% of the time, closure call setup 12 to 24%, builtins about 25%, S3 method lookup up to 17%) and from callgrind on seq(1, 10, by = 2), which costs 121.4k instructions per call on ry (JIT off, down from 141.6k when this table started) and about 106k on GNU R 4.3.3. A plain closure call, f(x, y = 2) x + y called from a loop, costs 3,968 instructions on ry and 4,602 on GNU R; timed as the median of 9 interleaved runs of 3 million calls, it takes 0.445 µs on ry and 0.525 µs on GNU R.

What remains of the seq() gap is spread thin. Tier-0 dispatch (loading the op word, decoding it and jumping) costs about 11k instructions per call, about 13 per op over about 860 ops: 196 jumps, 154 guards, 95 variable reads, 75 constants and 69 builtin calls. Of the rest, pmin() costs 55.9k on ry against 43.5k on GNU R, mostly in the vapply() it calls. No single step-2 row closes a gap that size, so shrinking the op count and the cost per op (step 3) comes forward.

Target. Untyped R with the JIT on runs at 10 times GNU R’s speed on one thread, measured as the geometric mean over the application workloads (just bench applications) and over the package test suites (just bench packages). The milestones are 1.5x and then 3x; benchmarks.mdx has where both suites stand. Parallelism is deferred: the architecture keeps it possible (decisions/interp.md, “Single-thread first, parallel-ready architecture (user directive)”), but the target does not count on it.

Where the time goes. ry run --profile-summary splits a run into the buckets below. R code is everything the evaluator does for R-level code: tier-0 instructions, closure call setup, lookups, S3 and S4 dispatch, condition handling and tier-1 code. Native code is split by owner: ry’s own ports of base and recommended code (nmath, fft and the rest of stats) are ry’s to speed up, while third-party CRAN C code is fixed on one thread, because packages assume R’s C API is single-threaded. I/O is the file and connection builtins, and waiting is Sys.sleep and waits on child processes (processx). Shares are of one run with the JIT on.

Workload R code builtins native, ry ports native, CRAN GC I/O waiting start-up
conditions 72% 20% 0% 0% 5% 0% 0% 3%
functional 64% 21% 0% 3% 10% 0% 0% 2%
objects 66% 26% 0% 0% 6% 0% 0% 2%
records 55% 31% 0% 0% 11% 0% 0% 3%
simulation 3% 51% 40% (stats) 0% 2% 0% 0% 4%
strings 62% 30% 0% 1% 4% 0% 0% 2%
tables 53% 27% 4% 9% (data.table) 2% 0% 0% 5%
timeseries 59% 24% 0% 13% (xts) 3% 0% 0% 1%
validation 71% 24% 0% 0% 3% 0% 0% 2%
workload mean 56% 28% 5% 3% 5% 0% 0% 3%
corpus mean (26 packages) 45% 30% 4% (all native) 8% 1.5% 4% 7%

The corpus row is the mean of per-package shares; the corpus profile does not split native code by owner. rlang and purrr set Config/testthat/parallel: true, so testthat runs their tests in a callr worker even on one CPU, and their row comes from the worker’s profile (RY_PROFILE_SUMMARY_DIR writes one summary per process): the main process only waits for the worker in processx‘s native code. Weighted by time, R code is 53% of the corpus, builtins 23%, native code 5%, I/O 0.7% and waiting 9.5%. Most I/O is unlink (1.7 s of a 158 s corpus run), and most of that removes single files, such as the verify_exec_* files testthat writes around each snapshot test in cli, which cost GNU R the same system call. Removing a directory tree costs more, because rmdir waits on the ext4 journal (0.1 ms on an idle disk, 2 to 4 ms under writes), and GNU R pays that wait too: a testthat-shaped tree takes about 0.35 ms on both idle and 2.6 ms on both under write load (decisions/builtins.md, “unlink() follows GNU R’s R_unlink, with directory descriptors”). The waiting is the suites’ own Sys.sleep (foreach 77%, lgr 22%, cachem 10%), which GNU R pays too. Child R processes started through callr and processx run ry, because R.home()’s bin/R and bin/Rscript start ry, and Rscript -e starts in 32 ms against GNU R’s 140 ms. Start-up dominates the smallest suites (abind 74%, zoo 81%). Averaged over the nine workloads, the builtins that take the most time are [<- and exp (1.8% each, all on simulation’s 30,000-element vectors, where ry already runs twice as fast as GNU R), then vapply (1.2%), ryStructure, .Call, <-, [, lapply, list, ryFormatDefault and forceAndCall (0.7 to 1.0% each). On the corpus they are as.POSIXlt, [[, c, [, lazyLoadDBfetch and match (measured before the row (a) fast paths below). Counted by calls rather than time, the builtins that compiled code reached outside any fast path were ! (476k), length (381k), [[ (257k), is.null (181k), missing (136k), [ (127k), .Call (122k), match (116k), is.na (108k), identical (105k), == (104k), names (92k), is.logical (91k), is.character (69k) and is.function (64k); the small base closures with the most self time were identical (2.4%), match (2.2%), nrow (1.5%), isTRUE (1.4%), vapply (1.4%), stopifnot (1.3%), %in% (1.0%) and %||% (0.9%).

The arithmetic. Speeding each bucket up by the factor below, with CRAN native code, I/O and waiting fixed, gives these geometric means over GNU R (Amdahl’s law per workload, starting from today’s ratio):

Plan R code builtins ry ports GC, start-up workloads corpus
1.5x milestone 2x 1.5x 1x 1x 1.43x 2.96x
corpus 1.5x 3x 2x 1x 2x 4.28x
3x milestone 5x 3x 3x 2x 3.08x 5.74x
10x target 30x 10x 10x 10x 10.96x 15.52x
ceiling: only the fixed buckets left tables 8.9x, timeseries 8.1x 34.4x

So 10x on the workloads is reachable on one thread: R code needs about 30x (tier 1 for most of it, row (c) below) and builtins about 10x (row (a)). tables and timeseries stop near 9x and 8x because of data.table’s and xts’s C code, and the geometric mean carries them. The corpus runs at 2.01x GNU R today (geometric mean over the 21 packages that pass on both engines, 95% interval 1.83x to 2.20x). The corpus runs offline: run.py drops test files that fetch URLs (NETWORK_TESTS, such as jsonlite’s test-network-*.R, whose GitHub requests cost both engines the same 0.2 s each) and routes both engines through a proxy that refuses every request, so a test that reaches for the network fails the run. Its column counts all native code as fixed, because the profile does not split ry’s ports from CRAN code, and its single-thread ceiling is 34.4x, because I/O, waiting and native code are small. The lowest per-suite ceilings are lgr’s 7.7x (its Sys.sleep), then rlang, withr and cli at 11x to 12x (their native code and waiting).

Target row Status What it needs
(a) Builtins several times faster than GNU R’s C: no allocation on the fast path, SIMD kernels, fused element-wise temporaries in progress builtins from 28% (workloads and corpus) to 10x faster; the top of the ranking above first. Built: attributes, c, [[ and [[<- with constant subscripts, forceAndCall, a builtin FUN in the apply family, Reduce, the one-argument builtins !, length, is.null, is.na, is.character, is.logical and is.function in compiled calls, and native entries for identical, isTRUE, isFALSE, nrow, ncol, match, %in% and `%
(b) Automatic parallelism for effect-free apply-family calls and long element-wise operations, deterministic, with bit-identical reductions deferred, architecture-ready the effect-free fact per function and the invariants in decisions/interp.md; package native code stays single-threaded. Deferred because the target users already run their test suites in parallel across processes and are CPU bound, so every core is busy and threads inside one process would only compete with the other workers. Single-core speed is the goal, and every cost paid per process (warm-up, compile time, package loading, resident memory) is paid once per worker
(c) Tier-1 compilation of most R-level time planned R code from 56% (workloads) to 30x faster; tier 1 today runs under 3% of the time on eight of nine workloads
(d) Native code shrinks only through faster ry ports or parallelism; third-party C is not replaced in progress ry’s own ports are ry’s to speed up; third-party C stays: data.table and xts on the workloads, data.table and rlang on the corpus. Built: vector kernels for the d/p/q functions, batched samplers, and AVX2 twister, tempering and inversion lanes, bit-identical to GNU R (“Distribution functions and the RNG run as vector kernels and batched samplers” in decisions/builtins.md). rnorm costs 67 instructions per normal (164 before); per element at length 1e6 rnorm is 3.2x GNU R, runif 5.7x, qnorm 3.0x, pnorm 1.7x and rpois 1.1x. The native bucket of simulation fell from 0.53 s (53%) to 0.30 s (40%), and the workload runs 1.26x faster (1.15 to 1.43 over 9 rounds). sample draws its indices in integers: per element at length 1e6, sample(1e6) is 2.7x GNU R and sample(1e6, replace = TRUE) 3.7x. Stats closures of the form .Call(C_routine, ...) enter their routine directly, without a frame, and decline to the R body on any warning or error (“Stats distribution closures enter their routine directly” in decisions/builtins.md): per call, dnorm(x) and pnorm(x) take about 0.46 µs (GNU R 1.0 and 1.1 µs) and rnorm(1) 0.68 µs (GNU R 2.8 µs). pnorm’s exponentials and the qnorm tail logarithms run on the exact vector ports of glibc’s FMA exp and log that the fused element-wise kernels use: per element at length 1e6, pnorm is 1.80x GNU R (1.19x over the scalar loop) and qnorm on tail probabilities 2.09x (1.19x). sample.int(N, n) with N / 128 <= n tracks drawn values in a bitset, 2.64x GNU R at sample.int(1e8, 1e6) (1.21x over the hash set)
Idea Source engine Status Measured gap it targets Code
1. Tier-0 call path
Op words carry their operand count; one cold error exit JSC LLInt built dispatch, about 15 instructions per op interpret, failed in crates/interp/src/bytecode.rs
Slot hints at lookup sites, behind the frame’s symbol filter JSC, V8 inline caches built variable lookup cached_cell, Frame::find_hinted in crates/heap/src/env.rs
Function lookups skip frames that cannot bind the symbol ry built lookup_function lookup_function in bytecode.rs
Lookup stamps compared as their bits V8 built 1.25k per seq() call LookupCache in bytecode.rs
Index only for frames over 32 bindings: one open-addressed block of packed (hash, position) words ry built 3k per seq() call (Frame::insert) INDEX_THRESHOLD in env.rs
Literal pkg::name reads the namespace binding it found, while the stamps of the bindings that led there stand still JSC watchpoints built namespace_lookup on testthat_full, JIT off: 33,841 calls to 1,549 over five repetitions Op::Namespace in bytecode.rs, namespace_binding in envir.rs
Frameless GetFun for a slot holding a function and for a cached global function LuaJIT, CPython built testthat_full, JIT off: the GetFun handler 22.7M to 12.4M instructions per repetition get_fun_fast in bytecode.rs
Builtin checks derived at registration GNU R PRIMARITY built builtin call overhead Checks in crates/interp/src/builtins.rs
A call plan per call site: arguments written straight into the callee’s slots JSC CodeBlock, V8 built run_closure’s matching and binding; a call from a loop costs 2,330 instructions, down from 3,065 on heap frames direct_plan in bytecode.rs, call_with_plan in eval.rs
Closure frames in fixed slots: a call builds its frame in the slot above the top and pops by lowering the depth, never moving it CPython 3.11 frame stack, Lua CallInfo reuse built frame push and pop: a call from a loop costs 2,844 instructions, down from 2,927; testthat_full -1.16% with the JIT off and -1.17% with it on, validation -0.91% FrameStack in crates/interp/src/interp.rs
Tier 0 continues its dispatch loop in the callee: a call to a compiled body pushes a resume record instead of entering Rust, and every way out of the body goes back through it CPython 3.11 inlined Python calls, LuaJIT built the Rust entry and exit per call: the planned h -> f pair 4,127 to 2,725 instructions, and with the JIT off expr_tree -10.4%, validation -1.5%, objects -0.8%, conditions +0.0% enter_in_place, finished in bytecode.rs; enter, leave, apply_closure_entering in eval.rs
2. Call facts ahead of time
Version-stamped bindings: a function guard is one compare JSC watchpoints, V8 property cells built 154 guards per seq() call; 141.6k to 139.7k instructions per call the Op::Guard arm and cached_cell in bytecode.rs
A guard on a base function is two bit tests and one load: no binding of the symbol outside base and an attached enclosure chain mean the base binding answers it. Every route that binds a symbol in a frame marks the symbol, and the mark never clears JSC watchpoints built testthat_full over five repetitions, JIT off: 4,145.6M to 4,132.8M instructions (-0.31%), run_guard 26.1M to 13.7M; an environment write costs 6 more (934 to 940) guard_fast in bytecode.rs; BOUND_ELSEWHERE, DETACHED and mark_bound_elsewhere in crates/heap/src/env.rs
Frames cleared in place, without copying the cell list ry built clear_frame; 139.7k to 136.6k per seq() call, with the two rows below Heap::clear_frame in crates/heap/src/heap.rs
Untyped closures skip the signature lookup; on.exit handling only when an exit expression exists ry built part of the 3.1k above signature_of in crates/interp/src/annotations.rs, run_closure in eval.rs
Frames as slot arrays, with an environment that binds a variable only when a lookup asks for it Ř, V8 built binding cells, promises and environments per call (slot-frames.md, “Measured”) bind_slots, pending_env, box_variable, lift_frame in eval.rs; slot-frames.md
Promise elision for strict, effect-free arguments Ř done in tier 0 (crates/interp/src/effects.rs) closure_args_into 3.8% of a call microbenchmark f(i, 1) 3,968 to 3,411 instructions per call; seq() unchanged, its helpers are not effect-free
Cheaper promises: created lazily, held inline in the frame slot, or allocated from a per-call arena Ř, GNU R rejected, measured a closure call on the testthat workload costs about 8,100 instructions with 1.2 promises; allocating a promise is a nursery bump, and promises are 1.4 of the 7.4 objects freed per call. None of the three designs saves more than that allocation, and each changes what PRCODE, PRENV, substitute and delayedAssign see
Formals bound in one pass; a forced promise settled with one barrier; the stack check against a cached floor ry built defining formals 270, settling 87 and stacker’s thread-local lookup per call; 8,174 to 8,140 instructions per closure call on the testthat workload Frame::insert_formals in crates/heap/src/env.rs, Heap::settle_promise, on_large_stack in eval.rs
The promargs pairlist built only when asked for GNU R planned args_pairlist 2.7% of a call microbenchmark
Argument-match caches, one entry per closure body V8, JSC done (eval::match_args_cached) match_args 2.8k, bind_arguments 2.8k per seq() call matching in seq() 3.6k to 1.0k instructions; 1.0 to 1.2 million named calls per application workload
Polymorphic inline caches for S3 and S4, keyed on the class vector Self, V8 built S3 method lookup up to 17% (timeseries); instructions per dispatch: UseMethod 8.75k to 7.69k (GNU R 9.82k), with NextMethod 23.14k to 19.04k (GNU R 19.03k); one NextMethod level from a method in slots 20.55k to 17.16k (GNU R 4.6.2 17.74k), standardGeneric 14.26k to 8.69k (GNU R 11.68k) resolve_s3, site_hit in crates/interp/src/dispatch.rs; S4Cache, dispatch_generic in crates/interp/src/methods.rs
Closed bindings per locked namespace, reopened by unlockBinding and assignInNamespace Bun, Roc planned namespace function lookups
Precise counts and borrowed parameters in tier 0 Roc (Perceus) planned copies and peak memory
Setter instruction for one-level complex assignment GNU R bytecode built attributes(m) <- NULL 4.2k to 1.5k instructions (GNU R 1.1k); mostattributes(m) <- 11.0k to 9.5k (GNU R 6.9k); seq() 136.2k to 135.0k Op::Replace, replace_variable in bytecode.rs
Native prologues for hot base closures (match.arg, stopifnot, setdiff, structure, format.default, Reduce), installed by hash on the R version they were written from ry, after the methods core built validation workload 0.6x to 1.87x GNU R; 2.71G to 1.32G instructions (JIT off) crates/interp/src/base_fast_paths.rs
Native prologues for hot package closures, installed by hash from registerS3methods() on each namespace load: rlang 1.3.0’s trace_back, which every expect_error() and expect_warning() runs ry built testthat workload 6.79G to 4.69G instructions (JIT on and off) crates/interp/src/package_fast_paths.rs
Builtin fast paths without string round trips or repeated evaluation: attributes and c take names as CHARSXPs instead of interning them again; the compiled [[ read serves classless lists and the in-place element assignment takes a constant name; forceAndCall reuses its call’s argument cells; lapply and vapply hand a builtin FUN (or [[) the element they read; Reduce gets a native prologue ry built instructions per call, JIT off, before and after (GNU R): attributes on an xts object 4,183 to 1,786 (2,692); c(1:3, 4.5) 4,262 to 2,131 (2,731); c(a, z = 3) 5,964 to 4,616 (4,299); x[[2L]] 1,150 to 698 (709); x[["fee"]] 1,674 to 693 (1,805); x[["net"]] <- 3 4,910 to 987 (2,011); forceAndCall(2, f, x, y) 5,520 to 4,232 (5,198); vapply(rows, `[[`, 0, "fee") over 100 rows 421.8k to 260.0k (363.4k); Reduce(f, x) over 100 elements 748.7k to 423.1k (688.8k) do_attributes, do_c in crates/interp/src/subset.rs; cached_item in records.rs; do_force_and_call, force_and_call_with, call_with_values in eval.rs; do_reduce in base_fast_paths.rs
One-argument builtins without dispatch, and native entries for small base closures: compiled code calls a builtin’s unary function with the operand register before any dispatch, and a call to a hash-guarded base closure whose arguments are already values runs natively without a frame ry built instructions per call, JIT off, before and after (GNU R): !x 944 to 563 (750); length(x) 1,002 to 772 (1,232); is.null(x) 754 to 575 (697); is.na(x) 1,128 to 641 (1,490); is.character(x) 754 to 574 (699); identical(x, y) 8,545 to 1,818 (3,149); isTRUE(x) 6,087 to 1,114 (5,594); nrow(m) 4,575 to 1,324 (4,075); match(x, t) 6,869 to 1,905 (2,963); x %in% t 11,327 to 1,745 (8,226); x %||% y 3,293 to 1,027 (absent in GNU R 4.3.3) BuiltinDef::unary in builtins.rs, its call in op_call_builtin (bytecode.rs); native_entry and NATIVE_ENTRIES in base_fast_paths.rs
Getter instructions for nested complex assignment (names(x)[2] <-, x$a$b <-) GNU R bytecode planned complex_assign calls a primitive setter with its values and builds a call for each getter level
3. LLInt- and LuaJIT-grade tier 0
In-place specialization (quickening) with value profiles CPython (PEP 659), JSC built for scalar integer and double arithmetic and comparisons; a comparison that a JumpUnless tests takes the branch itself while (i < n) i <- i + 1L, JIT off: 1,123 to 406 instructions per iteration with the two rows below QUICK_ARITHMETIC, quick_arithmetic, arithmetic_miss in bytecode.rs
Frameless fast handlers: a call-free fast path per hot instruction, with the generic handler a tail jump away LuaJIT, LLInt built for GetVar, SetVar, Guard, JumpUnless, Jump, Constant, SetSrcref, EndStatement and the quickened arithmetic the callee-saved spills of every handler; scalar results from Heap::try_alloc_scalar, which never calls fast_paths!, GENERIC_HANDLERS in bytecode.rs
Cold fallbacks of in-loop instructions after the back edge LuaJIT, V8 built loop bodies contiguous in the code vector back_edge in bytecode.rs
Guards folded into one version check per body entry; code, registers and pc pinned as handler arguments; the visible flag set once per statement LuaJIT planned the warmed loop’s remaining 406 instructions: three guards (about 34 each), three GetVars (about 31 each), SetVar (52)
Tail-call dispatch, one indirect jump per handler LuaJIT, JSC built the shared indirect jump; measured level with the match loop (121.4k against 120.8k per seq()), since handlers that call out still need a frame. The handler signature is (activation, pc) so that few values stay live across calls handlers! in bytecode.rs
Superinstructions for the most frequent op pairs CPython, LuaJIT rejected, measured the 20 hottest pairs cover 38.8% of executed ops on testthat_full, JIT off, yet instructions moved +0.08% and wall time stayed within noise: with one indirect jump per handler, a fused pair saves a jump the branch predictor already predicts the branch perf/tier0-superinstructions
Dense feedback storage, one slot per profiled instruction V8 planned feedback is one i32 per code word
One kernel layer for vector builtins: vectorized slice kernels, results written into dead temporaries, and an Op::Fused superinstruction that evaluates an element-wise tree in 512-element chunks or declines before anything observable happens pqR (R_allocOrReuseVector, task merging), Riposte in progress builtins 51% of simulation; one allocation and one pass per operator. y <- exp(-x^2/2) * k runs at 1.4 to 1.6 ns per element against GNU R’s 6.3 (4x), x * k + 1 at 0.3 against 1.8 crates/interp/src/kernels.rs, vector_math.rs
4. Optimizing tiers
Per-argument-type native functions for scalar closures Julia built recursive scalar functions crates/jit/src/native.rs
Baseline compiler from bytecode, no optimization V8 Sparkplug built, measured and removed warm code under the 3000-entry threshold. It compiled in a median of 28 µs per body, but ran 6.7% more instructions than tier 0 on testthat_full (3.1% with its compile excluded), while tier 0’s whole dispatch is 2.66% of that workload (about 3.1% with pc bookkeeping), so no call-threaded baseline can pay off decisions/jit-ssa.md, “No baseline tier, and code images hold bytecode only”
A lower Cranelift threshold HotSpot, .NET tiering measured, kept at 3000 entries; large bodies wait in proportion to their size, and a loop-free body compiles only when its call rate over the recording window (its share of the session’s closure calls) promises enough calls to repay the compile tier 1 under 3% of the time on eight of nine workloads. Callgrind geomean against JIT off: 1000 entries 1.015, 2000 1.016, 3000 1.013, 6000 1.010, 10,000 1.010, so the threshold does not decide on against off. The rate check took testthat’s JIT-on cost over JIT off from 17.6M to 5.6M instructions and kept every functional callback compiling SIZE_WAIT_WORDS and repays in crates/jit/src/jit.rs
Cross-closure inlining with deoptimization Ř (PIR) partly built: effect-free closures, single-expression or block bodies, guarded on callee identity; a failed guard reruns the whole call in tier 0. Callees with effects, which need frame materialization, are planned calls from compiled code re-enter tier 0 inline, lower_block in crates/jit/src/analysis.rs
Escape analysis, scalar replacement, vector fusion Graal, goose planned scalar and intermediate vector allocation
Per-signature numeric specialization of vector code Julia planned
Effect-free lapply, vapply, Map and long element-wise operations across cores; reductions stay sequential Bend planned wall time of independent per-element work
5. Memory and start-up
A start-up image of the heap’s pages at a fixed address, mapped privately and shared until written V8 snapshots, Bun built empty ry run 121.5M to 47.9M instructions, 38.5 to 29.2 ms; 4 concurrent workers 117 to 87 MB Pss crates/heap/src/image.rs, fill_from in crates/interp/src/image.rs
No major collection while a namespace loads; the limit is rebased when the outermost load returns ry built 2 major collections to 0 loading testthat, xts, data.table and a 40,744-object package; GC 15.7% to about 5% of the load enter_namespace_load in crates/heap/src/heap.rs
Lazy-load records read with borrowed strings, bulk vectors and iterative pairlists; makeLazy with GNU R’s shared environment; S4-generic checks answered from a record’s header GNU R built library() of 11 packages: 1,197.8M to 1,133.0M instructions, 914 records fetched to 651 crates/interp/src/serialize.rs, do_local_s4_generics in envir.rs
Card marking for remembered old objects V8, HotSpot planned minor collections during a load cost about 24M instructions each, mostly re-marking namespace frames being filled
A buffered unserializeFromConn GNU R planned it reads a few bytes per call: 93M instructions of the 11-package library()
Per-package code images written at install time, beside the lazy-load database Bun built, no speedup yet package load and warm-up; decoding a closure costs about what compiling it does, so untrained images cost 1.3% more instructions on library(survival) crates/interp/src/code_image.rs
Install-time machine code from whole-program facts (checker types, closed namespace bindings, effect-free functions), values from outside tested once where they enter, no profiles Bun (--aot) built for scalar numeric closures, measured neutral, removed (decisions/jit-ssa.md, “No baseline tier, and code images hold bytecode only”) testthat workload 7.850G against 7.834G instructions with images off, because few package functions are scalar numeric
One SSA IR for tier 1 and the typed core: typed facts unguarded, untyped speculations guarded with deoptimization exits; install-time code through the typed AOT pipeline, with its deoptimization metadata and watched bindings in the code file Ř (PIR), Graal IR built; install-time code planned two SSA forms and two lowerings to Cranelift crates/ssa
Profiles from a training run (the package’s tests and examples) stored in the per-package image HHVM Jump-Start, Project Leyden built, no speedup yet: loops tier up within their first call anyway, and a training run on other types makes the JIT refuse to recompile hot closures that never reach tier 1’s thresholds
Images shared across worker processes Bun planned resident memory per parallel worker
Concurrent tracing and Immix line reuse LXR planned, after collector pauses are measured collector pauses, fragmentation
A stackless tier 0 Bend planned, on the tail-call handlers Rust frame setup per R call
Rejected
Copy-and-patch as a tier CPython (PEP 744) rejected
Meta-tracing PyPy rejected
A partial-evaluation framework (AST interpreters) Truffle and Graal rejected
Generating the interpreter from LLVM IR Deegen rejected
Freeing R objects when their count reaches zero LXR rejected
Lazy fused vectors as ALTREP objects Riposte, pqR rejected every reader, C code through DATAPTR included, would materialize them, and where a deferred warning surfaces would become observable

R’s vector builtins share one kernel layer in crates/interp/src/kernels.rs, which is target row (a)’s design for element-wise work. It has three parts.

  • Slice kernels. A kernel takes each operand as a slice or a scalar and writes into an output slice. It touches no R object, allocates nothing and raises nothing: an integer kernel returns an overflow flag, and its caller warns. The loops vectorize for the baseline instruction set (SSE2 on x86-64). There is no separate AVX2 build: the loops are bound by memory traffic, and a second copy of every kernel costs resident code. Compiled code calls this layer directly.
  • Reuse. An operation writes its result into an operand’s buffer when the bytecode compiler marked the operand’s register as a temporary read only by this instruction, and at run time the value’s count is zero, it is mutable, not ALTREP, and has the result’s type and length. The compiler’s mark is needed because registers hold uncounted references, so a zero count alone does not prove the value dead. This is pqR’s R_allocOrReuseVector rule, restricted to what the compiler proves. The evaluator offers a second destination: in x <- f(x, ...), where f is an element-wise builtin and x’s binding holds the only reference to its value, the result goes into x’s buffer. Every kernel takes its destination as an argument that may be one of its operands, and reads that operand from the output buffer, so aliasing is exact under recycling. A destination of length one is never reused, because the shared TRUE, FALSE and NA constants can look private. A scalar operand of a math function, a comparison or unary minus is answered without the element loop.
  • Complex arithmetic. +, -, *, / and ^ with a complex operand run as slice kernels under the same reuse rule. * and / are ports of libgcc’s __muldc3 and __divdc3, which GCC-compiled GNU R uses and Rust’s runtime replaces with compiler-rt’s, and every step keeps GCC’s operand order so the same NaN payload wins: results match GNU R bit for bit, NA versus NaN included. ^ is GNU R’s mycpow, and z^2 reproduces R_cpow_n’s 1 * (z * z). A double beside a complex vector is lifted per element, NA as NA + 0i.
  • Reductions. sum on integers, any, all, min, max and range are SIMD kernels; range finds both bounds in one pass. prod and the double sum accumulate in x87 long double as GNU R does, so they keep scalar loops.
  • Fusion. For an element-wise tree such as a * b + c or sum(x > 0) whose leaves are constants and variables, the compiler emits Op::Fused in front of the ordinary code. The instruction reads the leaves in the ordinary code’s order (forcing an argument’s promise as a variable read would) and checks every operator’s binding through its guard cache. It declines and falls through to the ordinary code on anything observable (an active binding, an attribute, an object, ALTREP, recycling other than scalar against equal lengths, integer overflow, a NaN that a math function produced), so fused and unfused evaluation cannot be told apart. It also declines when every leaf is a scalar or the tree’s vectors are shorter than 64 elements, where the ordinary instructions are cheaper because a short vector saves little allocation. Otherwise it runs the tree in 512-element chunks, writes only the root, and records the type feedback of the instructions it skipped, so the JIT, which compiles the ordinary code, sees the same types. A leaf may also be a call the pass cannot compute, such as mean(x) in sum(x - mean(x) > 0), as long as no operator of the tree runs before it. The compiler first checks the guards of the operators R looks up before the call, then evaluates the call and the variables read before it into registers, in R’s order, and both the fused pass and the ordinary code read those registers, so the call runs exactly once. If one of those guards fails (an operator redefined in the frame), the whole expression goes to the evaluator before anything ran. A call that may modify a variable in place (an assignment, eval, a replacement call) stays unfused. A site that declines 16 times in a row rewrites its opcode to Op::Unfused, which does nothing, and drops its program, so a site that never fuses costs one dispatch in tier 0 and no heap.
  • Assignment into the old buffer. For y <- expr, a fused double pass writes its result into the vector y already holds when nothing else can see that vector: the binding is not active or locked, the vector’s count is one, and it has the result’s type and length. y may be a leaf of the tree, as in x <- exp(-x^2 / 2) * 0.5 + x; the pass then keeps each chunk in scratch and copies it over y’s elements only after every node has read them. A loop that reassigns a vector therefore allocates nothing after its first pass. Integer passes never reuse, because an overflow halfway through declines to the ordinary code, which must still read the old value.
  • SIMD exp and log. On x86-64 with AVX2 and FMA, exp and log of doubles, alone or inside a fused pass, run four lanes at a time (crates/numeric/src/vector_math.rs). They are ports of glibc’s __exp_fma and __log_fma, the variants GNU R calls on such a machine, and agree with them bit for bit; the first call compares both on edge values and falls back to glibc when they differ. pnorm and the qnorm tails call the same kernels on batches of their exponent and logarithm arguments. Table lookups use paired 128-bit loads rather than gathers, which the Gather Data Sampling mitigation makes slow. x^2 is x * x and division by a power of two is multiplication by its exact reciprocal, which give GNU R’s bits, NA’s quieted payload included.

NaN results match GNU R 4.3.3 on x86-64, where an operation on two NaNs returns the first operand’s payload. GNU R’s compiled loops swap the operands of + and * on two doubles when the left one is a scalar beside a longer vector or when both recycle, so NA_real_ + c(NaN, 1) is NaN while c(NA, 1) + NaN is NA; with an integer operand, and for -, / and %/%, the first operand’s payload wins. The kernels reproduce each case. Beside a scalar that is not NaN, only the vector’s element can be NaN and the hardware’s + and * return its payload in either operand order, so those loops carry no per-element NaN test.

Package code is meant to run as machine code calling machine code, with tier 0 kept for eval, non-standard evaluation and whatever compiled code declines. Four parts make that up, and they are one design because each constrains the others: the frame is what compiled code reads, the calling convention decides what a frame holds on entry, unboxed values decide when the frame is written, and compiling ahead decides which of these facts are known before the first call.

Part Status Owner
Slot frames, environments made on demand and filled one variable at a time built (slot-frames.md) frames
A direct calling convention between closures built from tier 0 to tier 0; machine to machine planned frames (tier 0), JIT (machine code)
Unboxed length-1 doubles, integers and logicals in compiled code built inside tier 1 and native functions; across calls planned JIT
Whole-package compilation at install, with entry guards and deoptimization to tier 0 measured and removed for untyped closures (decisions/jit-ssa.md, “No baseline tier, and code images hold bytecode only”); strict typed closures planned JIT

The targets are at least 80% of closures in rlang, cli and testthat running as machine code (5 to 11% today), 30% fewer instructions on the testthat workload, and the application workloads at twice GNU R’s speed. Vector kernels are a separate module behind a narrow interface that compiled code calls.

Frame layout. A call’s frame is a window of the register file: a header register, one slot per symbol the body can bind (formals first, in order, then locals numbered by the compiler’s slot table), then the body’s own registers. The header holds the frame’s environment once one exists and NULL before. Each slot counts one reference and holds a value, a promise, the empty argument for a missing formal, the unbound marker for an unassigned local, or for ... the DOTSXP the call collected. Frame.missing carries one missing bit per formal (up to 64 formals). Machine code uses the same window: its spilled values live in the slots, so a frame looks the same whichever tier is running it, and switching tiers moves no values.

Calling convention. A call site that calls closures carries a plan in its constants. The first call of a body there marks the site, and the second builds the plan: for each formal of the callee, the position of the argument that fills its slot, or -1 when the site supplies none. Later calls of the same formals and body skip argument matching and write the arguments straight into the callee’s slots (eval::call_with_plan); a site that has seen eight different bodies stops planning. A plan exists only when matching cannot depend on the values: the callee has no ... formal, the site passes no ... or ..N, and every formal the site leaves out has a literal default. Everything else binds through the matcher (bind_slots, with its per-body match cache), still into a slot frame. Arguments go in as values when they are constants, or variables passed to an effect-free callee; otherwise as argument references, which name the caller’s slot or the argument’s compiled code and come from a pool, so they allocate nothing and need no environment. A reference becomes a promise object only when something keeps the argument past the call. A call that passes ... on appends the arguments the caller’s ... slot collected.

Between machine code (planned), a call of a sibling closure in a locked namespace is a direct machine call to the callee’s entry for the argument types at hand, guarded once per call. Pure arguments (native::pure_value) are passed evaluated and unboxed; the rest are passed as promises over the caller’s frame, exactly as tier 0 passes them.

What makes the environment. A slot frame has no environment object until something names the frame: a promise or a closure made in it, parent.frame(), sys.function, S3 and S4 dispatch, a builtin that receives the calling environment, PRENV, R_GetCurrentEnv or the rho of .External2. eval::frame_env, eval::frame_sys_parent and Call::env are the only ways to get one, and what they hand out binds nothing. A variable moves from its slot into a binding cell when a lookup through the environment asks for that name, and the frame’s own code reads by name from then on. Every variable moves only when something lists the bindings or the environment outlives the call. missing, nargs, sys.call, substitute(name), on.exit, return and forwarding ... read the frame record or the slots and make nothing. slot-frames.md has the states, the triggers and the invariants.

What stays on heap frames. A body runs in a heap frame from the start when the compiler refuses it a slot table, which it does when the body may bind a name its own text does not show or hands its frame to code that may: a bare environment(), sys.frames(), attach or source, an eval, evalq, assign, delayedAssign or rm without an explicit environment, an assignment to a string target, or a read of an S3 dispatch variable. A call also binds a heap frame under the debugger, for a closure with a type signature, and when a missing formal’s default cannot be compiled with its own slot table. slot-frames.md, “The shape”, is the full list.

Deoptimization and frame state. Machine code that leaves for tier 0 continues on the same window. Each exit carries a frame-state map: for every live slot and register, whether it is already in the window or is a machine value of a known type, plus the tier-0 instruction to resume at. Leaving boxes the machine values, writes them into their slots, restores the missing bits and jumps into tier 0’s loop; it makes no environment, because only a trigger does. A callee can make the frame read its variables by name while machine code waits on the call, and then the header register holds the environment, so machine code checks the header after every call that can do that and leaves for tier 0 when it is set.

Tier-1 code runs in slot frames. It reads the header register on every variable probe: while it is NULL, a variable the slot table numbers loads straight from its slot at an index fixed when the code compiles, and a name the table does not number is looked up from the closure’s environment. Tier 1 keeps its own copies of the variables it loaded and writes a changed one back through the frame (Machine::assign), into the slot or, once the frame reads by name, into its binding, so it needs no exit when a callee switches the frame under it.

Boxing. A length-1 double, integer or logical without attributes stays in a machine register while compiled code uses it, with R’s NA and overflow rules. It is boxed when it escapes: written to a slot before anything that can read the frame (a generic call, a dispatching operation, a trigger, a deoptimization, a return to tier 0), passed to a callee that is not machine code, stored into a vector or list, captured by a promise, or returned to a caller that expects a SEXP. A machine-to-machine call passes and returns it unboxed, per the callee’s specialization.

Row (a) of the roadmap goes builtin by builtin, starting from the top of the Amdahl ranking: attribute access, c, [[ and [[<-, then [ and [<-, the apply family and .Call. Each builtin gets one implementation in its end shape, in its own module, which the full call and the fast entry both use, so there is no second copy of the semantics to drift.

  • Direct entries. A builtin may register a direct function that takes its argument values in formal order and returns None to decline. Compiled code calls it when no argument is tagged or empty, before it builds an argument vector, runs the call checks or opens a handle scope. A replacement called from a complex assignment (attr(x, "a") <- v) uses it too, with the trailing value argument. The entry declines whatever the full call treats differently: an object that dispatches, ALTREP, a ry native value, and any argument the full call reports an error for.
  • Strings by identity. Attribute names, class names and list names are interned CHARSXPs, and interned ASCII strings are equal exactly when they are the same object. A lookup compares pointers and reads bytes only when a string is not ASCII or a partial match is asked for.
  • No intermediate structures. c() and unlist() follow GNU R’s two passes: the first finds the result type, the length and whether any name exists, and the second writes elements and names straight into the result. When every argument is an atomic vector without attributes, no name can arise, so c() skips the naming walk entirely.

Instructions per call at tier 0, measured with callgrind net of the loop:

Call Before After GNU R 4.3
attr(x, "a") 1006 590 1814
attr(x, "a") <- v 3174 992 2520
names(x) <- v 1668 1191 1520
inherits(x, "c") 1266 795 1469
c(a, 4.5) 1782 863 1877
c(a, a, a) 2315 1351 2050
c(list(1, 2), list(3)) 3425 3032 2700
x[[i]], double vector 1155 925 223
x[i] <- 1, index c(2L, 5L) 5273 2146 1580
.Call(r, x), a registered routine 4133 2916 830

A second round took the call machinery itself. A direct entry receives the call as well as the values, so [, .Call and round, whose errors name the call, skip the argument list, the dispatch probe and the handle scope. Appending a name grows an unshared vector in place, a matrix column assignment copies contiguous runs, and Reduce(accumulate = TRUE) runs natively. Instructions per loop iteration with the JIT on, measured with callgrind:

Call Before After GNU R 4.3
x[-1L], five doubles 3179 2485 2372
x[m], logical m 1467 1132 1948
l[c("a", "c")], a list 2295 1959 3775
round(x, 2), a scalar 1785 1129 2526
round(x), per element of a double vector 63 29 76
x <- list(a = 1); x$b <- 2 7739 4292 4387
x <- list(a = 1); x[["b"]] <- 2 7937 4289 6112
m[, j] <- v, per element 35 8 20
.Call(f, 1) with a registered routine 2229 2021 964
Reduce(f, 1:20, accumulate = TRUE), per call 208.4k 93.4k 190.9k
c(a = 1, b = k) 4282 3698 4149

On whole programs (callgrind, JIT on), instruction counts fall by 7.9% on records, 7.9% on simulation, 5.4% on tables, 2.5% on functional and 0.2% on testthat, and change by less than 0.5% on the rest. Peak memory falls by 14 MB on functional and 4 MB on objects and is level elsewhere.

  • Assignment in place. Compiled x[i] <- v on an unshared atomic vector without attributes writes the selected elements directly, recycling v as GNU R does. It declines to the full [<- whenever the result would change shape or a warning is due: NA or zero positions, growth, a coercion that widens x, or a length that does not divide.
  • vapply results. One module checks each result against FUN.VALUE and copies it into the preallocated answer, widening integer and logical values inline, then sets names, dims and dimnames once. Every loop that calls FUN per element uses it, so the checks and their error text exist once.
  • .Call by address. A routine is native code exactly when its NativeSymbolInfo’s address pointer has no tag and a non-null address, so the call reads two slots by position and passes its arguments from the stack, with no name search or allocation before native code runs. A PACKAGE argument or an arity mismatch goes to the general path, which reports the errors.

A third round kept element assignments in slot frames: a for variable the body never reads gets a slot, ForStep and SubAssign find their slot through a constant-to-slot map built with the code, a parenthesized subscript counts as side-effect free, and x[i] <- list(v) writes a list in place. Negative subscripts and builtin argument matching stopped allocating. Instructions per loop iteration, loop included (an empty loop costs 98 in GNU R, 249 at tier 0 and 44 under the JIT):

Loop body Tier 0 before Tier 0 after JIT before JIT after GNU R 4.3
s <- x[[i]] 1456 1196 70 66 617
x[[i]] <- 5 1032 939 77 76 571
x[i] <- 5 1030 943 72 71 571
x[[(k %% 8L) + 1L]] <- 1 8660 1741 9450 118 1585
x[(k %% 8L) + 1L] <- 1 8351 1749 9141 118 1585
x[i] <- list(5) 5928 2229 6307 2446 2183
s <- x[["b"]], a list 1019 821 670 668 1489
s <- x[[i, 2L]], a matrix 1545 1292 968 144 723
x$b <- k 1316 1219 1203 1081 989
s <- x[-1L], five doubles 2455 2149 2174 2372

Under the JIT the scalar element ops run at a fifth of GNU R or less. At tier 0 what is left is dispatch around the builtin rather than the builtin: for x[[i]], the function lookup, the primitive and object branches, the call and the jump cost about 300 instructions around a 130-instruction read, and an assignment’s two guards cost about 100. The computed-subscript read x[[(k %% 8L) + 1L]] still leaves the JIT for tier 0, and x[i] <- list(5) costs more under the JIT than at tier 0.

A fourth round gave tier 0 fast handlers for those ops (beside GetFun’s, which reads a binding cell from the lookup cache): the primitive and object branches, CallBuiltin on [[ and [ through element_access::element_position, and SubAssign in place, by position or by an existing ASCII name. Each declines to the general handler with no side effect, so the op stream the JIT reads does not change. Instructions per loop iteration at tier 0, measured with callgrind against GNU R 4.6.2 (an empty loop costs 180 at tier 0 and 99 in GNU R):

Loop body Before After JIT GNU R 4.6
s <- x[[i]] 846 599 70 553
s <- x[2L] 886 587 56 492
x[[i]] <- 5 726 467 76 519
x[i] <- 5 727 470 72 519
x[[i]] <- 5, a list 708 486 268 687
x[i] <- list(5) 1917 1050 2428 1941
x$b <- k 1006 678 1080 878
s <- x[["b"]], a list 556 546 657 1293
s <- x[-1L], declined 1761 1853 1982 2113
x[["b"]] <- 2, a name append, declined 3565 3672 4031 5243

Net of the loop, every read and store the handlers take is below GNU R except x[2L], 4% above. A shape they decline pays for the attempt, about 5% on a negative subscript. The JIT column shows where compiled code is slower than tier 0: its fallback for a list’s [<-, $<-, $ and a name read calls the general path.

ry’s types are not sound in plain R, because R code can redefine anything at any time. So the JIT treats them in two ways, depending on whether a guarantee exists:

  • Default mode: types are profiles that arrive early. A function annotated fn(values: double[], scale: double) -> double[] starts with that type profile before its first call, so tier 1 compiles it at its first call instead of after warmup. The guards stay. The runtime reads the signature wherever it is written: inline, on the assigned name, or in the #: block above.
  • Strict mode: types are guarantees where a check backs them. Strict mode does not report every imprecision (it never reports Any, nor an Unknown nested inside a type, and the stubs use Any on purpose), so a strict package can still receive an imprecise value from typed code. ry therefore inserts a check wherever an Any or Unknown value flows into a precise type, at an untyped caller and inside typed code alike, and keeps guards on facts that come only from hand-written stubs, because a wrong stub must never mean memory-unsafe compiled code. An atomic type costs a type-code, length and attribute check; a record or list type costs a walk of the value; a function type cannot be checked at the boundary at all and needs a wrapper that checks each call. Between checks, the body is compiled without guards on the checked facts.

The ideas above that come from Roc, Bend and goose, and the ones from those languages and from Vx that ry rejects, are argued in prior art from new language implementations. The JIT never reads the checker’s internal data structures. It consumes the per-function summaries of section 8, which the analysis computes and which are stored with the bytecode.

devtools::load_all (implemented by pkgload) builds a fresh namespace environment, processes NAMESPACE imports, sources every file in R/ in Collate order, runs .onLoad, registers S3 methods and exports, compiles src/ if needed, and attaches the result. It does all of it on every call.

loadfast keeps the same steps for the first load and makes later loads incremental: it hashes the R/ files with MD5 and re-sources only those that changed, rebuilds S3 method tables, and tracks which loaded packages import from which, so reloading a dependency upgrades its importers’ next load to a full reload. Its documentation is candid about the limits: the README explains that it does not track which symbols came from which file, so deleted files and removed functions leave stale objects until a full reload, and TECHNICAL_DEBT.md records that it does not re-read NAMESPACE, so new exports or imports also need one. Compiled code is rebuilt into a new temporary library and loaded beside the old one.

Both tools are eager: every top-level expression in every file runs before the first function is called. GNU R’s installed packages are already lazy, because R CMD INSTALL serializes each object into a lazy-load database and the namespace holds promises that fetch an object on first use. The cost there is the install step, which is exactly what the development loop wants to avoid.

The loader is built, ahead of the runtime, on the GNU R backend that ry R embeds (loading packages is the user page). It splits into three parts, and only the last one knows which runtime runs the code:

  • The item index (semantics::load_index) is derived from the analysis: per item a content hash, whether it is a function definition, the S4, R6 and S3 registrations it makes, and the names it reads while it runs; per file the text R reads and each item’s position; per package which names are lazy. It is incremental like the rest of the analysis (architecture).
  • The plan (crates/loader) is the diff between the index a session has loaded and the current one: what to bind lazily, which statements to run in which order, which bindings to remove, which registrations to undo or make, and whether imports, exports, data, compiled code and hooks need work. It says nothing about how.
  • A backend applies the plan. The GNU R backend sends it to R as an RDS file, and R code installed in the session (runtime.R) applies it. ry’s runtime will apply the same plan natively, so neither the index nor the diff changes when it arrives.

The rules the implementation settled:

  • A function definition is lazy when its name has exactly one top-level writer. The namespace holds a promise that parses and evaluates only that definition on first access. On GNU R the promises are made in C by the makeLazy internal that installed packages use, so binding 24,500 definitions takes about 30 ms. Any second writer, conditional or replacing (f <- memoise(f)), makes every writer of the name eager, in order.
  • Every other top-level expression runs eagerly in Collate order, then the files Collate leaves out in C-locale order, as load_all does. The code files include R/unix/ (or R/windows/), and Collate.unix overrides Collate, as in R CMD INSTALL. Making a provably pure constructor call lazy is not implemented.
  • Imports are copies, and a reload rebuilds them when NAMESPACE imports change. Updating the copies other development packages hold is done after every load: each loaded development package whose NAMESPACE imports from the reloaded one runs its import directives again (.ry_update_importers in runtime.R), which costs one pass over those directives.
  • A reload is a diff over items. A changed or new function is rebound and a deleted one removed. Statements in a changed file are matched to the file’s old statements by content, in order, so an inserted statement runs alone while two swapped writers of a name rerun. A statement reruns when it is new, when it read a binding that changed while it ran (it holds the old value), or when it writes a name that changed (the last writer must win again). A rerun statement that reads a name it or a later statement rewrites first reruns that name’s earlier writers, so f <- memoise(f) sees f as at load time. A reorder of files by Collate falls back to a full load. The property test in crates/loader/tests/test_reload_fuzz.rs checks all of this against a fresh load.
  • Compiled code is built by pkgbuild into src/ and loaded, and a rebuild unloads the previous library first, as load_all does. Loading a rebuild under a new name, so objects that point into the old library stay valid, is not implemented.
  • Installed packages keep GNU R’s installed layout, so the same directory serves GNU R and ry. ry reads their lazy-load databases and .rds files, and builds the object index and bytecode on first load into a cache of its own, never into the package (packages and R versions). This part waits for the runtime.

Hooks run where R runs them: .onLoad after the eager expressions and S3 registration, .onAttach on attach. A reload runs .onLoad again only when the .onLoad definition changed, because it usually sets options or registers things once. ry load and the ry R console are the entry points, and load_all(), attached in tools:ry, serves both ry’s console and plain R sessions; ry does not intercept devtools::load_all().

data.table is fast for specific, well-known reasons: a parallel radix sort (forder) that also drives grouping and joins, “GForce”, which replaces common aggregations inside [ (sum, mean, min, max, .N, …) with specialized grouped C loops, keyed and indexed binary-search joins, in-place update by reference with := (columns are over-allocated so that adding one does not copy the table), and a multithreaded fread. Its weak spots are equally clear: anything outside GForce evaluates R code once per group, all of it is single-threaded at the R level, and its query is not optimized as a whole.

Recommendation: Polars, linked as a Rust crate

Section titled “Recommendation: Polars, linked as a Rust crate”

Polars is a Rust dataframe engine on Arrow’s columnar memory, with multithreaded hash group-by and join kernels, a lazy query planner (predicate and projection pushdown, common-subexpression elimination) and a streaming engine. Because ry is Rust, it can link polars-core and polars-lazy directly, with no FFI layer between the runtime and the engine. The R package polars in the benchmark closure already does this through savvy, which proves the engine works for R users; ry’s table type removes the binding layer and teaches the type checker about it.

The alternatives are weaker for this purpose. DuckDB is excellent, and it already scans R data frames and Arrow data without copying (duckdb-r returns ALTREP-backed results), but it is a C++ engine with a SQL-shaped planner, so ry would embed it through a C API rather than link a Rust library whose plan it can build directly. Arrow’s own compute kernels lack a query planner. A custom engine would spend years re-deriving what Polars has.

The engine is crates/table and its query IR; crates/frames/src/frame.rs makes frames interpreter values and lowers queries into the IR, and crates/libr/src/frame_altrep.rs exposes columns as ALTREP vectors to native code. The user guide is DataFrames.

  • The type is DataFrame, an external pointer that owns a Polars DataFrame. The runtime class is "DataFrame" alone (a DataFrame is no data.frame; as.data.frame() and as.DataFrame() convert), and the checker types it as DataFrame{id: integer[], price: double[], ticker: character[]} (the “DataFrames” section of the typing reference). LazyFrame holds a plan instead of a table, and GroupBy a DataFrame or plan plus its keys.
  • The primary API is Polars’ verbs over expressions (DataFrame.select, with_columns, filter, group_by + GroupBy.agg, sort, join, head, with Expr.col("x") expressions), all qualified names in package:ry. Every verb builds a step of table::lazy::Plan, and an eager verb collects at once. The planner pushes filters below with_columns and projections, and pushes filters, needed columns and row limits into a file scan. The bracket syntax below stays as data.table compatibility and lowers to the same IR.
  • A column reaches R code as a copied R vector, and native code as an ALTREP vector over the Arrow buffer. The interpreter copies a column when R code reads it ($, as.list, a data mask), which is cheap next to the query. The ALTREP path in libr is built but no interpreter path hands it out yet. Element and region reads go to the buffer, and so does DATAPTR_OR_NULL or a read-only data pointer for an integer or double column without nulls, because those bytes are identical in both layouts. A writable pointer (INTEGER, REAL, DATAPTR), a column with nulls and a logical column (bit-packed in Arrow, 32-bit in R) materialize R’s layout once into the ALTREP object’s data2. A write through that pointer changes the R vector and never the frame, which is R’s value semantics. Character columns intern their CHARSXPs on first access, and factors are copied, because R’s one-based int codes differ from the enum’s codes. A column R never materialized comes back into a frame as the same Arrow buffer.
  • Residency is per column: a column lives in the Arrow buffer until R code or native code needs R’s layout. Vx tracks where data lives in the type and makes every transfer explicit (prior art); ry keeps the transfer implicit, and plans a lint for typed code that forces a column to materialize inside a loop.
  • NA maps onto Arrow validity, and NaN stays a value. Integer NA (INT_MIN) and double NA (the NaN with low word 1954) are rewritten into validity at the boundary. A vector coming in from R is copied into a new Arrow buffer; only a column R never materialized comes back zero-copy.
  • Queries go through a small IR to a Polars lazy plan. The evaluator and the bytecode hand tbl[...] on a DataFrame to the lowering before i, j and by are evaluated, so tbl[price > 0, .(total = sum(price)), by = ticker] becomes a Query (rows, j, by, keyby), which lowers to one lazy frame, so the planner sees the whole query and every grouping expression runs as a Polars kernel. The IR covers filters, ordering, positions, projections, grouped aggregation over data.table’s GForce set (sum, mean, min, max, .N, first, last, median, sd, var, plus head and cor), equi, keyed, rolling and non-equi joins, by = .EACHI, mult =, and :=. Lowering adds R’s semantics where Polars differs: integer overflow becomes NA, aggregates propagate NA unless na.rm, %/% and %% follow R’s signs, and joins follow data.table’s row and column layout. A query returns the warnings data.table would raise (an overflowing grouped integer sum, a lossy :=) as data, and the interpreter raises them as R warnings. Anything the IR does not cover, such as an R function inside an aggregation, runs as R code once per group in a data mask that binds the columns it mentions; a lint saying so is planned.
  • := is copy-on-write with reference counts, not over-allocation. A frame whose reference count is one is updated in place, so tbl[, x := y * 2] costs one new column, and a shared frame first copies only its column list, because the Arrow buffers themselves are immutable and shared. In the checker, := rebinds the frame to its extended type. data.table’s := on a data.table object keeps data.table’s own by-reference semantics, because that package runs unchanged.
  • Interop is zero-copy through the Arrow C data interface, for a single column and for a whole frame as a struct array, which is how the R polars and arrow packages, duckdb and nanoarrow exchange data.

The claim that the frame outperforms data.table rests on a benchmark of its own (tools/bench/internal/table/): the db-benchmark group-by and join questions (the suite H2O started and DuckDB Labs maintains), := update loops and a keyed rolling join, run on the same machine against data.table with all threads. just bench-table <dir> --rows 1e7 regenerates a table below (it generates the data on first use), and --groupby-only limits a run to the group-by questions.

At db-benchmark’s 0.5 GB size (1e7 rows, 4 threads), DataFrames from R code under ry run beat data.table under GNU R on every question, and all three runs give the same checksums. The loop that updates 1% of the rows writes only the matching rows, in place, in both engines: data.table builds an index on id4 during the first pass, and a DataFrame builds a row index of id4 on the second id4 == step filter and keeps it until id4 changes. Each cell is the faster of two runs, in seconds, and the last row is each engine’s peak resident memory over the whole run, which is the loop that adds 100 columns. The last column is the same engine driven from Rust, without R.

Question data.table ry, from R ry, from Rust
groupby q1: sum(v1) by id1 0.148 0.018 0.026
groupby q2: sum(v1) by id1, id2 0.148 0.020 0.026
groupby q3: sum(v1), mean(v3) by id3 0.293 0.084 0.097
groupby q4: three means by id4 0.222 0.103 0.105
groupby q5: three sums by id6 0.301 0.107 0.102
groupby q6: median(v3), sd(v3) by id4, id5 0.915 0.097 0.121
groupby q7: max(v1) - min(v2) by id3 0.603 0.040 0.038
groupby q8: the two largest v3 by id6 1.679 0.139 0.133
groupby q9: cor(v1, v2)^2 by id2, id4 0.632 0.060 0.060
groupby q10: sum(v3), count by all six ids 1.675 0.656 0.640
:= on a whole column, 100 times 4.858 0.430 0.555
:= on 1% of rows, 100 times 0.356 0.111 0.105
:= adding a column, 100 times 4.920 0.965 0.755
join q1: small, on id1 0.363 0.096 0.114
join q2: medium, on id2 0.498 0.088 0.103
join q3: medium, left, on id2 0.720 0.123 0.132
join q4: medium, on factor id5 0.543 0.093 0.099
join q5: big, on id3 2.978 0.339 0.391
keyed rolling join 0.120 0.055 0.053
total 21.97 3.62 3.66
peak memory (GB) 7.7 4.5 4.8

At db-benchmark’s 5 GB size (1e8 rows) the table holds the ten group-by questions alone, because the := loop that adds 100 columns needs more than this machine’s 15 GB. The peak is q10, whose answer has nearly one group per row. The R script’s checksum sums an answer’s numeric columns in the engine (DataFrame.select of one Expr.sum per column), because reading a 1e8-row column back as an R vector would copy it.

Question data.table ry, from R ry, from Rust
groupby q1: sum(v1) by id1 1.399 0.179 0.164
groupby q2: sum(v1) by id1, id2 1.674 0.199 0.212
groupby q3: sum(v1), mean(v3) by id3 1.954 1.238 1.197
groupby q4: three means by id4 1.831 1.034 0.971
groupby q5: three sums by id6 2.129 1.309 1.242
groupby q6: median(v3), sd(v3) by id4, id5 9.314 1.130 1.123
groupby q7: max(v1) - min(v2) by id3 6.729 0.813 0.677
groupby q8: the two largest v3 by id6 17.289 2.510 2.185
groupby q9: cor(v1, v2)^2 by id2, id4 3.155 0.582 0.521
groupby q10: sum(v3), count by all six ids 17.497 8.289 8.588
total 62.97 17.28 16.88
peak memory (GB) 12.5 8.5 8.5

The two := loops that write existing columns fit at this size as well (just bench-table <dir> --rows 1e8 --updates-only). The subset loop writes one million rows per pass.

Question data.table ry, from R ry, from Rust
:= on a whole column, 100 times 37.738 6.616 6.431
:= on 1% of rows, 100 times 3.079 0.987 1.040
total 40.82 7.60 7.47
peak memory (GB) 10.8 6.6 6.6

The join questions are measured separately at db-benchmark’s 5 GB size (just bench-table <dir> --rows 1e8 --joins-only), because their inputs are twice the group-by file: join_x and join_big are 5.1 GB of CSV each, and join_x has 63.2 million distinct id6 strings. ry answers all five joins at a peak of 11.6 GB from R and 12.0 GB from Rust. data.table runs out of memory before its first answer: the kernel stops it at 14.3 GB resident.

Question data.table ry, from R ry, from Rust
join q1: small, on id1 out of memory 1.090 0.994
join q2: medium, on id2 out of memory 1.177 1.315
join q3: medium, left, on id2 out of memory 1.449 1.457
join q4: medium, on factor id5 out of memory 1.191 1.197
join q5: big, on id3 out of memory 5.863 6.165
total out of memory 10.77 11.13
peak memory (GB) over 14.3 11.6 12.0

Three choices keep the joins inside the machine:

  • A factor is a code column plus one level table (crates/table/src/factor.rs). The table stores its labels sorted by bytes and front-coded in blocks of 16: each label records how many bytes it shares with the label before it, then the rest. Looking a label up is a binary search over the blocks’ first labels and a scan of one block, so there is no hash index. In tests/test_memory.rs, a table shaped like join_x holds 32 bytes per row, its seven columns’ values and level tables together.
  • A join buckets one side’s rows by a dense code of the key, coded over that side’s value range alone (crates/table/src/join.rs). The bucketed side is the right table of DataFrame.join, unless the left table has at most 65,536 rows and no more than the right. The bucket index is two flat arrays, the probe counts its matches before it writes them, and the answer’s columns are gathered one side at a time.
  • A block of a megabyte or more has a mapping of its own, which returns to the kernel when the block is freed (heap::large::Mapped), so the reader’s and a join’s scratch memory does not stay resident beside the next answer. While a table operation runs, a mapping of 2 MiB or more asks for huge pages, because a query maps its buffers afresh and would otherwise take a page fault per 4 KiB. Outside a table operation a block gets small pages, so a session that uses no table commits only the memory it touches.

tests/test_memory.rs in crates/table pins the bytes per row that the reader, each join question and the grouped sums allocate at their peak and hold afterwards, on four threads and with a margin of 1 to 4 bytes per row. A buffer that scales with the rows, outlives its use and is larger than that margin fails the test. The test counts allocated bytes, not resident memory, and does not check the answers, which tests/test_table.rs does.

The R script uses the Polars-style verbs for every question except the := loops, which measure in-place update and so keep data.table’s syntax. The Rust driver runs the same lazy plans on the same allocator as libR (mimalloc for small blocks, a mapping of its own for each large one), so it measures the engine without the R calls around it.

tools/bench/internal/table/ops.R times data.table’s helpers on the db-benchmark group-by file (10 million rows, 4 threads), and the ops_benchmark bench in crates/table times the engine’s kernels for the same operations from Rust. All three columns give the same checksums. R calls to these names run data.table’s own C under ry’s runtime, which is the middle column; calls from R do not reach the engine’s kernels.

Operation data.table on GNU R data.table on ry’s runtime ry engine, from Rust
fread 3.16 2.36 1.39
fwrite 0.84 0.60 0.70
setkey 0.43 0.42 0.46
setorder 0.90 0.83 0.69
unique 0.083 0.085 0.09
uniqueN 0.12 0.12 0.10
rbindlist 0.90 0.71 0.29
melt 1.21 0.94 0.39
dcast 0.21 0.14 0.26
shift 0.024 0.006 0.004
fifelse 0.092 0.044 0.050
fcoalesce 0.063 0.028 0.047
nafill 0.085 0.051 0.042
rleid 0.026 0.011 0.011
between 0.022 0.013 0.013
%chin% 0.078 0.067 0.036
tstrsplit 5.73 3.71 1.86

Each cell is the faster of two runs. Under ry’s runtime unique is at parity (its median over the two runs is 0.086 s against 0.10 s) and every other helper is faster than on GNU R. The 5 GB size (1e8 rows) needs more than the 15 GB of memory the measuring machine has, because rbindlist(list(x, x)) alone holds 15 GB of columns.

The three benchmark code bases each have a module built on data.table (tables in data science, market_data in finance, trials in biostatistics). Their templates carry a DataFrame variant next to the data.table code, and the typed program uses it, so the typed module is ordinary ry code that checks clean in strict mode. just bench-frames generates both variants from one seed, strict-checks the typed one, runs each module’s functions end to end on the same inputs (the driver is tools/bench/internal/table/frames_driver.R), and refuses the result if any step’s checksum differs. Each cell is a step’s faster run in seconds; memory is each engine’s peak resident size.

10,000,000 rows:

Step data.table on GNU R data.table on ry DataFrame on ry, typed
tables: make_events 1.714 1.245 1.601
tables: summarise_groups 0.547 0.425 0.433
tables: add_features 3.734 3.643 1.727
tables: join_labels 1.301 1.586 0.255
tables: reshape_wide 0.318 0.358 0.429
market_data: fetch_prices 1.193 0.724 1.249
market_data: latest_prices 1.129 0.818 0.393
market_data: to_wide 2.590 2.589 0.884
market_data: read_reference 0.653 0.678 0.590
trials: enrol 1.023 0.514 0.647
trials: visit_schedule 4.274 3.370 1.488
trials: visits_per_month 1.898 1.797 1.929
total 20.37 17.75 11.62
peak memory (GB) 1.53 2.29 2.24

The typed program wins where the engine does the work (windows, joins, pivots, grouped aggregation) and loses a little where a step mostly builds R vectors and hands them over. Building a DataFrame copies each column into the engine, where data.table() keeps R’s vectors, which is most of the gap in make_events, fetch_prices and enrol; visits_per_month spends its time in lubridate::floor_date on both sides.

Three drafts and decisions bear on this, and the mandate settles what they left open. decisions/syntax-semantics.md (“An annotation is one concept with pluggable spellings”) makes the surface spelling pluggable at lowering, names a valid-R inline form through R 4.4’s declare() primitive as the route that keeps every file ordinary R, and leaves a superset dialect as a product decision. development/design/inline-type-syntax.md costed that superset as a dialect compiled to plain R, in its own .ry files, and recommended against building it for inline types alone. The mandate now requires an inline syntax that is on by default and that ry warns about when it is turned off. A declare() form is valid R, so it would need no switch and no warning, which means the mandate asks for the superset. A runtime also changes the draft’s cost argument: ry executes the syntax directly, so there is no compile step and no generated R to keep in sync.

The recommendation is therefore the superset, using the four positions the draft chose:

scale_by <- function<T: numeric>(values: T, scale: T) -> T {
values * scale
}
count: integer <- 0L

The parameter, return and binder positions are syntax errors in GNU R (checked with R 4.3.3: unexpected '<', unexpected ':' and unexpected '->'), so no valid R program changes meaning. The binding position is the one subtle case. R parses count: integer <- 0L as an assignment to count:integer, and running it fails, with object 'count' not found when count does not exist yet and could not find function ":<-" when it does. So the only R programs it could change are ones that already fail. The rest follows from the mandate:

  • The syntax is on by default in ry’s parser and runtime, and ry warns when a project turns it off in ry.toml.
  • declare(type(...)) stays a recognized spelling of the same annotation, for code that must remain valid R, as the pluggable design intends.
  • A typed file keeps the .R extension, which reverses the draft’s .ry files: in a runtime that executes the syntax, a second extension buys nothing. The cost is real, though. Every other R tool (R CMD check, roxygen2, lintr, styler) fails on a typed file under R/. Code that must also run on GNU R, such as a package submitted to CRAN, therefore needs a strip step: a ry build command would write plain R with the inline types moved into #: comments.
  • Comment and inline annotations must agree. When both annotate the same item, ry compares them as types, after alias expansion, and reports a warning on the inline annotation when they differ.
  • Strict mode rejects untyped code. The settled rule is in the typing reference (untyped parameters): a parameter nothing constrains is reported, while an undetermined return or binding is reported once, at the origin it traces to.

This settles the question decisions/syntax-semantics.md left open, and the decision is recorded there (“The inline annotation syntax is a superset of R”).

The checker’s types (TyKind in crates/semantics/src/types.rs) are interned in the salsa database and reference inference variables and arena names, which the runtime should not depend on. So the runtime receives two small, owned, serializable values per function, computed by tracked queries:

  • The runtime type summary comes from the checker’s exported scheme. It keeps what the runtime can use (atomic type, scalar or vector shape, names, record fields, function arity, nominal types) and collapses what it cannot check cheaply (type parameters, deep unions) to “unknown”. It changes only when the function’s interface changes.
  • The runtime body facts come from the function’s body, not its scheme: whether it reflects on its frame, which parameters it always forces, which it only reads, and whether it is free of effects. They change on any body edit, so they live in their own query, and only the function’s own compiled code depends on them. The JIT’s callers read a callee’s facts through a watchpoint, so an edit deoptimizes the callers that relied on the old facts instead of widening the interface, which keeps the interface firewall that makes incremental analysis cheap.

Both are written with a package’s bytecode when it is installed (see “Where bytecode comes from”), so no process needs a cache keyed by content, and salsa’s ids, stable only inside one database, never leave the analysis. This keeps a single source of truth (the checker’s types and the syntax tree) and makes the runtime’s copies derived, recomputable projections. The same summary drives strict mode’s boundary checks, the JIT’s initial profiles, and the table type’s column checks.

The three code bases (finance, data science, biostatistics, about 300,000 lines in about 500 files each, all using the dependency set in AGENTS.md) do not exist yet. They should be generated, and built to exercise what real code exercises rather than to be easy to run:

  • Generator. A ry tool (tools/benchmark-gen/) emits each code base as an R package with a DESCRIPTION that has exactly the benchmark Imports, R/ files of 400 to 800 lines, and tests/testthat/. A seeded generator composes modules from domain templates (pricing, risk, yield curves and GARCH models for finance; data cleaning, feature pipelines, model fitting and reporting for data science; survival, trial simulation and mixed models for biostatistics), so a code base can be regenerated at any size.
  • Realism. Each template uses the dependencies the way real code does: data.table with := and by, R6 classes, S4 generics, purrr maps, foreach with doParallel, httr2 and Azure clients behind mocks, testthat suites, lgr logging, and rlang tidy evaluation. A fraction of each code base carries #: annotations, and a fraction carries inline ones, so the analysis has typed and untyped code to check. GNU R runs the inline-typed files only after the strip step of section 8.
  • Hermetic runs. Network-dependent packages (Azure, Bloomberg via Rblpapi, ODBC) run against local mocks or fakes, so a benchmark run is deterministic.
  • Three measurements: run the test suite under GNU R (on the stripped sources) and under ry (wall time, and outputs must match), check the code base with ry check (cold and incremental keystroke latency), and load it with ry load (cold and incremental reload).

Each step ends with something real running, and each one is a large, whole change.

  1. Corpus and oracle first. Fetch the benchmark closure (the scripts in tools/research/ already resolve it) together with the Suggests its packages’ tests need, install it into a GNU R library, and build a differential harness that runs an R file under GNU R and under ry and compares output, errors and warnings. Write the benchmark generator and generate small versions of the three code bases.

  2. The object model, GC and C API skeleton (done). Objects, interned strings and symbols, the GC with PROTECT, and the libR shared library with the top 150 or so symbols, enough for a C package to load and run its .Call entry points from a Rust test harness. libR exports 149 of the 150 API names the closure uses most (the gap is R_ParseVector, which needs the parser) and 195 of the top 200. brio from the closure and a purpose-written package run under it, built both against ry’s headers and by GNU R’s R CMD SHLIB.

  3. The interpreter and base R. The tier-0 bytecode interpreter, closures, promises, environments, conditions, S3 dispatch, and base R’s primitives and internals in Rust. Base R’s R code (the base, stats, utils, methods, tools and parallel sources) is reused as R source, so only the internals behind .Internal and .Primitive are reimplemented. Run the base package’s own tests through the oracle.

    The interpreter runs. Every oracle case in crates/oracle/cases matches GNU R 4.3.3 (oracle compare --engine ry). Of GNU R 4.3.3’s own tests/*.R, 64 of 66 end with GNU R’s exit status and 27 print exactly GNU R’s output. The others come from three known cases, two of them accepted divergences (pf to the last bit, and env.profile counts that follow GNU R’s string hash), and reg-large needs tens of gigabytes of memory. All six corpus packages that run R code while loading (S7, arrow, nanoarrow, reticulate, minqa and yaml) now load under ry run. Parsed code keeps source references when keep.source asks for them. Connections, sockets included (so parallel’s PSOCK clusters run), are a single implementation shared by the interpreter and libR. R’s graphics engine runs on ry’s runtime with the R_GE_version 17 device API, so base graphics, grid, lattice and device packages such as ragg share one engine, and the built-in pdf, svg, postscript, png, jpeg, bmp and tiff devices are engine devices too. On ragg captures, base graphics, grid and lattice match GNU R pixel for pixel.

    At the full benchmark size (about 308,000 lines per code base), ry’s test suites match GNU R on every test of all three code bases. With the JIT off, finbench’s suite takes 1.13x GNU R’s time; with it on, finbench, dsbench and biobench take 1.30x, 1.35x and 1.21x, so the JIT currently costs cold code about 15% (.agents/memory/backlog.md, “Open: the benchmark packages under ry’s runtime”, has the levers).

  4. The full C API and packages. The rest of the 792 measured names and the BLAS and LAPACK interfaces, ALTREP, connections, unwind protection, C callables, R CMD INSTALL semantics and binary installs. Exit criterion: all 232 packages of the closure install and pass their own tests under ry (with their Suggests installed), and the three generated code bases pass their test suites with output identical to GNU R.

    The C API is done, with evaluation behind a hook the interpreter installs (libr::eval::Evaluator). libR declares and exports all 985 function and variable names that GNU R’s public headers declare, which covers the 444 the closure uses (the rest of the 792 are types, macros and enum constants in the headers). crates/libr/tests/test_headers.rs checks the list in tests/headers/r_api_names.txt against ry’s headers and the exports. libR implements Rmath, Applic, LINPACK, ALTREP, connections and serialization; BLAS and LAPACK are declared in headers and come from the system libraries. Against the corpus library (GNU R 4.3.3 binaries, tests/test_corpus_binaries.rs), 192 of the closure’s 199 non-base compiled packages load and register under ry. Of the other seven, six evaluate R code while loading (S7, arrow, nanoarrow, reticulate, minqa, yaml) and tesseract needs a system library that is not installed. All 23 recorded .Call routines that need no evaluation return what GNU R returns (tests/test_corpus_calls.rs). The rcmd crate compiles packages from source as R CMD INSTALL does: 111 of the 113 compiled packages in the pinned sources build and load. Rblpapi needs Bloomberg’s proprietary blpapi3 library and Rmpfr needs the MPFR headers. rcmd also runs the R-level half of installation (the lazy-load database, Meta/ and help indices) on ry’s interpreter, and oracle install installs the whole corpus that way: 236 of 238 packages install from source and load. Rblpapi needs blpapi3 and magick needs ImageMagick’s Magick++. Two package-test rates are tracked, both counting only the packages whose tests pass under GNU R. With the packages GNU R installed (.corpus/library, oracle packages), ry passes the tests of 140 of 144 (97.2%). With the packages ry installed itself (.corpus/ry-library, oracle packages --installed), it passes 155 of 164 (94.5%). The rest fail on interpreter gaps, and the classes are listed in .agents/memory/backlog.md.

  5. Lazy loading. The item-based loader on top of the analysis index, replacing load_all and loadfast for the code bases. Built ahead of steps 1 to 4 on the GNU R backend; once the runtime exists it applies the same plans.

  6. Inline syntax, agreement warnings and strict mode (done), in the parser, the checker and the runtime, with the runtime type summary and body facts.

  7. The JIT (loops and scalar functions done, general calls next). The SSA IR, speculation, deoptimization and Cranelift backend, then environment and promise elision, then vector fusion, driven by the benchmark code bases and a microbenchmark set (the Ř benchmark suite is a good public start).

  8. The table type, on Polars, with its own benchmark against data.table. The engine, its query IR, ALTREP exposure and the checker’s DataFrame type exist (section 7); the interpreter now runs DataFrames and their Polars-style verbs, and data.table is a normal package that runs on its own code. data.table’s readers, writers and helpers (fread, fwrite, rbindlist, setkey, dcast, melt and the rest) run data.table’s own C, which under ry is at or below GNU R’s time; ry never re-routes them. On db-benchmark’s questions at 1e7 rows on four cores, ry called from R is faster than data.table on every one (section 7 has the table).

  9. Portability. macOS runs the runtime: libR.dylib builds with the install name @rpath/libR.dylib and the full export list, GNU R’s package binaries are rebound to it (section 4), and rcmd reads its toolchain from GNU R’s Makeconf. All of this is verified by cross-compiling from Linux for aarch64-apple-darwin and x86_64-apple-darwin and by running the Mach-O rewriter on a linker-built package; the release smoke test is the first run on a Mac. Windows builds R.dll and ry.exe for x86_64-pc-windows-gnullvm (the UCRT), and ry run runs base R and Rtools-built packages under Wine. rcmd also follows Rtools’ conventions for R CMD INSTALL on Windows, verified only by installing from a Linux host, and the session reports a UTF-8 locale as .utf8, as GNU R does. What is verified and what is open is in section 11.

The JIT comes late on purpose. Until real packages run, there is nothing representative to optimize, and an object model or calling convention changed for the JIT’s sake after the C API exists would break every package. The C API and the object model are designed first, as section 2 argues, and the JIT fits around them.

  • Windows runtime. Built for x86_64-pc-windows-gnullvm and run under Wine, not yet on Windows. What exists:

    • libr builds as R.dll and the CLI as ry.exe, both for gnullvm, so both link the UCRT (api-ms-win-crt-*), as Rtools 4.2 and newer build packages. One C runtime matters because errno, FILE * and malloc/free pairs cross the API: a package that frees what R allocated, or reads errno after Riconv, must see the same runtime’s state. Rust’s windows-gnu target links msvcrt.dll instead, so it is not used.
    • native.c marks its exports __declspec(dllexport) and rustc exports the Rust side, so no .def file is needed, and the linker writes the import library libR.dll.a beside the DLL.
    • The headers’ LibExtern is __declspec(dllimport) extern under _WIN32, as in GNU R, so a package reaches data exports such as R_NilValue through the import table.
    • R.dll carries the Windows-only parts of GNU R’s interface that packages link: the libintl_gettext family (GNU R’s libintl.h renames gettext to it; messages are not translated, so each returns its message id), EmitEmbeddedUTF8, and xerbla_, the BLAS error handler that R’s Rblas.dll and Rlapack.dll import from R.dll. xerbla_ raises GNU R’s error when a package calls the routine, but returns while the interpreter calls BLAS or LAPACK from Rust (DirectFortran in crates/interp/src/linalg.rs), because the jump would cross Rust frames; the routine then returns a negative info, which the interpreter reports.
    • native.c jumps with the CRT’s _setjmp(buffer, NULL) and longjmp. The null frame makes longjmp restore registers only, as on Unix, instead of unwinding through SEH. Neither mingw’s setjmp macro (which unwinds) nor clang’s __builtin_setjmp works: the builtin saves the canonical frame address but its landing code treats it as the frame pointer, so a function whose frame pointer sits above its stack pointer, as R_UnwindProtect’s does, resumes with every local misread.
    • The interpreter’s operating-system calls go through crates/interp/src/platform.rs: CPU times, file modes, the umask, file times, links, globbing, processes, dynamic libraries, errno, the native codeset and iconv. Windows has no iconv(3), so ry converts there itself (UTF-8, Latin-1, ASCII, UTF-16, UTF-32, and the other encodings encoding_rs knows), behind the same interface Riconv exposes to packages.
    • The session reports itself as Windows: .Platform$OS.type is "windows", the path separator ;, the platform x86_64-w64-mingw32, and normalizePath returns backslashes (or winslash) without the \\?\ prefix Rust’s canonical paths carry, makes a missing path absolute as GNU R does, and rejects a winslash other than "/" or "\\". The default packages’ DLLs are found under library/<pkg>/libs/x64/, and the Windows-only routines that utils and grDevices call at load time (winver, getIdentification, readRegistry and so on) are registered (WINDOWS_ROUTINES in crates/interp/src/builtin_libraries.rs).
    • ry.exe and ry-rcmd.exe reserve a 64 MiB main-thread stack and embed ry.exe.manifest, which makes UTF-8 the active code page as R.exe’s manifest does (crates/ry/build.rs, through windres, which rcmd names as its build script too). The session also switches each locale category’s codeset to UTF-8 at startup, so it holds even where the manifest is ignored, and reports the codeset as .utf8, as GNU R does (Wine’s CRT names it .65001).
    • rcmd builds packages the Windows way when the R home’s etc/Makeconf says SHLIB_EXT = .dll, the one fact every other convention is derived from (Platform::of_home): Makevars.ucrt, then Makevars.win, then Makevars; configure.ucrt or configure.win and Makefile.ucrt or Makefile.win, with no fallback to the Unix files; DLLs installed under libs/x64/; and R_ARCH=/x64 for the build and for install.libs.R. Its Makeconf follows the Rtools ABI of GNU R’s etc/x64/Makeconf: gcc/g++/gfortran, -shared -static-libgcc, no PIC flags, and -L"$(R_HOME)/bin/x64" -lR against the libR.dll.a that the home keeps beside R.dll in bin/x64/. A DLL exports what the package’s <name>-win.def lists, or else every global symbol, as GNU R’s winshlib.mk links it. Before an R CMD command the front end reads the home’s etc/Rcmd_environ, linked from GNU R, as GNU R’s Rcmd.exe does, which puts that R version’s Rtools first on PATH, so Rtools’ GCC finds Rtools’ assembler even when another toolchain (MSYS2’s clang64, say) comes earlier on PATH. Windows runs no shell scripts, so the home’s bin/R.exe, bin/Rscript.exe, bin/x64/Rcmd.exe and bin/x64/Rterm.exe (which callr starts) are copies of ry-rcmd.exe, which reads which front end it is from its file name and the home from its location, ignoring an inherited R_HOME. The paths it exports to configure and make use forward slashes, because both read a backslash as an escape. Directories that cannot be linked (Windows needs Developer Mode for symbolic links) are copied.
    • ry run loads R.dll from beside ry.exe, and BLAS and LAPACK from the R installation’s bin/x64/Rblas.dll and Rlapack.dll. DLLs load with LOAD_WITH_ALTERED_SEARCH_PATH from a backslashed path, so Rlapack.dll finds Rblas.dll in its own directory.
    • ry R loads GNU R’s R.dll before its siblings, by full path. ry’s own R.dll beside ry.exe is first in the default search order, and Windows binds a later import of R.dll by name to whichever module of that name loaded first. This ordering is unverified, because the checks do not run GNU R’s DLLs.

    Both binaries must be linked with LLVM’s lld. GNU ld as packaged by Ubuntu’s mingw-w64 (2.41) emits a base relocation for each SECREL32 thread-local offset, so when Windows loads the DLL at another address than its preferred one (ASLR does this routinely), every thread_local access lands on a garbage address. The release workflow uses MSYS2’s clang64 environment on the Windows runner. Cross-building from Linux needs clang, lld, llvm-windres and a clang64 sysroot (MSYS2’s crt, headers, winpthreads, libunwind and compiler-rt packages, or an llvm-mingw release), with a wrapper x86_64-w64-mingw32-clang that runs clang --target=x86_64-w64-windows-gnu --sysroot=SYSROOT -rtlib=compiler-rt -unwindlib=libunwind -fuse-ld=lld:

    Terminal window
    CARGO_TARGET_X86_64_PC_WINDOWS_GNULLVM_LINKER=x86_64-w64-mingw32-clang \
    CC_x86_64_pc_windows_gnullvm=x86_64-w64-mingw32-clang AR_x86_64_pc_windows_gnullvm=llvm-ar \
    WINDRES=llvm-windres cargo build --target x86_64-pc-windows-gnullvm -p libr -p ry-lang

    Verified under Wine 9 with a Windows R 4.5 home whose own DLLs were not executed:

    • Base R scripts that print, sort, summarize mtcars, format dates, run regular expressions, read files, load stats, utils and tools, catch errors and call normalizePath() print what GNU R prints (compared with GNU R’s documented and Unix output, since GNU R itself did not run). l10n_info() reports code page 65001.
    • Package DLLs built from CRAN sources against R.dll’s import library with the Rtools ABI (GCC 14’s headers and static libstdc++ from MSYS2’s ucrt64 environment, driven by clang and lld): jsonlite, data.table (grouping, keys, fwrite/fread, its error messages), digest, cli, uuid and Rcpp, plus a test package that throws Rcpp and C++ exceptions, calls back into R, and lets an R error cross its C++ frames, with every destructor run once.
    • R CMD INSTALL of those six packages through rcmd‘s Windows conventions, then library() and a call into each one’s DLL from libs/x64/ under ry.exe. The install was cross-hosted, because running MSYS2’s gcc, make or sh under Wine is not allowed in the environment that verified it: rcmd on Linux, with a home whose Makeconf is the Windows one and whose compilers are clang wrappers over the ucrt64 sysroot that link libstdc++, winpthreads and zlib statically, as Rtools’ GCC does. The R-code half of that install ran on Linux ry, so the Built: platform was restamped before loading. ry-rcmd.exe assemble under Wine wrote the Windows home, and its R.exe RHOME and Rscript.exe (loading digest, reporting .utf8 locales and code page 65001) ran from it.
    • The BLAS path, with a stand-in Rblas.dll built from C that imports xerbla_ from R.dll as R’s own does: ry loads and calls it, and a bad argument becomes the R error BLAS/LAPACK routine 'DGEMM ' gave error code -3. R’s own Rblas.dll and Rlapack.dll import nothing else from R.dll, which their import tables show.

    Open:

    • Nothing has run on Windows itself; the release smoke test (tools/smoke-test.sh, which runs a script, a BLAS and LAPACK call and a CRAN binary of jsonlite) is the first run.
    • R CMD INSTALL driving Rtools’ own make, sh and GCC on Windows has not run; the release smoke test should install a source package with a Makevars.win (data.table) on the runner.
    • win.version() and Sys.info() report a fixed Windows 10 x64 with no build number.
  • Bytecode compatibility. Installed binary packages contain GNU R bytecode in their lazy-load databases. ry can ignore it and recompile from the deparsed closures, which is the current plan, but it costs install time.

  • How much of base R to reimplement natively versus reuse as R source. The plan above reuses the R sources, which is less work but ties ry to GNU R’s base implementation details.

Settled: licensing. The runtime is GPL-2.0-or-later, as GNU R is, because parts of it translate R’s C sources (licensing). ry still loads base R’s R sources at runtime from the user’s own GNU R installation instead of vendoring them, which keeps ry small and lets it behave like the R version it finds; the reasoning is in .agents/memory/decisions/docs-process.md (“licensing”).

  • R 4.6.2 sources: src/include/ (the public headers), doc/manual/R-exts.texi (API classes), src/library/tools/R/sotools.R (the non-API list).
  • The measured data: tools/research/data/ and the scripts beside it.
  • loadfast: github.com/finccam/loadfast, README and TECHNICAL_DEBT.md.
  • Ř: reactorlabs/rir and its benchmarking tools; Flückiger et al., “R Melts Brains: An IR for First-Class Environments and Lazy Effectful Arguments” (DLS 2019) and “Contextual Dispatch for Function Specialization” (OOPSLA 2020).
  • rcp: Kocourek, Křikava and Vitek, “Copy-and-Patch Just-in-Time Compiler for R” (VMIL 2025), d3s.mff.cuni.cz.
  • FastR status: the GraalVM R runtime reference manual.
  • Renjin status: renjin.org/support.
  • TERR package compatibility: the Spotfire Enterprise Runtime for R release notes.
  • Riposte: Talbot, DeVito and Hanrahan, “Riposte: A Trace-Driven Compiler and Parallel VM for Vector Code in R” (PACT 2012).
  • Copy-and-patch: Xu and Kjolstad, “Copy-and-Patch Compilation” (OOPSLA 2021).