Skip to content
ry

The typed code file

ry install compiles a package’s typed functions and writes their machine code into the installed package as R/<package>.<build>.ryt, beside the lazy-load database and the bytecode image. A later session maps that file, and the first call of a typed function runs code compiled at install instead of compiling it. crates/typed/src/file.rs is the writer and the loader, and this page is their contract.

Terminal window
$ ry install rates -l library
...
** typed code: closures=2 written=2
** code image: closures=2 written=2
* DONE (rates)
$ RY_TYPED_LOG=1 ry run use.R # library(rates, lib.loc = "library"); print(total(1000, 0.001))
typed: attached `total` for [I64, Dbl] -> Dbl from rates's code file
[1] 718640.9

ry build --aot on a package does what ry install does. R CMD INSTALL --ry-no-typed-code skips the file, as --ry-no-code-image skips the bytecode image, and the two options are independent. A typed function that the file does not supply compiles at its first call, as it would without the file, so a missing, stale or damaged file costs time and never changes what a program prints.

On an iterate build, one Linux machine:

Measure Target Measured
First calls of 50 typed functions of one package 1.43 ms from the file, 18.5 ms compiled in the session
Attaching one function at its first call at most 20 µs about 21 µs, including the lazy-load fetch of the closure
Peak resident memory over library() alone, same 50 calls 2.2 MiB from the file, 5.0 MiB compiled in the session
library(pkg) with a code file at most 0.1 ms slower 7.13 to 7.27 ms with the file, 7.51 ms without
Code pages of two processes that attached the same file shared Shared_Clean in both, one copy in memory
Warm time of file code over session code (same package) within 2% orders 1.010, report 1.014, sales 0.975, drawdown 1.006, vasicek 0.996
Typed benchmark functions left out for a match over any tag at most a tenth 9 of 170 (5.3%)

The file holds every function that ry run --aot compiles up front for the same program, except those left out for a match over any tag: pidigits 18 of 18, spectralnorm 5 of 5, nbody_2 5 of 5, orders 1 of 3.

The file holds one compiled version per pair of a closure and its argument types, which is the key of the session’s table of compiled code (COMPILED in crates/typed/src/typed.rs). The roots are the package’s typed closures whose parameter annotations say which values arrive from R, compiled for those types, and the file also holds every typed function of the same database that a root calls, for the types the caller passes.

The install log counts the typed closures, the versions written, and the versions left out by reason:

Reason in the log What it means
compiles with its caller a parameter type R cannot pass, such as a record, so the closure is not a root; it is in the file when a root calls it
does not compile the typed core refuses the function, so it runs in the interpreter in every session
matches over any tag its code tests for the shapes the installing process had confirmed, which depends on the process
assumes a lookup a session cannot check it resolved a name in an environment the file cannot name, or it took the result of an untyped function as a table value because of the function’s return annotation
calls R with code a session cannot rebuild an R call site holds a value the file cannot store
makes an R call that is not in a body a session can find an R call site is not a call in the body of the closure or of a typed function lowered into it
calls a function it cannot name, has a type a file cannot name the same for a callee and for a type
does not compile into a file, does not link the code needs a relocation the writer does not resolve, or a relative call that does not reach
calls a function left out of the file it calls a version of the same file directly, and that version is left out for one of the reasons above

A closure copied at run time (an R6 method bound by $new(), a function after environment<-, the per-class copy of an S4 method) is another closure with another environment, so it compiles in the session, and the closure it was copied from still attaches. A --train workload adds the versions it compiled for the package’s own closures, among them a version for the type a Num.from_r or a List.from_r the checker cannot type gave in that run (a guessed conversion, below).

Session code embeds process addresses as 64-bit immediates. File code instead loads every word that differs between processes from an offset table that sits directly below the code, so the code bytes are the same in every process and are never written after they are mapped. The backend emits both through one seam (Slot in crates/typed/src/backend.rs): in the session a slot’s word is an immediate, and in a file it is a table load.

