Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
28 commits
Select commit Hold shift + click to select a range
ff19f31
Declare the process-heap allocator to LLVM as LLVM declares malloc
ASDAlexander77 Oct 24, 2026
a98a9b7
Design: @value classes and interfaces
ASDAlexander77 Oct 24, 2026
235df52
Plan: @value classes and interfaces
ASDAlexander77 Oct 24, 2026
b66b107
@value: parse, store, reject invalid combinations, print
ASDAlexander77 Oct 24, 2026
7288850
Merge remote-tracking branch 'origin/main' into value-types
ASDAlexander77 Oct 24, 2026
fe0145f
@value interfaces: a literal of a @value interface type is a value
ASDAlexander77 Oct 24, 2026
73bdcbd
@value interfaces: print their fields readonly for importers
ASDAlexander77 Oct 24, 2026
408e445
@value classes: new makes a value, methods take this by value
ASDAlexander77 Oct 24, 2026
8db010c
@value classes: statics set by new, constructor this as the value, no…
ASDAlexander77 Oct 24, 2026
7d023bb
@value: T | null is an optional value; null into a plain @value type …
ASDAlexander77 Oct 24, 2026
212cd4b
@value: one three-state encoding for a missing value; reading one throws
ASDAlexander77 Oct 24, 2026
37e107c
@value: an interface's f?: T is read as the class's optional value
ASDAlexander77 Oct 24, 2026
a6a198a
@value: a plain field for an optional @value member names the reason;…
ASDAlexander77 Oct 24, 2026
12d0b10
@value: values holding references, through generics and closures
ASDAlexander77 Oct 24, 2026
fad3d9d
@value: an interface cycle through a @value type, and a literal-or-nu…
ASDAlexander77 Oct 24, 2026
1506f8a
-mm=own: @value records
ASDAlexander77 Oct 24, 2026
e773888
@value: pin own record exits and split value_interface
ASDAlexander77 Oct 24, 2026
0cc697d
@value: -shared import
ASDAlexander77 Oct 24, 2026
98ec37f
-shared: pin forward references in __decls
ASDAlexander77 Oct 24, 2026
8500b8c
Ray tracer: Vector/Color/Ray/Intersection are @value; results
ASDAlexander77 Oct 24, 2026
f1cba3b
@value: 'this' is not a value inside the constructor
ASDAlexander77 Oct 24, 2026
056c999
@value: a value cannot contain itself
ASDAlexander77 Oct 24, 2026
bdac555
optional chain: skip the rest of the chain after a missing value
ASDAlexander77 Oct 24, 2026
e038d7b
@value spec: the missing-value encoding as emitted
ASDAlexander77 Oct 24, 2026
a44bf71
@value: report 'this' used whole in a discovery run too
ASDAlexander77 Oct 24, 2026
a77ad5f
@value: 'this' in a field initializer is not a value either
ASDAlexander77 Oct 24, 2026
ffd2996
@value: a field cannot hold a generic made from its own type
ASDAlexander77 Oct 24, 2026
90096a5
@value: never type a field as the unspecialized generic
ASDAlexander77 Oct 24, 2026
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
108 changes: 105 additions & 3 deletions tslang/benchmarks/raytrace/README.md
Original file line number Diff line number Diff line change
@@ -1,9 +1,9 @@
# Ray tracer: memory models vs Rust and C++

`rtbench.ts` is `test/tester/tests/raytrace.ts` at 512x512 with a pixel checksum (see its header).
`rtbench_own.ts` is the same program for `-mm=own`, with two source edits: the surfaces, which every
thing shares, are `Shared<Surface>` handles, and `Plane.normal` returns a fresh vector instead of
its own field.
`rtbench_own.ts` is the same program for `-mm=own`, with one source edit: the surfaces, which every
thing shares, are `Shared<Surface>` handles. In both files `Vector` and `Color` are `@value` classes
and `Ray` and `Intersection` `@value` interfaces (see "Results 2026-10-24: `@value`").
`rust/` and `cpp/` each hold two ports of the same algorithm:

