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
53 changes: 36 additions & 17 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -765,35 +765,54 @@ what to do about it, and **[docs/own-memory-model.md](docs/own-memory-model.md)*

### Performance

**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
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
`-mm=none`, which frees nothing.

The ray tracer benchmark in [tslang/benchmarks/raytrace](tslang/benchmarks/raytrace/README.md)
(`raytrace.ts` at 512x512; release build, Windows 11 x64, median of 7 runs; the tslang rows measured
2026-10-31, the Rust and C++ rows 2026-10-21 on the same machine) against Rust and C++ ports of the
same code. The benchmark's copy marks `Vector` and `Color` as `@value` classes and `Ray` and
`Intersection` as `@value` interfaces, so they are structs passed by value rather than heap
objects; `-mm=own` builds `rtbench_own.ts`, the same program with the shared surfaces as
`Shared<T>` handles.
(`raytrace.ts` at 512x512; release build, Windows 11 x64, median of 9 runs, measured 2026-11-10)
against Rust and C++ ports of the same code. The benchmark's copy marks `Vector` and `Color` as
`@value` classes and `Ray` and `Intersection` as `@value` interfaces, so they are structs passed by
value rather than heap objects; `-mm=own` builds `rtbench_own.ts`, the same program with the
shared surfaces as `Shared<T>` handles.

| build | time | vs Rust (values) |
| --- | --- | --- |
| `-mm=gc` | 71 ms | 1.3x slower |
| `-mm=none` | 70 ms | 1.3x slower |
| `-mm=own` | 77 ms | 1.4x slower |
| `-mm=rc` | 110 ms | 2.0x slower |
| Rust, values (`Copy` vectors and colors) | 55 ms | |
| C++, values (clang -O3 / MSVC /O2) | 51 / 69 ms | |
| Rust, every object in an `Rc` | 492 ms | 8.9x slower |
| C++, every object in a `shared_ptr` (clang / MSVC) | 830 / 899 ms | 15x slower |
| `-mm=gc` | 73 ms | 1.3x slower |
| `-mm=none` | 73 ms | 1.3x slower |
| `-mm=own` | 76 ms | 1.35x slower |
| `-mm=rc` | 96 ms | 1.7x slower |
| Rust, values (`Copy` vectors and colors) | 56 ms | |
| C++, values (clang -O3 / MSVC /O2) | 52 / 70 ms | |
| Rust, every object in an `Rc` | 500 ms | 8.9x slower |
| C++, every object in a `shared_ptr` (clang / MSVC) | 834 / 908 ms | 15x slower |

On 2026-10-21, before `@value`, every vector and color the program computed was a heap object and
the same benchmark took 1298 ms under `-mm=gc` and 599 ms under `-mm=rc`; `@value` took it to 255
and 172 ms. The rest of the gain came from capturing parameters by copy instead of in heap cells,
calling methods nothing overrides directly, and testing a union for null without a tag. `-mm=rc`
still pays for retains and releases in the inner loops. The benchmark's README has every step and
the earlier results.
the earlier results. `-mm=rc` went from 110 to 96 ms when retains and releases through an
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).

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 (release build, Ubuntu 24.04
x64 on a 4-core cloud VM, median of 9 runs, ms, measured 2026-11-10).
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):

| build | saxpy | triad | stencil | dot | matmul | hash |
| --- | --- | --- | --- | --- | --- | --- |
| `-mm=gc` | 87.8 | 107.9 | 92.5 | 91.6 | 53.8 | 64.6 |
| `-mm=rc` | 86.2 | 114.4 | 93.9 | 94.8 | 56.7 | 65.5 |
| `-mm=none` | 88.1 | 112.6 | 95.1 | 92.6 | 53.4 | 62.7 |
| `-mm=own` | 85.6 | 111.8 | 94.1 | 91.2 | 53.8 | 62.3 |
| Rust (`Vec<f64>`, iterators) | 77.0 | 93.5 | 94.7 | 93.5 | 52.0 | 65.4 |