Slot kind Filled with When
Helper(id) the address of runtime helper id, or of a libcall such as fmod when the file is mapped
Interrupt the address of interp::unwind::INTERRUPT_REQUESTED when the file is mapped
Shape(entry) this process’s id for the file’s shape entry, after interning it when the file is mapped
Constant(entry) the static box of that shape (shapes::constant) when the file is mapped
Data(offset) the address of the file’s read-only data plus offset, which holds static strings when the file is mapped
Site(index) a *const RCall built for R call site index when its function attaches
Callee(index) the entry of a typed function of another namespace when its function attaches

Slot n is the 8-byte word at base - 8 * (n + 1), where base is the start of the code. Helper ids are positions in one static array of helper addresses, so a file is only valid for the ry build that wrote it, which the header checks. A shape id never appears in the code as an integer: lowering writes Constant::Shape, and the backend turns it into a Shape slot.

ssa::Relocatable (crates/ssa/src/lower.rs) compiles the file’s functions. Lowering to Cranelift IR runs on the main thread, because it reads the typed core’s thread-local shape table, and Relocatable::finish compiles the IR on worker threads, lays the functions out in declaration order and resolves every relocation: a table load against its slot, a libcall against a Helper slot, and a call between two functions of the file as a direct relative call. A function with any other relocation is left out.

All integers in the header are little-endian u64s after the magic and a u32 version.

Part Contents
Header magic RYTYPED\0, format version 3, then the hash of the build identity, the .rdb’s length and modification time, the hash of the code target (triple and ISA flags), the metadata’s length, the number of slots, the code’s offset, the code’s length, the data’s length, where the shared code starts, the metadata’s hash, the shared part’s hash, and a reserved zero word
Metadata LEB128 varints, in this order: strings, shapes, slots, lookups, sites, callees, functions
Padding zeros up to the code’s offset, a multiple of 64 KiB
Code the function bodies and their trampolines, then the code every function shares (the free entries)
Data after the code, padded to 8 bytes: the read-only data that Data slots address

The metadata tables are:

  • functions: per version, sorted by (record offset, position, signature): the binding name for the log, the closure’s .rdb record offset and its position in that record, its argument and result types, the offsets of its body and trampoline, where its code ends and that code’s hash, whether it calls R, and its lists of lookups, sites, callees and confirmed shapes.
  • lookups: per name a version resolved when it compiled: the symbol, whether a function was looked up, the environment the lookup starts from and the one it found the binding in, and the class of what it found (below).
  • sites: per R call site, every field of its RCall: the environment, where the call stands (the closure whose body holds it, which is the version’s own or one a lookup finds, and the item positions from the body to it), the called function’s lookup, per argument its tag, code, type and conversion, how the result is used, and the flags diverges and effect_free.
  • callees: per typed function a version calls, its lookup, the signature the caller compiled against, and whether it is a version of this file (a direct call) or reached through a Callee slot.
  • shapes: per record layout, tag union and list item type that the code or a signature names, enough to intern it in another process. An entry names only entries before it.
  • slots and strings: the slot kinds above, and the bytes of every name.

A closure is named by the offset of its lazy-load record in the package’s R/<package>.rdb and its position among the closures of that record, in the order serialize::unserialize_with_closures yields them. The .rdb stamp in the header ties those offsets to one database. sysdata.rdb is never named.

A lookup records what lowering found, because lowering specializes on more than a function’s identity, and attaching requires the same class:

Class What lowering did with it What attaching requires
File a direct call, or the function inlined a typed closure noted from the same package, record, position and database stamp
Base code for the builtin by name is_base_function holds for what the name finds
Table a call that gives a table value is_table_function holds
Library the standard library constant inlined the name finds the standard library’s own binding
Other a call through a Site slot a function that is not typed

An environment is named as the global environment, base, base’s namespace, the standard library, a package’s namespace, its imports, or an attached package, so a later session finds its own.

