Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
37 changes: 36 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -767,7 +767,9 @@ what to do about it, and **[docs/own-memory-model.md](docs/own-memory-model.md)*

**Compared with Rust:** under `-mm=own`, tslang matches Rust on numeric array loops and runs
within about 1.35x of idiomatic Rust on an object-heavy ray tracer, about 6.6x faster than the
same program written with Rust's `Rc` for every object. Put shortly: within 1.1-1.4x of idiomatic
same program written with Rust's `Rc` for every object. Written without interfaces and closures,
as Rust code with enums is, the ray tracer takes the same time as that Rust code under every
memory model (measured on Linux x64). Put shortly: within 1.1-1.4x of idiomatic
Rust, and on par for tight array loops. These are two benchmarks of our own, measured on Windows
x64; on the ray tracer the remaining gap is in code generation (calls through interfaces, structs
returned through memory), not in memory management, since `-mm=own` runs within a few percent of
Expand Down Expand Up @@ -800,6 +802,39 @@ the earlier results. `-mm=rc` went from 110 to 96 ms when retains and releases t
interface began changing the count inline; what it still pays over the other models is counting
itself, not thread safety (atomics are only used for blocks shared between threads).

The same ray tracer written without interfaces and closures, the way a Rust program with enums
and `match` is (`rtbench_static.ts`: a thing is one `@final` class with a shape tag and a
`switch`, the rest `@value` classes and free functions), against that Rust program
(`rust/src/bin/static_dispatch.rs`). Ubuntu 24.04 x64, a 4-core cloud VM, release build, median of
21 runs, measured 2026-11-11:

| build | time | vs Rust (enums) |
| --- | --- | --- |
| `-mm=gc` | 50 ms | the same |
| `-mm=none` | 50 ms | the same |
| `-mm=own` | 50 ms | the same |
| `-mm=rc` | 51 ms | the same |
| Rust, enums and `match` | 50 ms | |
| Rust, `dyn Thing` (the port above) | 113 ms | |

On the same machine the version with interfaces above (`rtbench.ts`) takes 77 ms under `-mm=gc`,
78 under `-mm=none`, 82 under `-mm=own` and 111 under `-mm=rc`, against 116 ms for the Rust port
with `dyn Thing` and 70 ms for the C++ port: a call through an interface or a callback now first
tries, as direct calls, the few functions of the module it can be. With `@final interface Thing`
(only classes of this module implement it) no call through a pointer is left, and it takes 71 ms
under `-mm=gc` and `-mm=none`, the C++ port's time, and 106 ms under `-mm=rc`.