On Ubuntu 24.04 x64 (a 4-core cloud VM, median of 9 runs, ms, measured 2026-11-10):

| build | saxpy | triad | stencil | dot | matmul | hash |
| --- | --- | --- | --- | --- | --- | --- |
Expand Down
19 changes: 17 additions & 2 deletions tslang/benchmarks/numeric/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -63,8 +63,23 @@ its own run.
packed floating-point and integer instructions, against 234-282 for gc, none, own and Rust, and
own's `hash` loop was not vectorized either. Linux does not run the pass. Declared `captures(none)`, rc and
own are level with Rust on every kernel.
- `noalias` on the resize's result, which LLVM also says of `realloc`, vectorizes a few more loops
under none, but crashes five array tests (0xC0000409); it is left out.
- The resize's result is `noalias` too, as LLVM says of `realloc`. That first broke five array
tests: the resize was declared `allockind("realloc,uninitialized")`, and with the result fresh
LLVM read the grown block's old elements as undefined (`b[0]` after a splice). LLVM declares
`realloc` `allockind("realloc")` alone, and so does the helper now. A later, quieter run with
both changes, ms:

| Build | saxpy | triad | stencil | dot | matmul | hash |
|---|---|---|---|---|---|---|
| tslang gc | 87.8 | 107.9 | 92.5 | 91.6 | 53.8 | 64.6 |
| tslang rc | 86.2 | 114.4 | 93.9 | 94.8 | 56.7 | 65.5 |
| tslang none | 88.1 | 112.6 | 95.1 | 92.6 | 53.4 | 62.7 |
| tslang own | 85.6 | 111.8 | 94.1 | 91.2 | 53.8 | 62.3 |
| Rust | 77.0 | 93.5 | 94.7 | 93.5 | 52.0 | 65.4 |

The four models are level with each other, and with Rust except on saxpy and triad (1.1-1.2x).
The triad loop is vectorized, unrolled twice and checks once per call that the three arrays do
not overlap, which Rust's `&mut` does not need; the rest of that difference was not looked into.
- The C++ port is about twice as slow here as on Linux (82 packed instructions): clang with the
MSVC standard library does not vectorize most of its loops. That is the port's build, not a
baseline to compare with.
Expand Down
30 changes: 30 additions & 0 deletions tslang/benchmarks/raytrace/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -53,6 +53,36 @@ median of 9 runs after a warm-up; every build prints the same checksum.
looked into.
- The heap change is for loops over arrays; here it moves the models by no more than the noise.

### rc: an interface's count changed inline

A sampling profile of the rc build (the program's main thread sampled every 0.2 ms, 20 runs,
symbols from a `--di` build), with each function's share scaled by `pow_fma`'s, which does the same
work under every model, put rc's extra time in `Sphere.intersect` (+17 ms against none), the inlined
`addLight` closure that holds `testRay` and `intersections` (+16 ms), the out-of-line retain and
release routines (+17 ms) and `traceRay` (+7 ms). Most of it was one thing: an `Intersection`
holds an interface, `thing`, and an interface is retained and released through the type descriptor
its vtable names - vtable, tag, descriptor, then an indirect call LLVM can neither inline nor pair
with its counterpart. `Sphere.intersect` retained `thing` that way on every hit, and spilled the
80-byte result to the stack to give the routine its address.

Every type whose value is a reference to a block counted the plain way (class and object literal
instances, strings, `any` boxes, `Shared<T>`) now shares one retain routine, and under rc a retain
through an interface whose descriptor names that routine adds one to the count inline; a release
takes one off inline when it is not the last reference on a block only this thread holds. The last
reference, shared and immortal blocks and every other kind still go through the descriptor.

| Build | before | interface count inline |
|---|---|---|
| tslang rc | 110-114 ms | 95.9 ms |
| tslang gc, none, own | 71-76 ms | 73.1, 73.3, 75.8 ms |