The install session that writes the bytecode image (crates/rcmd/src/code-image.R, run by write_code_image in crates/rcmd/src/rcmd.rs) loads the namespace, runs the training workload if one was asked for, and calls ryTypedCodeWrite(package) before ryCodeImageWrite, because writing the image ends the recording of the database’s closures that the code file names. The writer:

  1. Takes every typed closure the install recorded from the package’s database, with its record offset and position.
  2. Takes as roots every version the training workload compiled for one of those closures, then compiles each closure for its declared types, and repeats the pass while it confirms new shapes, as ry run --aot does for a script.
  3. Lowers every version the roots reach through calls of the same database again for the file target, and leaves out what the table under “What the file holds” lists.
  4. Encodes, compiles, lays out and links the versions that remain. When one of them cannot be written, it is left out with every version that calls it directly, and the writer starts this step again over the rest, so every lookup, site, callee and code byte of the file belongs to a written version.
  5. Parses its own bytes, so a file the loader would refuse fails the install, and writes the file to <name>.ryt.partial before it renames it into place, so a process never maps a half-written file.

Two writes against one installed package give the same bytes. images::prune removes the .ryt files of other builds as it removes their .ryc files.

Noting closures. When a session first reads from a package’s .rdb, it checks once whether a code file of its own build lies beside it. If one does, every lazy-load fetch from that database goes through unserialize_with_closures and notes each typed closure’s record offset, position and the database’s stamp at that first check (code_image::typed_note). A noted closure is preserved for the rest of the session, so its address never names another closure. A database without a file is read as before and notes nothing, so an untyped package pays nothing.

Opening. The first miss in compiled_or_refusal for a noted closure opens the file. It reads the header and the metadata, and the file is refused when the magic, version, build or target differ, when the header’s stamp differs from the note’s (a reinstall in a running session replaced the database while the notes still name the old one), when the file’s length disagrees with the header, or when the metadata’s hash or any index in it is wrong. Parsing is a pure function over bytes (parse), so it is fuzzed without a session. A refusal prints one RY_TYPED_LOG line and leaves the package’s functions to compile in the session.

Mapping. The loader reserves one range for the table and the code, makes the table writable, and on Linux maps the code and data from the file read-only and executable over the upper part. Where that mapping is refused, and on every other Unix, it maps fresh memory at the same place, reads the code and data into it, makes it executable and flushes the instruction cache; the table keeps its fixed distance and only the sharing is lost (RY_TYPED_FILE_COPY=1 forces this path). Windows does not use the file. The loader checks the hash of the shared code and data, interns every entry of shapes, and fills the slots that do not wait for a function. A mapping lasts for the life of the process, because static strings point into it and frames of its code may be on the stack when a namespace unloads.

Attaching. A version is attached when its closure is first called with its argument types, and attaching builds the same Compiled entry a session compile would:

  1. Find the version by the closure’s note and the argument types. No version is a miss.
  2. Check the hash of the version’s code.
  3. Resolve each lookup in the live session and require the class it recorded.
  4. Build each R call site’s RCall from its recorded fields and fill its slot. The call and a conversion’s call are the nodes of the live closure’s body at their recorded positions, not copies: the interpreter knows a call by its node when it replays a recorded call or reads what a conversion gave.
  5. For each callee: a version of this file attaches first, depth first, and must be noted from the same record and position; a typed function of another namespace attaches or compiles through compiled_or_refusal, and its entry fills the Callee slot. Its result type must match the signature the caller compiled against.
  6. Confirm the shapes the version constructs (shapes::confirm), as a session compile does. For a site whose conversion was guessed, record that the conversion gave the type the version was compiled for (numbers::assume_conversion). When this session already saw it give another type, the version is refused; when it later gives another type, the native code gives up at that site, the interpreter runs the call again with the values its R calls returned, and the version is stale from then on, as session code compiled for a guess is.
  7. Insert the entry into COMPILED and root the closure. The entry’s speculations are its own lookups and those of every callee, and its epoch is the earliest of theirs.