- `rust/src/bin/idiomatic.rs`, `cpp/idiomatic.cpp`: `Vector`/`Color` are plain values, things are
Expand All @@ -26,6 +26,108 @@ pwsh tslang/benchmarks/raytrace/bench.ps1
- Rust: `opt-level=3`, `lto="fat"`, `codegen-units=1`, `panic="abort"`
- C++: `clang++ -std=c++20 -O3`, and `cl /std:c++20 /O2 /EHsc /MT`

## Results 2026-10-24: `@value`

Release, Windows 11 x64, the same machine and toolchains as below; branch `value-types` (98ec37ff,
stacked on the "allocator as malloc" change). Two runs of `bench.ps1`, median of 7 runs after a
warm-up each; the table gives the mean of the two medians. For the tslang builds in the table the
two medians were within 1.5 ms of each other; for the C++ `shared_ptr` rows within 6 ms, and for
the `--no-stack-promotion` builds within 7 ms (gc: 256.2 and 249.4). Every build prints the same
checksum.

`rtbench.ts` and `rtbench_own.ts` mark `Vector` and `Color` as `@value` classes (constructor
parameters `public readonly`) and `Ray` and `Intersection` as `@value` interfaces (fields
`readonly`). Their values are structs passed and returned by value, not heap objects. A `@value`
type has no null of its own, so `intersect` returns `Intersection | null` and `closestInter` is
`Intersection | undefined`. No object literal changed. `rtbench_own.ts`'s `Plane.normal` returns
`this.norm` again, since returning a value copies it.

| Build | allocator as malloc | `@value` | vs Rust idiomatic |
|---|---|---|---|
| tslang gc | 1199 ms | 255 ms | 4.7x |
| tslang rc | 630 ms | 172 ms | 3.1x |
| tslang none | 434 ms | 165 ms | 3.0x |
| tslang own | 444 ms | 148 ms | 2.7x |
| Rust idiomatic | 54 ms | 55 ms | 1x |
| Rust Rc-boxed | 490 ms | 492 ms | 9.0x |
| C++ idiomatic (clang) | 50 ms | 50 ms | 0.9x |
| C++ idiomatic (MSVC) | 68 ms | 68 ms | 1.2x |
| C++ shared_ptr (clang) | 829 ms | 903 ms | 16.5x |
| C++ shared_ptr (MSVC) | 896 ms | 977 ms | 18x |