What is left of rc's extra time is counting itself: `scene.things` is retained on every iteration
of `intersections` (the read of an interface's field is owned, since the slot may hold a getter's
cell), and `closestInter = inter` copies a reference that `inter` gives up at the end of the
iteration, where a move would do. Hoisting `scene.things` out of the loop by hand saves about 8 ms.
Cancelling `return x`'s retain against the local's release, tried as a pass, measured nothing: with
both halves inline LLVM already folds them.

## Results 2026-11-10: Linux

Release, Ubuntu 24.04 x64, a 4-core cloud VM (Xeon 2.1 GHz); main d78c735 with the collector's
Expand Down
194 changes: 188 additions & 6 deletions tslang/include/TypeScript/LowerToLLVM/OwnershipRoutineLogic.h
Original file line number Diff line number Diff line change
Expand Up @@ -724,8 +724,26 @@ class OwnershipRoutineLogic
return ss.str();
}

// The one retain routine of every type whose value is a reference to a counted block of its own -
// string, class and object instances, a Shared<T> handle, an "any" box: buildRetainBody takes one
// more reference to the block and nothing else for each of them, so they share it. Sharing it is
// what lets a retain or release through an interface's tag see, by comparing the descriptor's
// retain slot with this routine, that `this` is such a block (interfaceThisIsPlainBlock).
static constexpr const char *PLAIN_BLOCK_RETAIN_ROUTINE = "__tslang_retain_block_slot";

static bool isPlainBlockType(mlir::Type type)
{
return isa<mlir_ts::StringType>(type) || isa<mlir_ts::ClassType>(type) || isa<mlir_ts::SharedType>(type) ||
isa<mlir_ts::ObjectType>(type) || isa<mlir_ts::AnyType>(type);
}

std::string getRetainRoutineName(mlir::Type type)
{
if (isPlainBlockType(type))
{
return PLAIN_BLOCK_RETAIN_ROUTINE;
}

std::stringstream ss;
ss << "tsret_" << (size_t)hash_value(type);
return ss.str();
Expand Down Expand Up @@ -1317,18 +1335,182 @@ class OwnershipRoutineLogic
ArrayRef<LLVM::GEPArg>{INTERFACE_VTABLE_TYPE_SLOT});
auto tagValue = rewriter.create<LLVM::LoadOp>(loc, ptrTy, tagSlot);
emitIfNonNull(tagValue, [&]() {
if (retaining)
{
retainViaDescriptor(tagValue, thisSlot);
}
else
// Under rc what an interface holds is nearly always a class or object instance, a
// block counted the plain way, and then the count is changed here rather than through
// the descriptor's routine: an indirect call LLVM can neither inline nor cancel
// against its pair. The ray tracer's `Intersection { thing }` was retained and
// released through it on every hit.
if (!compileOptions.isRefCounted())
{
releaseViaDescriptor(tagValue, thisSlot);
if (retaining)
{
retainViaDescriptor(tagValue, thisSlot);
}
else
{
releaseViaDescriptor(tagValue, thisSlot);
}

return;
}

auto isPlain = interfaceThisIsPlainBlock(tagValue);
emitIfElse(
isPlain,
[&]() {
auto thisValue = rewriter.create<LLVM::LoadOp>(loc, ptrTy, thisSlot);
if (retaining)
{
emitIncRef(thisValue);
}
else
{
emitReleasePlainBlock(tagValue, thisValue);
}
},
[&]() {
if (retaining)
{
retainViaDescriptor(tagValue, copyToSlot(rewriter.create<LLVM::LoadOp>(loc, ptrTy, thisSlot)));
}
else
{
releaseViaDescriptor(tagValue, copyToSlot(rewriter.create<LLVM::LoadOp>(loc, ptrTy, thisSlot)));
}
});
});
});
}