Any failure marks the version as failed, prints one RY_TYPED_LOG line with the reason, and leaves the closure to compile in the session. A version whose direct callee is still being attached misses, so mutually recursive functions compile in the session; a function that calls itself attaches. No package in the benchmark set or the typed benchmark programs has mutually recursive typed functions, so attaching a cycle as one unit waits for one that does. An attached entry holds no JIT memory, so it does not count toward MAX_COMPILED. Every later call checks the entry’s speculations as it does for session code, so a rebinding after unlockBinding drops the entry the same way. RY_AHEAD_MISS=1 makes every attach miss, which the tests of the fallback use.

A file from another build. Under ry run --aot, a namespace that loads with typed closures and a .ryt file of another build compiles its typed functions as it loads, and prints one line:

Terminal window
$ ry run --aot use.R
ry: another build of ry installed rates, so its typed functions compiled as it loaded; reinstall it to compile them at install
[1] 718640.9

A package with no file at all is not compiled at load, because telling an untyped package from one installed with --ry-no-typed-code would mean reading every function.

ry build --aot --exe main.R writes a script’s code file into an executable: a copy of ry with a payload appended (crates/ry/src/executable.rs).

Part Contents
ry the running ry executable, byte for byte
Padding zeros up to a multiple of 64 KiB, so the code maps straight from the executable
Code file a typed code file in the format above, for the script’s top-level definitions
Metadata the run flags as a little-endian i32, then four fields, each a little-endian u64 length and its bytes: the script’s name, its elaborated text, and the runtime library and base R tree of a development build (empty for a release)
Trailer five little-endian u64s (the code file’s offset and length, the metadata’s offset and length, the metadata’s FNV-1a hash) and the magic ry-exe\0\x01

At start ry reads its own last 48 bytes. Without the magic it is ry. With it, a trailer whose offsets do not meet end to end or whose metadata’s hash does not match is an error that asks for a new build, and a sound one runs the script as ry run --aot does, without the checker.

A script has no lazy-load database, so its code file names a closure differently:

  • Record and position. The closure of the top-level definition at index i among the script’s expressions is record i, position 0. A definition that is not a typed closure has no entry.
  • Database stamp. The header’s database length and modification time hold the elaborated text’s length and its hash, so code built from another text never attaches.
  • Package. The file’s package is "", which no package can be called, and a File lookup of a script function requires a closure noted from the executable’s script.

The closures a run makes are noted with these names before the script’s first statement runs, so the first call of each attaches from the executable through the same checks as a package’s file. A function the file does not hold compiles at its first call, and a file the script sources is read from disk and compiles as it does under ry run --aot.

A code file is machine code that the process runs, like the shared objects in a package’s libs directory, and it is trusted to the same degree: whoever can write the installed package can run code in the session. The hashes and stamps catch truncation, a file from another build and a database that changed, not an attacker.

Test What it pins
typed_scripts_agree_however_they_compile installs every generated typed script as a package and runs it with its file, then with RY_AHEAD_MISS=1 file code prints what every other tiering prints, and the fallback does too
install-typed-package.scenario the attach line; RY_GC_STRESS and the copy path over attached code; ry build --aot; a file from another build under ry run --aot; a match over a closed union, a record parameter and a sort comparator attached after the process interned other shapes; a closure copied at run time; a reinstall in a running session
fuzz_typed_code_parse (crates/typed/tests/test_typed/file.rs, cargo fuzz target typed_code_parse) random valid metadata reads back as written, and truncated or bit-flipped bytes never panic the parser
fuzz_typed_code_file (crates/ry/tests/test_scenarios.rs) an installed file damaged in its header, metadata or code never attaches, and a second write against one install gives the same bytes
build-exe.scenario an executable prints what ry run --aot prints for the same arguments, attaches every function and compiles none, and compiles at first calls under RY_AHEAD_MISS=1
typed_scripts_agree_however_they_compile with executables every generated typed script built with ry build --aot --exe prints what the interpreter prints, and at least half of them attach from the executable
fuzz_executable_payloads (crates/ry/tests/test_fuzz.rs, cargo fuzz target executable_payload) a payload reads back as written, and a damaged trailer or metadata reads as damaged or as no payload, never as a payload that lies outside the file