With nothing called through a vtable or a function value the four memory models run alike, and
tslang takes the time of the Rust program (under `-mm=none` it executes 606 million instructions
against Rust's 604 million). It was 1.2x (60 ms) before seven changes to the optimizer made for
this benchmark: an array's length and data are read without a branch on null, a C math function
is the LLVM intrinsic (TypeScript has no `errno`), `--emit=exe` makes functions that are not
exported internal, the inliner's threshold at `--opt_level=3` is 325, jump threading runs before
the first SimplifyCFG, a select over a phi with a constant is made a branch again once its
function's callees are inlined, and under `-mm=rc` a local alias is not counted where nothing can
release what it names. The steps, their open questions and what is left are in
[docs/raytrace-rust-parity.md](docs/raytrace-rust-parity.md).

Loops over arrays are measured by [tslang/benchmarks/numeric](tslang/benchmarks/numeric/README.md):
six kernels over flat arrays of 4096 elements, with Rust and C++ ports. On Windows 11 x64 (release
build, median of 15 runs, ms, measured 2026-11-10):
Expand Down
7 changes: 7 additions & 0 deletions docs/own-memory-model.md
Original file line number Diff line number Diff line change
Expand Up @@ -667,6 +667,13 @@ that can run TypeScript code (one that takes a callback).
of type `C` is a direct call, with no vtable lookup
([design](../tslang/docs/superpowers/specs/2026-10-19-final-classes-design.md)).

`@final interface I`: only classes of this module implement `I`. A value of type `I` is made from
a class object or null and nothing else: a cast from an object literal, from another interface's
value or from `any` is an error, as are an interface that extends `I`, `export` on `I`, and an
exported or declared class that implements it. In return, with `--opt_level=3` a call of one of
`I`'s methods that at most four functions can be is those functions called directly, with no call
through a pointer left.

Under `-mm=own` it matters more. A method of an exported class that is not `@final` may be
overridden in another module, by a method that frees anything; the compiler cannot see that
method, so a call of it ends every borrow the caller holds, and its result is not known to be
Expand Down
175 changes: 175 additions & 0 deletions docs/raytrace-rust-parity.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,175 @@
# The ray tracer against Rust: where it stands and what is left

`tslang/benchmarks/raytrace/rtbench_static.ts` is the ray tracer written without interfaces and
closures; `rust/src/bin/static_dispatch.rs` beside it is the Rust program it mirrors (`enum Thing`,
`enum Surface`, `match`). This note says where the two stand, what was done to get there, and what
is left. The benchmark's [README](../tslang/benchmarks/raytrace/README.md) has every measurement.

## Where it stands

Ubuntu 24.04 x64, a 4-core cloud VM, 2026-11-11, `bench.sh` with 21 rounds, median wall time. A
few percent either way is noise on this machine.

| Build | Time | vs Rust |
|---|---|---|
| tslang gc | 50.5 ms | 1.02x |
| tslang rc | 50.6 ms | 1.02x |
| tslang none | 49.6 ms | 1.00x |
| tslang own | 49.5 ms | 1.00x |
| Rust, enums and `match` | 49.6 ms | 1x |

Instructions executed (callgrind): tslang 606 million under `-mm=none` and 622 million under
`-mm=rc`, Rust 604 million.

Under every memory model the program takes the time of the Rust one, within this machine's noise.
Not measured: Windows, and any machine but this one.

## What was done

Seven changes to the optimizer for the static version, all in `tslang/tslang/transform.cpp` except the first
(`include/TypeScript/LowerToLLVM/ArrayLayout.h`). Together they took the benchmark from 60 to
50 ms.

| Change | Why |
|---|---|
| An array's length and data are loaded through a select between the header and a constant empty header | The branch on a null array kept both loads inside the loop |
| A call of a C math function is the LLVM intrinsic | `sqrt` could write `errno`: a call, a branch to libm, and no hoisting over it |
| `--emit=exe` with `--opt` makes functions that are not exported internal | The inliner inlines a function with one call left whatever its size |
| The inliner's threshold at `--opt_level=3` is 325 | `intersections` cost 285 against 250 and stayed a call in every ray's loop |
| SROA and jump threading run before the first SimplifyCFG (levels 2 and 3) | A miss's `dist === 0 ? Infinity : dist` became a select that jump threading does not unfold |
| A select whose condition compares a phi and is decided for one of the phi's constants is made a branch, then jump threading (levels 2 and 3, after a function's callees are inlined) | The caller's `if (dist < closest)` was selects before `intersect` was inlined, so a miss still ran the minimum |
| `-mm=rc`: a retain of a local and its release on every path are removed when the function and everything it calls store only into locals and can release nothing (before the inliner) | `const things = scene.things` was counted up and down on every ray |

Open questions about these, none of them checked:

- The threshold of 325 applies to every program at `--opt_level=3`. Its effect on code size and
compile time of a large program was not measured.
- The early SROA and jump threading, and the select pass with its jump threading, run on every
function at levels 2 and 3. Compile time was not measured.
- Internal functions: the rule is "not `export`ed, not the entry point, no section, in an
executable". The test suite passes; a program whose other objects call a function of the main
module by name without `export` would no longer link.
- The select pass makes a branch of a select that the processor may have predicted worse than it
computed the select. It fires only where a predecessor's constant decides the condition, and the
branch that is left for the other predecessors is given back to SimplifyCFG. No program but
these two benchmarks was timed with it.

