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
22 changes: 21 additions & 1 deletion docs/memory-models.md
Original file line number Diff line number Diff line change
Expand Up @@ -262,7 +262,27 @@ promotion already keep a program's data off the heap, the heap barely matters.
rather than being freed twice. The compiler warns when it can see the mismatch. Building
everything with the same `-mm=` avoids it. (The standard library is not affected — see
above.)
- **Counts are not atomic.** `-mm=rc` is single-threaded today.
- **Sharing objects between threads.** A plain count change is a load, an add and a store, so two
threads taking or dropping references to the same object at once lose updates: the object is
freed while still held, or never. So the top bit of a block's header word marks it *shared*, and
a shared block's count changes atomically (relaxed for a retain; release for a release, with an
acquire fence before the last one frees). A block only one thread holds counts as before; the
test costs the ray tracer about 4.5%. There are three ways to share:
- `Shared.share(v)` marks every block `v` reaches - fields, elements, closures' captures, and
what an `any`, interface or union holds. It marks the graph as it is: a value stored into a
shared object later has to be shared too before another thread can see it.
- An `@atomic class` marks each new object once its constructor has run, and marks every value
stored into one of its fields before the store. A class extending one is `@atomic` too. Not
seen: a store through an interface or a base type that is not `@atomic`, and an element added
to an array a field holds (`obj.items.push(x)`) - share those first.
- `--atomic-rc` treats every block as shared: no marking needed, at about 2.5x the counting cost.
Only in the code built with it, though: the default library and any other library built
without it still count an unmarked block plainly, so share what their code touches on several
threads.

Keeping the objects themselves consistent is the program's job (`@atomic` variables, `Atomics`).
The share routine sits in every type descriptor, so code built before it - a default library
included - cannot be mixed with code built after it; rebuild the library.

## Shared libraries and `-mm=gc`

Expand Down
9 changes: 9 additions & 0 deletions tslang/include/TypeScript/DataStructs.h
Original file line number Diff line number Diff line change
Expand Up @@ -102,6 +102,15 @@ struct CompileOptions
return memoryModel == MemoryModelRC;
}

// --atomic-rc: every reference count change is an atomic read-modify-write, so objects may
// be shared between threads under `rc`. Only `rc` keeps counts; `own` never counts at all.
bool atomicRC = false;

bool atomicRefCounts() const
{
return isRefCounted() && atomicRC;
}

// Whether the ownership operations are live and lower to code - retains and releases under
// `rc`, releases that destroy under `own`. Where only the count itself matters, the
// question is isRefCounted().
Expand Down
16 changes: 15 additions & 1 deletion tslang/include/TypeScript/Defines.h
Original file line number Diff line number Diff line change
Expand Up @@ -414,6 +414,9 @@
// `@value class C` / `@value interface R`: a type whose values are copied, not shared - no identity,
// no vtable, no base (docs/superpowers/specs/2026-10-24-value-types-design.md)
#define VALUE_DECORATOR "value"
// `@atomic class`: objects several threads may use at once (ClassInfo::isAtomic). On a variable,
// an atomic load and store (MLIRGenVariables).
#define ATOMIC_DECORATOR "atomic"
// `@sharedElements class Map<K, V>`: a container that keeps what it is given and hands out
// borrows of it. Under -mm=own each of its type arguments has to be a value, a string (copied) or
// a Shared<T> handle (counted): an object, whose block has one owner, goes through Shared<T>.
Expand Down Expand Up @@ -505,6 +508,13 @@
// ABI break. See docs/reference-counting-evaluation.md sections 9.5 and 9.24.
#define HEAP_BLOCK_IMMORTAL -1

// The top bit of a counted block's header word says the block is shared: other threads may hold
// references to it, so its count changes are atomic (OwnershipRoutineLogic::emitIncRef and
// emitDecRef). The rest of the word is the count, which never grows into the bit. A block's bit
// is set once, by the thread that holds it before any other can reach it, and never cleared.
// HEAP_BLOCK_IMMORTAL has the bit set too, so an immortal test always comes first. It is the
// word's top bit, so the value depends on the word size: 1 << (bits - 1).

// Runtime type descriptor.
//
// The ANY_TYPE slot of an "any" box, and the UNION_TAG_INDEX slot of a tagged union, both
Expand Down Expand Up @@ -534,12 +544,16 @@
// because a tagged union carries its payload inline: copying or dropping one has to retain
// or release a value whose type is only known at run time, and the tag is what knows it.
#define TYPE_DESCR_RETAIN 3
// Address of the type's share routine (`Shared.share`, OwnershipRoutineLogic::getOrCreateShareRoutine),
// on the same terms again: it sets the shared bit of every block a value whose type is only known
// at run time reaches. Null under every model but `rc`.
#define TYPE_DESCR_SHARE 4
// The block header, last so that it sits immediately in front of the name bytes. A tag is a
// `typeof` result, and `typeof x` can be assigned to a `string` and released like any other
// string - so a tag has to look like a payload with an immortal block header, exactly as a
// string literal does, on top of being a name preceded by a descriptor. Both reads work off
// the same pointer: `tag - sizeof(header)` is the marker, `tag - sizeof(record)` the record.
#define TYPE_DESCR_BLOCK_HEADER 4
#define TYPE_DESCR_BLOCK_HEADER 5

// Coarse category of the described type. These correspond one-to-one with the names
// TypeOfOpHelper::typeOfAsString reports, and are derived from that name so the two cannot
Expand Down
7 changes: 6 additions & 1 deletion tslang/include/TypeScript/LowerToLLVM/LLVMCodeHelper.h
Original file line number Diff line number Diff line change
Expand Up @@ -354,7 +354,7 @@ class LLVMCodeHelper : public LLVMCodeHelperBase
// capture box); it is not part of the name the record carries.
mlir::Value getOrCreateTypeDescriptorName(mlir::Type type, std::string name, int kind,
StringRef releaseRoutineName, StringRef retainRoutineName,
StringRef variant = "", uint32_t layout = 0)
StringRef shareRoutineName, StringRef variant = "", uint32_t layout = 0)
{
auto loc = op->getLoc();
auto parentModule = op->getParentOfType<ModuleOp>();
Expand Down Expand Up @@ -405,6 +405,11 @@ class LLVMCodeHelper : public LLVMCodeHelperBase
? (mlir::Value)rewriter.create<LLVM::ZeroOp>(loc, th.getPtrType())
: (mlir::Value)rewriter.create<LLVM::AddressOfOp>(loc, th.getPtrType(), retainRoutineName);
setStructValue(loc, recordValue, retainValue, TYPE_DESCR_RETAIN);
mlir::Value shareValue =
shareRoutineName.empty()
? (mlir::Value)rewriter.create<LLVM::ZeroOp>(loc, th.getPtrType())
: (mlir::Value)rewriter.create<LLVM::AddressOfOp>(loc, th.getPtrType(), shareRoutineName);
setStructValue(loc, recordValue, shareValue, TYPE_DESCR_SHARE);
// a tag doubles as a string payload, so what precedes the name has to read as an
// immortal block header - see TYPE_DESCR_BLOCK_HEADER
setStructValue(loc, recordValue,
Expand Down
Loading
Loading