// Does the descriptor `tagValue` points at retain with PLAIN_BLOCK_RETAIN_ROUTINE - is what its
// type's values point at a block counted the plain way (isPlainBlockType)? The release routine of
// such a type is "drop one reference, and destroy and free the block when it was the last"
// (buildBody), so emitReleasePlainBlock can drop one that is not the last itself.
mlir::Value interfaceThisIsPlainBlock(mlir::Value tagValue)
{
TypeHelper th(rewriter);
TypeConverterHelper tch(typeConverter);
TypeDescriptorLogic tdl(rewriter, tch, op->getLoc());

auto loc = op->getLoc();
auto ptrTy = th.getPtrType();

ensurePlainBlockRetainRoutine();

auto recordPtr = tdl.getRecordPtrFromTag(tagValue);
auto retainPtrSlot =
rewriter.create<LLVM::GEPOp>(loc, ptrTy, TypeDescriptorLogic::getRecordType(rewriter, tch.convertType(th.getIndexType())),
recordPtr, ArrayRef<LLVM::GEPArg>{0, TYPE_DESCR_RETAIN});
auto retainFn = rewriter.create<LLVM::LoadOp>(loc, ptrTy, retainPtrSlot);
auto plainRetain = rewriter.create<LLVM::AddressOfOp>(loc, ptrTy, PLAIN_BLOCK_RETAIN_ROUTINE);
return rewriter.create<LLVM::ICmpOp>(loc, LLVM::ICmpPredicate::eq, retainFn, plainRetain);
}

void ensurePlainBlockRetainRoutine()
{
auto parentModule = op->getParentOfType<ModuleOp>();
if (parentModule.lookupSymbol<LLVM::LLVMFuncOp>(PLAIN_BLOCK_RETAIN_ROUTINE))
{
return;
}

TypeHelper th(rewriter);
auto loc = op->getLoc();

OpBuilder::InsertionGuard insertGuard(rewriter);
rewriter.setInsertionPointToStart(parentModule.getBody());

auto funcOp = rewriter.create<LLVM::LLVMFuncOp>(
loc, PLAIN_BLOCK_RETAIN_ROUTINE, th.getFunctionType(th.getVoidType(), {th.getPtrType()}), LLVM::Linkage::Internal);
auto *entryBlock = funcOp.addEntryBlock(rewriter);
rewriter.setInsertionPointToStart(entryBlock);
emitIncRef(rewriter.create<LLVM::LoadOp>(loc, th.getPtrType(), entryBlock->getArgument(0)));
rewriter.create<LLVM::ReturnOp>(loc, ValueRange{});
dropDebugLocations(funcOp);
}

// Drops one reference to `payloadPtr`, a block counted the plain way whose type's descriptor is
// `tagValue`: a reference that is not the block's last, on a block only this thread holds, is a
// decrement here; the last one, a shared or an immortal block, or any block under --atomic-rc goes
// to the descriptor's release routine, which decides the same thing again and destroys the block
// when it has to.
void emitReleasePlainBlock(mlir::Value tagValue, mlir::Value payloadPtr)
{
TypeHelper th(rewriter);
TypeConverterHelper tch(typeConverter);
LLVMCodeHelperBase ch(op, rewriter, typeConverter, compileOptions);

auto loc = op->getLoc();
auto llvmIndexType = tch.convertType(th.getIndexType());

emitIfNonNull(payloadPtr, [&]() {
if (compileOptions.atomicRefCounts())
{
releaseViaDescriptor(tagValue, copyToSlot(payloadPtr));
return;
}

auto blockPtr = ch.getBlockPtrFromPayloadPtr(loc, payloadPtr, llvmIndexType);
auto count = emitCountLoad(loc, llvmIndexType, blockPtr);
auto one = rewriter.create<LLVM::ConstantOp>(loc, llvmIndexType, rewriter.getIntegerAttr(llvmIndexType, 1));
// a shared or an immortal word is negative, and so is not greater than one
auto notLast = rewriter.create<LLVM::ICmpOp>(loc, LLVM::ICmpPredicate::sgt, count, one);
emitIfElse(
notLast,
[&]() {
rewriter.create<LLVM::StoreOp>(loc, rewriter.create<LLVM::SubOp>(loc, llvmIndexType, count, one),
blockPtr);
},
[&]() { releaseViaDescriptor(tagValue, copyToSlot(payloadPtr)); });
});
}