The "allocator as malloc" column is the earlier run below; its Rust and C++ values are that run's
(its "main" column, since those ports do not use tslang's allocator). The Rust and C++ ports did
not change; their `@value` column is this run, for comparison. "vs Rust idiomatic" divides the
`@value` column by this run's Rust idiomatic (54.6 ms). The goal was 1.1x of Rust idiomatic, about 60 ms. own is 2.7x, about 90 ms short of it.

`--no-stack-promotion` changes gc, rc and own by 2% or less; none takes 180 ms without it (9%
slower). This run does not explain the difference for none.

Stack promotion: `--emit=mlir-affine --stack-promotion-report` under rc keeps 17 allocations on
the heap and none of them is a `Vector`, `Color`, `Ray` or `Intersection`. They are the four
closures that capture (`addLight`, `getPoint`, `recenterX`, `recenterY`: "counted-capture") and
the scene built once in `defaultScene` and `exec` (the things, the lights, the camera, the scene
literal, the `RayTracer`). In the optimized LLVM IR, `render` allocates nothing per pixel under
none (LLVM inlines `getPoint` and its two closures and deletes their cells; rc allocates two cells
once per `render`). The one allocation left on the hot path is `addLight`'s: `getNaturalColor`
puts each of the six variables the closure captures in a heap cell (rc adds a seventh block), on
every call.

Where the time goes. A 512x512 render calls `intersections` 2.24 million times (9 million
`Thing.intersect` calls through the interface), `shade` 397 thousand times and `testRay` 1.59
million times. Each row below edits a scratch copy of the benchmark (`rtbench.ts` for none and
rc, `rtbench_own.ts` for own) to remove one cost and keeps the checksum; none of these edits is in
the benchmark. The edits:

- A: `getNaturalColor` does not build `addLight` and call `scene.lights.reduce(addLight,
Color.defaultColor)`; it starts from `let col = Color.defaultColor`, runs `addLight`'s body in a
`for (const light of scene.lights)` loop (a light in shadow is skipped, otherwise
`col = Color.plus(col, ...)`), and returns `col`.
- B: `intersect` returns `Intersection` in `Thing`, `Sphere` and `Plane`; a miss returns
`{ thing: this, ray: ray, dist: 0 }` instead of `null`. `closestInter` is an `Intersection` that
starts as `{ thing: scene.things[0], ray: ray, dist: 0 }`, and the tests `inter != null`,
`isect != null` (`testRay`) and `isect === undefined` (`traceRay`) test `dist` against 0.
- F: `@final` before `class RayTracer`, so calls to its methods are direct.

Median of 7 runs, ms:

| Variant | none | own | rc |
|---|---|---|---|
| the benchmark | 165 | 148 | 171 |
| A: `addLight` written as a loop over the lights, no closure | 89 | 89 | 108 |
| B: `intersect` returns `dist: 0` for a miss, no `\| null` | 148 | 131 | 177 |
| F: `@final class RayTracer` | 147 | 129 | 161 |
| A and B | 73 | 72 | 117 |
| A, B and F | 58 | 58 | 107 |

- A: the `addLight` closure costs 59-76 ms (A alone: 76 ms under none, 59 under own; the same
after B). The IR shows where: 2.4 million cell allocations per render (six per `shade`), which
none never frees and own and rc free again. Closures are a non-goal of `@value`.
- B: `Intersection | null` costs 16-17 ms under none and own (B alone, and B after A). The IR shows
two likely parts, not measured separately: the result is an optional holding a union, 88 bytes,
returned from every `Thing.intersect` call; and every test for null compares the union's type
tag with the string `"null"` (`strcmp`), once per `intersect` result, per `traceRay` and per
`testRay`. Under rc B is 5 ms slower, probably because the miss now carries a `thing` that is
retained and released (not measured separately).
- F: the virtual `RayTracer` methods cost 18-19 ms alone and 14-15 ms after A and B (none and
own). `traceRay` and `testRay` call `intersections` and `shade` through the vtable, so LLVM
inlines none of them and the 88-byte result goes through memory. `@final` makes the calls
direct. The `Thing` and `Surface` calls stay indirect, as in Rust.
- With all three removed, none and own run in 58 ms, 1.06x Rust: these three account for the
whole gap. rc stays at 107 ms. The IR shows that copying an `Intersection` retains and releases
its `thing` through the type's retain and release functions, which are indirect calls; that
this is what keeps rc at 107 ms is a reading of the IR, not measured.
- Checks for a missing value: of the three narrowed reads looked at in the optimized IR, one has
no check left and two keep one. In `RayTracer.intersections` under none, `inter.dist` after
`inter != null` reads the field with no check. In `RayTracer.traceRay` (none and rc),
`isect === undefined` rules out only `undefined` (null and undefined are one encoding), so
passing `isect` to `shade`, which takes a plain `Intersection`, keeps a test for null and its
throw ("a @value value is null or undefined"). Under rc, the `inter.dist` read in
`intersections` keeps one too, because the retain and release calls of `closestInter = inter`
come between the test and the read. Only `traceRay`'s check was measured: writing
`isect == null` there, which folds it, gives the same times. The rc `intersections` re-check was
not isolated.

## Results 2026-10-24

Release, Windows 11 x64, the same machine and toolchains as below; median of 7 runs after a
Expand Down
37 changes: 22 additions & 15 deletions tslang/benchmarks/raytrace/rtbench.ts
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,9 @@
// every pixel's drawing color into a checksum (38837369), so the render cannot be optimized away
// and every build, including the Rust ports in rust/, can be checked against the others.
// print() shows the sum with 6 significant digits, so the low digits are printed separately.
// Vector and Color are @value classes and Ray and Intersection @value interfaces: their values are
// structs copied on the stack, not heap objects. A missing intersection is spelled
// `Intersection | null` (or `| undefined`), since a @value type has no null of its own.
declare function sqrt(v: number): number;
declare function floor(v: number): number;
declare function pow(v: number, s: number): number;
Expand Down Expand Up @@ -32,10 +35,11 @@ class Math {
}
}

