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.
1. The recommendations
Section titled “1. The recommendations”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 treatSEXPas 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,
PROTECTkeeps 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.
2. The C API surface, measured
Section titled “2. The C API surface, measured”What was measured
Section titled “What was measured”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,@eapifunand@eapivar. - Embedding is the API for programs that embed R.
- Non-API is the list
tools:::nonAPIthatR CMD checkwarns about. - BLAS/LAPACK is every routine declared in
R_ext/BLAS.h,Lapack.handLinpack.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
#includeedges 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
lengthcount only where R would remap them. They do not count in C++ files (since R 4.5.0,R CMD INSTALLcompiles C++ with-DR_NO_REMAP), in packages that defineR_NO_REMAP, or for Rmath’s short names (dt,df,beta) in files that do not includeRmath.h. - Both branches of an
#ifare 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
BODYmacro and simdjson’sOBJECTenumerator. polarsandazidentityfetch their Rust dependencies with Cargo at build time. Only the code in the tarball is scanned, which includes each package’s own glue but notsavvy-ffiorlibR-sys, where their calls into the API live.
The closure
Section titled “The closure”| 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 names
Section titled “The names”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 |
Interfaces that shape the runtime
Section titled “Interfaces that shape the runtime”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 (vroombuilds its lazily parsed columns on it, andcli,vctrsandpakdefine 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_RegisterCCallableandR_GetCCallable, among themRcpp,rlang,vctrs,xts,zoo,Matrixanddata.table).xtscallszoo’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_tryEvalor their relatives). Rcpp and cpp11 callR_UnwindProtectdirectly 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,vroomandxml2read and write R connections;curlandpakcreate custom ones), which exposes theRconnectionstruct layout, versioned byR_CONNECTIONS_VERSION. - Graphics (5 packages:
raggimplements a device, andsystemfonts,farver,laterandpakuse smaller parts). The device API can come late, but the graphics headers also declareRf_ucstoutf8and the interrupt-suspension macros, whichrlang,readxlandlateruse, 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.
What the API implies for the object model
Section titled “What the API implies for the object model”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 afterRf_install, and comparesCHARSXPstrings by pointer, becauseRf_mkCharreturns 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_SHAREDbefore mutating, but some code mutates in place on purpose: data.table’s:=,set()andsetattr()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_PreserveObjectand the protected slot of an external pointer are the other roots. - Pairlists. Calls (
LANGSXP),.Externalarguments and attribute lists are walked withCARandCDR, 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_SHAREDbefore mutating in place. - Struct layouts that are part of the API:
Rcomplex,R_CallMethodDefand its siblings,Rconnection(versioned), the graphicsDevDesc, ALTREP class handles, and the bit patterns ofNA_integer_(INT_MIN) andNA_real_(a NaN with payload 1954). longjmperrors.Rf_errornever 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 inR_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.
The decision: ABI-compatible libR
Section titled “The decision: ABI-compatible libR”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).
3. Prior art
Section titled “3. Prior art”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).
4. The runtime
Section titled “4. The runtime”Language and structure
Section titled “Language and structure”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.
Objects
Section titled “Objects”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
.Externalarguments, 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
Eltmethod, sox <- seq_len(2^31 - 1); x[c(1, 2^31 - 1)]reads two elements instead of expanding 8 GB.
Memory management
Section titled “Memory management”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 parsedgsubreplacement and the pieces of astrsplitelement. - Data that already exists is borrowed: a pattern is looked up by
&str, a replacement refers to slices of its template, andreturn()orbreakunwinds with the jump inline inUnwind. - Text of unbounded length is assembled in one scratch buffer the interpreter owns
(
Interp::text_buffer, throughstrings::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.
Errors across the boundary
Section titled “Errors across the boundary”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 nativeRf_erroror an R error raised in a nestedRf_evaljumps 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
longjmpto 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.
Native packages
Section titled “Native packages”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.
Threads
Section titled “Threads”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.
5. Execution: interpreter and JIT
Section titled “5. Execution: interpreter and JIT”The performance bar
Section titled “The performance bar”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.Rstarts 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,orderandpaste. 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.
Where bytecode comes from
Section titled “Where bytecode comes from”Bytecode is build output, never a cache, so nothing checks whether a stored copy is still valid:
- Installed packages.
ry installandR CMD INSTALLcompile 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 loadand 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 barry load’s lazy loading sets.
When code compiles and what it binds
Section titled “When code compiles and what it binds”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 <- 0for (i in 1:40) { if (i == 10) attach(list(`+` = minus), name = "masking_plus") total <- total + 1}print(total)#> [1] 40When 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’slanguageFuns(+,<-,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.
Code images of installed packages
Section titled “Code images of installed packages”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<-oras.functionmakes 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 noroptions(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 (
verifyincrates/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, whichunloadNamespacecalls, 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 withSIGBUSonce the file shrank. A failed write removes the staging file. - Off switches.
RY_CODE_IMAGE=0ignores images when loading;R CMD INSTALL --ry-no-code-imagewrites 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.
interpretincrates/interp/src/bytecode.rskeeps the frame, the code, the registers and the heap in locals for the whole run, and an error leaves the loop through one exit (thetri!macro) that hands it to the code’s handler table. Single-stepping for the debugger is the same loop, compiled withSINGLE = true. - Slot hints. Every call of one function binds its formals and locals in the same order, so a
GetVarorSetVarsite 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
NULLwhen 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
.Internalwrappers are inlined. A call of one of GNU R’s “safe base internals” (nchar,typeof,inherits,identical,match,rep_len,vector,which.maxand the rest of the list in GNU R’scmp.R), or of a frame-free wrapper ry adds (paste,paste0,sprintf,characterand the rest of thevectorfamily,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 aslist(...)(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 readsError 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 (
Checksincrates/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
xis a length-one double without attributes,+is base+,fis 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
+,cor 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.framein 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_isINT_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] <- 0copies, and deoptimization rebuilds the exact counts. A loop likefor (i in ...) x[i] <- vcopies at most once, on entry ifxis 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
.Callor.Externalcounts 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 andNAsubscripts,[[, and classed vectors with their own[methods stay behind guards, and a fact aboutlength(x)dies whenxis 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::mapruns 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).
What tier 1 does today
Section titled “What tier 1 does today”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,sumof doubles a double,x * yon 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^2for 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=1prints 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
NAand 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 arem[i, j]andm[[i, j]]reads with scalar subscripts on an ordinary matrix; a subscript out of range,NAor below 1 hands the read to tier 0, which raises the error. - Loops over sequences. A
forloop over a compact sequence such as1:norseq_len(n)never expands it: both tiers compute each element from the first element and the increment, sofor (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 orreturn(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,
breakornextraised 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,
sqrtorlogof 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
SEXPat 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_fullat 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.
Untyped performance roadmap
Section titled “Untyped performance roadmap”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 |
The vector kernel layer
Section titled “The vector kernel layer”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_allocOrReuseVectorrule, restricted to what the compiler proves. The evaluator offers a second destination: inx <- f(x, ...), wherefis an element-wise builtin andx’s binding holds the only reference to its value, the result goes intox’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 sharedTRUE,FALSEandNAconstants 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__muldc3and__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,NAversusNaNincluded.^is GNU R’smycpow, andz^2reproducesR_cpow_n’s1 * (z * z). A double beside a complex vector is lifted per element, NA asNA + 0i. - Reductions.
sumon integers,any,all,min,maxandrangeare SIMD kernels;rangefinds both bounds in one pass.prodand the doublesumaccumulate in x87 long double as GNU R does, so they keep scalar loops. - Fusion. For an element-wise tree such as
a * b + corsum(x > 0)whose leaves are constants and variables, the compiler emitsOp::Fusedin 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 asmean(x)insum(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 toOp::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 vectoryalready 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.ymay be a leaf of the tree, as inx <- exp(-x^2 / 2) * 0.5 + x; the pass then keeps each chunk in scratch and copies it overy’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
expandlog. On x86-64 with AVX2 and FMA,expandlogof 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_fmaand__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.pnormand theqnormtails 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^2isx * xand 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.
The native execution model
Section titled “The native execution model”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.
Builtin fast paths
Section titled “Builtin fast paths”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
directfunction that takes its argument values in formal order and returnsNoneto 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 trailingvalueargument. 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()andunlist()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, soc()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] <- von an unshared atomic vector without attributes writes the selected elements directly, recyclingvas 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 widensx, or a length that does not divide. vapplyresults. One module checks each result againstFUN.VALUEand copies it into the preallocated answer, widening integer and logical values inline, then sets names, dims and dimnames once. Every loop that callsFUNper element uses it, so the checks and their error text exist once..Callby address. A routine is native code exactly when itsNativeSymbolInfo’saddresspointer 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. APACKAGEargument 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.
How the static types feed the JIT
Section titled “How the static types feed the JIT”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 anUnknownnested inside a type, and the stubs useAnyon purpose), so a strict package can still receive an imprecise value from typed code. ry therefore inserts a check wherever anAnyorUnknownvalue 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.
6. Lazy package loading
Section titled “6. Lazy package loading”How the existing tools work
Section titled “How the existing tools work”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.
ry’s design
Section titled “ry’s design”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
makeLazyinternal 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
Collateorder, then the filesCollateleaves out in C-locale order, asload_alldoes. The code files includeR/unix/(orR/windows/), andCollate.unixoverridesCollate, as in R CMD INSTALL. Making a provably pure constructor call lazy is not implemented. - Imports are copies, and a reload rebuilds them when
NAMESPACEimports change. Updating the copies other development packages hold is done after every load: each loaded development package whoseNAMESPACEimports from the reloaded one runs its import directives again (.ry_update_importersinruntime.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)seesfas at load time. A reorder of files byCollatefalls back to a full load. The property test incrates/loader/tests/test_reload_fuzz.rschecks 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, asload_alldoes. 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
.rdsfiles, 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().
7. The table type
Section titled “7. The table type”What has to be beaten
Section titled “What has to be beaten”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 design
Section titled “The design”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 PolarsDataFrame. The runtime class is"DataFrame"alone (a DataFrame is nodata.frame;as.data.frame()andas.DataFrame()convert), and the checker types it asDataFrame{id: integer[], price: double[], ticker: character[]}(the “DataFrames” section of the typing reference).LazyFrameholds a plan instead of a table, andGroupBya 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, withExpr.col("x")expressions), all qualified names inpackage:ry. Every verb builds a step oftable::lazy::Plan, and an eager verb collects at once. The planner pushes filters belowwith_columnsand 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 inlibris built but no interpreter path hands it out yet. Element and region reads go to the buffer, and so doesDATAPTR_OR_NULLor 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’sdata2. A write through that pointer changes the R vector and never the frame, which is R’s value semantics. Character columns intern theirCHARSXPs on first access, and factors are copied, because R’s one-basedintcodes 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 (theNaNwith 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 beforei,jandbyare evaluated, sotbl[price > 0, .(total = sum(price)), by = ticker]becomes aQuery(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, plusheadandcor), 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 unlessna.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, sotbl[, 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 adata.tableobject 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
polarsandarrowpackages, 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. Intests/test_memory.rs, a table shaped likejoin_xholds 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 ofDataFrame.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.
Real code: the benchmark modules
Section titled “Real code: the benchmark modules”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.
8. Typing integration
Section titled “8. Typing integration”The inline syntax
Section titled “The inline syntax”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 <- 0LThe 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
.Rextension, which reverses the draft’s.ryfiles: 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 underR/. Code that must also run on GNU R, such as a package submitted to CRAN, therefore needs a strip step: ary buildcommand 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”).
One type model
Section titled “One type model”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.
9. The benchmark code bases
Section titled “9. The benchmark code bases”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 aDESCRIPTIONthat has exactly the benchmarkImports,R/files of 400 to 800 lines, andtests/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
:=andby, R6 classes, S4 generics,purrrmaps,foreachwithdoParallel,httr2and Azure clients behind mocks,testthatsuites,lgrlogging, andrlangtidy 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 withry load(cold and incremental reload).
10. Build order
Section titled “10. Build order”Each step ends with something real running, and each one is a large, whole change.
-
Corpus and oracle first. Fetch the benchmark closure (the scripts in
tools/research/already resolve it) together with theSuggestsits 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. -
The object model, GC and C API skeleton (done). Objects, interned strings and symbols, the GC with
PROTECT, and thelibRshared library with the top 150 or so symbols, enough for a C package to load and run its.Callentry points from a Rust test harness.libRexports 149 of the 150 API names the closure uses most (the gap isR_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’sR CMD SHLIB. -
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,toolsandparallelsources) is reused as R source, so only the internals behind.Internaland.Primitiveare reimplemented. Run the base package’s own tests through the oracle.The interpreter runs. Every oracle case in
crates/oracle/casesmatches GNU R 4.3.3 (oracle compare --engine ry). Of GNU R 4.3.3’s owntests/*.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 (pfto the last bit, andenv.profilecounts that follow GNU R’s string hash), andreg-largeneeds tens of gigabytes of memory. All six corpus packages that run R code while loading (S7, arrow, nanoarrow, reticulate, minqa and yaml) now load underry run. Parsed code keeps source references whenkeep.sourceasks for them. Connections, sockets included (soparallel’s PSOCK clusters run), are a single implementation shared by the interpreter andlibR. 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-inpdf,svg,postscript,png,jpeg,bmpandtiffdevices 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). -
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 INSTALLsemantics and binary installs. Exit criterion: all 232 packages of the closure install and pass their own tests under ry (with theirSuggestsinstalled), 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).libRdeclares 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.rschecks the list intests/headers/r_api_names.txtagainst ry’s headers and the exports.libRimplements 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.Callroutines that need no evaluation return what GNU R returns (tests/test_corpus_calls.rs). Thercmdcrate compiles packages from source asR CMD INSTALLdoes: 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.rcmdalso runs the R-level half of installation (the lazy-load database,Meta/and help indices) on ry’s interpreter, andoracle installinstalls 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. -
Lazy loading. The item-based loader on top of the analysis index, replacing
load_allandloadfastfor the code bases. Built ahead of steps 1 to 4 on the GNU R backend; once the runtime exists it applies the same plans. -
Inline syntax, agreement warnings and strict mode (done), in the parser, the checker and the runtime, with the runtime type summary and body facts.
-
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).
-
The table type, on Polars, with its own benchmark against data.table. The engine, its query IR, ALTREP exposure and the checker’s
DataFrametype 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,meltand 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). -
Portability. macOS runs the runtime:
libR.dylibbuilds with the install name@rpath/libR.dyliband the full export list, GNU R’s package binaries are rebound to it (section 4), andrcmdreads its toolchain from GNU R’sMakeconf. All of this is verified by cross-compiling from Linux foraarch64-apple-darwinandx86_64-apple-darwinand by running the Mach-O rewriter on a linker-built package; the release smoke test is the first run on a Mac. Windows buildsR.dllandry.exeforx86_64-pc-windows-gnullvm(the UCRT), andry runruns base R and Rtools-built packages under Wine.rcmdalso follows Rtools’ conventions forR CMD INSTALLon 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.
11. Open questions
Section titled “11. Open questions”-
Windows runtime. Built for
x86_64-pc-windows-gnullvmand run under Wine, not yet on Windows. What exists:librbuilds asR.dlland the CLI asry.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 becauseerrno,FILE *andmalloc/freepairs cross the API: a package that frees what R allocated, or readserrnoafterRiconv, must see the same runtime’s state. Rust’swindows-gnutarget linksmsvcrt.dllinstead, so it is not used.native.cmarks its exports__declspec(dllexport)and rustc exports the Rust side, so no.deffile is needed, and the linker writes the import librarylibR.dll.abeside the DLL.- The headers’
LibExternis__declspec(dllimport) externunder_WIN32, as in GNU R, so a package reaches data exports such asR_NilValuethrough the import table. - R.dll carries the Windows-only parts of GNU R’s interface that packages link: the
libintl_gettextfamily (GNU R’slibintl.hrenamesgettextto it; messages are not translated, so each returns its message id),EmitEmbeddedUTF8, andxerbla_, the BLAS error handler that R’sRblas.dllandRlapack.dllimport 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 (DirectFortranincrates/interp/src/linalg.rs), because the jump would cross Rust frames; the routine then returns a negativeinfo, which the interpreter reports. native.cjumps with the CRT’s_setjmp(buffer, NULL)andlongjmp. The null frame makeslongjmprestore registers only, as on Unix, instead of unwinding through SEH. Neither mingw’ssetjmpmacro (which unwinds) nor clang’s__builtin_setjmpworks: 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, asR_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 andiconv. Windows has noiconv(3), so ry converts there itself (UTF-8, Latin-1, ASCII, UTF-16, UTF-32, and the other encodingsencoding_rsknows), behind the same interfaceRiconvexposes to packages. - The session reports itself as Windows:
.Platform$OS.typeis"windows", the path separator;, the platformx86_64-w64-mingw32, andnormalizePathreturns backslashes (orwinslash) without the\\?\prefix Rust’s canonical paths carry, makes a missing path absolute as GNU R does, and rejects awinslashother than"/"or"\\". The default packages’ DLLs are found underlibrary/<pkg>/libs/x64/, and the Windows-only routines thatutilsandgrDevicescall at load time (winver,getIdentification,readRegistryand so on) are registered (WINDOWS_ROUTINESincrates/interp/src/builtin_libraries.rs). ry.exeandry-rcmd.exereserve a 64 MiB main-thread stack and embedry.exe.manifest, which makes UTF-8 the active code page asR.exe’s manifest does (crates/ry/build.rs, throughwindres, whichrcmdnames 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).rcmdbuilds packages the Windows way when the R home’setc/MakeconfsaysSHLIB_EXT = .dll, the one fact every other convention is derived from (Platform::of_home):Makevars.ucrt, thenMakevars.win, thenMakevars;configure.ucrtorconfigure.winandMakefile.ucrtorMakefile.win, with no fallback to the Unix files; DLLs installed underlibs/x64/; andR_ARCH=/x64for the build and forinstall.libs.R. ItsMakeconffollows the Rtools ABI of GNU R’setc/x64/Makeconf:gcc/g++/gfortran,-shared -static-libgcc, no PIC flags, and-L"$(R_HOME)/bin/x64" -lRagainst thelibR.dll.athat the home keeps besideR.dllinbin/x64/. A DLL exports what the package’s<name>-win.deflists, or else every global symbol, as GNU R’swinshlib.mklinks it. Before anR CMDcommand the front end reads the home’setc/Rcmd_environ, linked from GNU R, as GNU R’sRcmd.exedoes, which puts that R version’s Rtools first onPATH, so Rtools’ GCC finds Rtools’ assembler even when another toolchain (MSYS2’s clang64, say) comes earlier onPATH. Windows runs no shell scripts, so the home’sbin/R.exe,bin/Rscript.exe,bin/x64/Rcmd.exeandbin/x64/Rterm.exe(which callr starts) are copies ofry-rcmd.exe, which reads which front end it is from its file name and the home from its location, ignoring an inheritedR_HOME. The paths it exports toconfigureandmakeuse 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 runloadsR.dllfrom besidery.exe, and BLAS and LAPACK from the R installation’sbin/x64/Rblas.dllandRlapack.dll. DLLs load withLOAD_WITH_ALTERED_SEARCH_PATHfrom a backslashed path, soRlapack.dllfindsRblas.dllin its own directory.ry Rloads GNU R’sR.dllbefore its siblings, by full path. ry’s ownR.dllbesidery.exeis first in the default search order, and Windows binds a later import ofR.dllby 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 eachSECREL32thread-local offset, so when Windows loads the DLL at another address than its preferred one (ASLR does this routinely), everythread_localaccess 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-windresand a clang64 sysroot (MSYS2’scrt,headers,winpthreads,libunwindandcompiler-rtpackages, or an llvm-mingw release), with a wrapperx86_64-w64-mingw32-clangthat runsclang --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-langVerified 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, loadstats,utilsandtools, catch errors and callnormalizePath()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 staticlibstdc++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 INSTALLof those six packages throughrcmd‘s Windows conventions, thenlibrary()and a call into each one’s DLL fromlibs/x64/underry.exe. The install was cross-hosted, because running MSYS2’sgcc,makeorshunder Wine is not allowed in the environment that verified it:rcmdon Linux, with a home whoseMakeconfis 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 theBuilt:platform was restamped before loading.ry-rcmd.exe assembleunder Wine wrote the Windows home, and itsR.exe RHOMEandRscript.exe(loading digest, reporting.utf8locales and code page 65001) ran from it.- The BLAS path, with a stand-in
Rblas.dllbuilt from C that importsxerbla_fromR.dllas R’s own does: ry loads and calls it, and a bad argument becomes the R errorBLAS/LAPACK routine 'DGEMM ' gave error code -3. R’s ownRblas.dllandRlapack.dllimport 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 INSTALLdriving Rtools’ ownmake,shand GCC on Windows has not run; the release smoke test should install a source package with aMakevars.win(data.table) on the runner.win.version()andSys.info()report a fixedWindows 10 x64with 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”).
Sources
Section titled “Sources”- 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).