- The rc pass trusts its own reading of what a function can do: a store is local when LLVM's
`getUnderlyingObject` finds an alloca or a parameter, a callee is safe when it is defined in the
module and passes the same test, or is a declaration that only reads memory. It finds the pair
by the names `tsret_` and `tsrel_`. The test suite passes and
`00rc_local_alias_no_count.ts` covers a callee that releases the array; nothing else checks it,
and an object shared between threads and released by another thread while the alias is in use
is not considered (the function's caller holds a reference to the owner in the case measured).

## What is left

Nothing in time, on this benchmark and this machine. What follows is what still differs.

### 1. rc counts that the alias pass does not reach

The pass removes a pair only around code that can release nothing. `rtbench.ts` (interfaces,
closures) under rc is unchanged at 119 ms against 84 ms for the other models: its counts are on
interface values and closure cells, and its loop calls through `Thing`, which the pass cannot see
through. The benchmark's README has what those counts are.

### 2. Differences that are still there and cost nothing measured

With the instruction counts level, these are no gap, but the code still differs from Rust's in
them:

- `Thing[]` holds pointers, one load more a thing than Rust's `Vec<Thing>`. `@value class Thing`
puts the things in the array itself and measured no faster: each element is loaded whole, all
six fields, before the shape is tested.
- `const light = lights[i]` loads all six numbers of the light at the top of the iteration, where
Rust reads the color only for a point the light reaches. Sinking the loads with LLVM's sink pass
changed nothing.
- LLVM's SLP vectorizer packs two of a vector's three components in the Rust build and does not
fire in tslang's. Turning it off in Rust does not change Rust's time.
- `let i = 0` is a 32-bit counter beside a 64-bit induction variable. With `let i: index = 0` the
program executes more instructions and takes the same time.

### 3. The benchmark with interfaces

`rtbench.ts` (interfaces, closures) against the ports written the same way (`dyn Thing`,
`std::unique_ptr<Thing>`), the same machine and day:

| Build | Time |
|---|---|
| tslang gc | 77 ms |
| tslang none | 78 ms |
| tslang own | 82 ms |
| tslang rc | 111 ms |
| Rust idiomatic | 116 ms |
| C++ idiomatic (clang) | 70 ms |

Two more changes got it there from 84 ms (119 under rc): a call through a function value first
tries, as direct calls, the few functions of the module that have its type
(`SpeculativeDirectCallPass`, `--opt_level=3`), and null of a `@value` type with a pointer writes
only its pointers (`CastLogicHelper::nullOfValueType`).

Every model is ahead of the Rust port here, but the Rust port is slow on this machine for the
instructions it executes (900 million; the C++ port 828 million in 70 ms; tslang none 1148
million). On Windows the Rust and C++ ports were level at 57 and 52 ms with tslang at 73 to
77 ms, and nothing in this note was measured there. Take the C++ port as the target: tslang was
1.1x of it under gc and none, 1.6x under rc, with these two changes.

A third change since: `@final interface Thing`. `@final` on an interface says only classes of
this module implement it; the compiler refuses everything else that could make a value of it (an
object literal, another interface's value, `any`, an extending interface, `export`, an exported
class), and a call of its method is then exactly the functions in the vtables the module made:
the last is called without a test and no call through a pointer is left. `rtbench.ts` takes
70.7 ms under gc and 70.8 under none (from 75.5; the C++ port 68 to 73 ms in a noisy run of the
same hour), 105.5 under rc (from 111.6). gc and none are at the C++ port within this machine's
noise; rc is about 1.5x of it.

What is left, from the disassembly of the `addLight` closure before `@final`, none of it measured
apart:

- Done by `@final interface Thing`: the call kept for "any other function", which made
`scene.things` be read again on every iteration, and the compare with the null `Thing`'s method.
- `@final` is the source saying it. The compiler could find the same for an interface that is not
exported, in an executable, with no annotation; that is not done. `Surface` and `Scene`, made
from object literals, cannot be `@final`.
- `intersect` returns `Intersection | null` through memory, 80 bytes with the optional's flag,
and its caller tests it there.
- rc: an `Intersection` holds a `Thing`, counted when it is copied, and the `addLight` closure's
captures are counted. 33 ms over the other models; the alias pass above does not apply (the
loop calls through a pointer). The benchmark's README (2026-11-10, "rc") has the counts.
- Open questions for the direct-call pass: it adds up to four tests and calls at every call
through a pointer of a matching type, so code grows; candidates are chosen by LLVM function
type alone, so an unrelated function of the same type is tried too; the order is by size. No
program but the benchmarks was timed with it, and compile time was not measured.

## How to measure

```bash
TSLANG=<path to tslang> RUNS=21 bash tslang/benchmarks/raytrace/bench.sh
```

Wall time on a shared machine moves by a millisecond between runs, which is a third of what is
left, so compare instruction counts first:

```bash
valgrind --tool=callgrind --dump-instr=yes --compress-pos=no --callgrind-out-file=cg.out ./rtbs_none
```

Everything is inlined into `traceRay` (`trace_ray` in Rust), so the function totals say nothing.
Join the per-address counts of `cg.out` with `objdump -d` and group the instructions by how often
they ran: blocks of the two builds that ran the same number of times are the same block of the
source (6,353,088 is a thing in the shadow loop, 4,764,816 a sphere there, 1,588,272 a shadow ray,
397,068 a shaded point), and the number of instructions in each is what to compare.

The inliner's decisions:

```bash
tslang --emit=llvm --opt --opt_level=3 --no-default-lib --mm=none rtbench_static.ts -o s.ll
opt -passes='cgscc(inline)' -pass-remarks-missed=inline -disable-output s.ll
```

LLVM's hidden options are accepted on tslang's command line (`--help-hidden`), which is the quick
way to try a threshold.

One comparison to keep in mind: the Rust port written as `rtbench_static.ts` is, a miss as
`f64::INFINITY` and the thing by its index, takes 73 ms: the form costs Rust more than it costs
tslang.
Loading
Loading