@value
class Vector {
constructor(public x: number,
public y: number,
public z: number) {
constructor(public readonly x: number,
public readonly y: number,
public readonly z: number) {
}
static times(k: number, v: Vector) { return new Vector(k * v.x, k * v.y, k * v.z); }
static minus(v1: Vector, v2: Vector) { return new Vector(v1.x - v2.x, v1.y - v2.y, v1.z - v2.z); }
Expand All @@ -54,10 +58,11 @@ class Vector {
}
}

@value
class Color {
constructor(public r: number,
public g: number,
public b: number) {
constructor(public readonly r: number,
public readonly g: number,
public readonly b: number) {
}
static scale(k: number, v: Color) { return new Color(k * v.r, k * v.g, k * v.b); }
static plus(v1: Color, v2: Color) { return new Color(v1.r + v2.r, v1.g + v2.g, v1.b + v2.b); }
Expand Down Expand Up @@ -90,15 +95,17 @@ class Camera {
}
}

@value
interface Ray {
start: Vector;
dir: Vector;
readonly start: Vector;
readonly dir: Vector;
}

@value
interface Intersection {
thing: Thing;
ray: Ray;
dist: number;
readonly thing: Thing;
readonly ray: Ray;
readonly dist: number;
}

interface Surface {
Expand All @@ -109,7 +116,7 @@ interface Surface {
}

interface Thing {
intersect(ray: Ray): Intersection;
intersect(ray: Ray): Intersection | null;
normal(pos: Vector): Vector;
surface: Surface;
}
Expand All @@ -132,7 +139,7 @@ class Sphere implements Thing {
this.radius2 = radius * radius;
}
normal(pos: Vector): Vector { return Vector.norm(Vector.minus(pos, this.center)); }
intersect(ray: Ray): Intersection {
intersect(ray: Ray): Intersection | null {
let eo = Vector.minus(this.center, ray.start);
let v = Vector.dot(eo, ray.dir);
let dist = 0.0;
Expand All @@ -154,7 +161,7 @@ class Plane implements Thing {
constructor(public norm: Vector, public offset: number, public surface: Surface) {
}
public normal(pos: Vector): Vector { return this.norm; }
public intersect(ray: Ray): Intersection {
public intersect(ray: Ray): Intersection | null {
let denom = Vector.dot(this.norm, ray.dir);
if (denom > 0) {
return null;
Expand Down Expand Up @@ -198,7 +205,7 @@ class RayTracer {

private intersections(ray: Ray, scene: Scene) {
let closest = +Infinity;
let closestInter: Intersection = undefined;
let closestInter: Intersection | undefined = undefined;
for (let i in scene.things) {
let inter = scene.things[i].intersect(ray);
if (inter != null && inter.dist < closest) {
Expand Down
46 changes: 27 additions & 19 deletions tslang/benchmarks/raytrace/rtbench_own.ts
Original file line number Diff line number Diff line change
@@ -1,8 +1,12 @@
// @strict-null false
// rtbench.ts for -mm=own, with its two source edits: the surfaces, which every thing shares, are
// `Shared<Surface>` handles, and `Plane.normal` returns a fresh vector, as `Sphere.normal` does,
// instead of its own field. Otherwise the same program and the same checksum (38837369).
// rtbench.ts for -mm=own, with one source edit: the surfaces, which every thing shares, are
// `Shared<Surface>` handles. Otherwise the same program and the same checksum (38837369).
// (`Plane.normal` used to return a fresh vector here; with Vector a @value class, returning its
// own field returns a copy, as in rtbench.ts.)
// print() shows the sum with 6 significant digits, so the low digits are printed separately.
// Vector and Color are @value classes and Ray and Intersection @value interfaces: their values are
// structs copied on the stack, not heap objects. A missing intersection is spelled
// `Intersection | null` (or `| undefined`), since a @value type has no null of its own.
declare function sqrt(v: number): number;
declare function floor(v: number): number;
declare function pow(v: number, s: number): number;
Expand Down Expand Up @@ -32,10 +36,11 @@ class Math {
}
}

@value
class Vector {
constructor(public x: number,
public y: number,
public z: number) {
constructor(public readonly x: number,
public readonly y: number,
public readonly z: number) {
}
static times(k: number, v: Vector) { return new Vector(k * v.x, k * v.y, k * v.z); }
static minus(v1: Vector, v2: Vector) { return new Vector(v1.x - v2.x, v1.y - v2.y, v1.z - v2.z); }
Expand All @@ -54,10 +59,11 @@ class Vector {
}
}

@value
class Color {
constructor(public r: number,
public g: number,
public b: number) {
constructor(public readonly r: number,
public readonly g: number,
public readonly b: number) {
}
static scale(k: number, v: Color) { return new Color(k * v.r, k * v.g, k * v.b); }
static plus(v1: Color, v2: Color) { return new Color(v1.r + v2.r, v1.g + v2.g, v1.b + v2.b); }
Expand Down Expand Up @@ -90,15 +96,17 @@ class Camera {
}
}

@value
interface Ray {
start: Vector;
dir: Vector;
readonly start: Vector;
readonly dir: Vector;
}

@value
interface Intersection {
thing: Thing;
ray: Ray;
dist: number;
readonly thing: Thing;
readonly ray: Ray;
readonly dist: number;
}

interface Surface {
Expand All @@ -109,7 +117,7 @@ interface Surface {
}

interface Thing {
intersect(ray: Ray): Intersection;
intersect(ray: Ray): Intersection | null;
normal(pos: Vector): Vector;
surface: Shared<Surface>;
}
Expand All @@ -132,7 +140,7 @@ class Sphere implements Thing {
this.radius2 = radius * radius;
}
normal(pos: Vector): Vector { return Vector.norm(Vector.minus(pos, this.center)); }
intersect(ray: Ray): Intersection {
intersect(ray: Ray): Intersection | null {
let eo = Vector.minus(this.center, ray.start);
let v = Vector.dot(eo, ray.dir);
let dist = 0.0;
Expand All @@ -153,8 +161,8 @@ class Sphere implements Thing {
class Plane implements Thing {
constructor(public norm: Vector, public offset: number, public surface: Shared<Surface>) {
}
public normal(pos: Vector): Vector { return new Vector(this.norm.x, this.norm.y, this.norm.z); }
public intersect(ray: Ray): Intersection {
public normal(pos: Vector): Vector { return this.norm; }
public intersect(ray: Ray): Intersection | null {
let denom = Vector.dot(this.norm, ray.dir);
if (denom > 0) {
return null;
Expand Down Expand Up @@ -198,7 +206,7 @@ class RayTracer {

private intersections(ray: Ray, scene: Scene) {
let closest = +Infinity;
let closestInter: Intersection = undefined;
let closestInter: Intersection | undefined = undefined;
for (let i in scene.things) {
let inter = scene.things[i].intersect(ray);
if (inter != null && inter.dist < closest) {
Expand Down
Loading
Loading