// A slot of its own holding `value`, for a routine that takes the storage of a value: given the
// address of a field instead, a value a function keeps in registers would be spilled whole to
// the stack around the call. The alloca goes to the entry block of the function being built.
mlir::Value copyToSlot(mlir::Value value)
{
TypeHelper th(rewriter);
auto loc = op->getLoc();

mlir::Value slot;
{
OpBuilder::InsertionGuard insertGuard(rewriter);
auto *entryBlock = &rewriter.getInsertionBlock()->getParent()->front();
rewriter.setInsertionPointToStart(entryBlock);
auto count = rewriter.create<LLVM::ConstantOp>(loc, th.getI32Type(), rewriter.getI32IntegerAttr(1));
slot = rewriter.create<LLVM::AllocaOp>(loc, th.getPtrType(), value.getType(), count);
}

rewriter.create<LLVM::StoreOp>(loc, value, slot);
return slot;
}

// Runs `thenBody` when `condition` holds and `elseBody` when it does not, and leaves the insertion
// point on the continuation.
void emitIfElse(mlir::Value condition, llvm::function_ref<void()> thenBody, llvm::function_ref<void()> elseBody)
{
auto loc = op->getLoc();

auto *currentBlock = rewriter.getInsertionBlock();
auto *continuationBlock = rewriter.splitBlock(currentBlock, rewriter.getInsertionPoint());
auto *thenBlock = rewriter.createBlock(continuationBlock);
auto *elseBlock = rewriter.createBlock(continuationBlock);

rewriter.setInsertionPointToEnd(thenBlock);
thenBody();
rewriter.create<LLVM::BrOp>(loc, ValueRange{}, continuationBlock);

rewriter.setInsertionPointToEnd(elseBlock);
elseBody();
rewriter.create<LLVM::BrOp>(loc, ValueRange{}, continuationBlock);

rewriter.setInsertionPointToEnd(currentBlock);
rewriter.create<LLVM::CondBrOp>(loc, condition, thenBlock, elseBlock);

rewriter.setInsertionPointToStart(continuationBlock);
}

// Body of the capture-box routines: they take the storage holding the box pointer, like
// every other routine, so each begins by loading the box out of it. A box that holds nothing
// of its own frees the block and stops there.
Expand Down
8 changes: 6 additions & 2 deletions tslang/lib/TypeScript/ProcessHeapPass.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -123,7 +123,11 @@ class ProcessHeapPass : public mlir::PassWrapper<ProcessHeapPass, ModulePass>
}
else if (name == PROCESS_HEAP_REALLOC)
{
allocKind = (1 << 1) | (1 << 3);
// not Uninitialized: the block keeps its contents up to the old size, and LLVM
// declares realloc `allockind("realloc")` alone. Said uninitialized, a load from the
// grown block - an array's first element after a splice - could fold to undef once the
// result was also `noalias`
allocKind = 1 << 1;
takesBlock = true;
}
else if (name == PROCESS_HEAP_FREE)
Expand Down Expand Up @@ -158,7 +162,7 @@ class ProcessHeapPass : public mlir::PassWrapper<ProcessHeapPass, ModulePass>
// Without it on realloc, a store into a grown array's elements might have written the
// array's header, so a loop over the elements loaded their pointer again on every
// iteration and was not vectorized.
if (!takesBlock && funcOp.getNumResults() > 0)
if (funcOp.getNumResults() > 0)
{
funcOp.setResultAttr(0, LLVM::LLVMDialect::getNoAliasAttrName(), mlir::UnitAttr::get(context));
}
Expand Down
Loading
Loading