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
Original file line number Diff line number Diff line change
@@ -0,0 +1,156 @@
# -mm=own: what an append-only global keeps is immortal

## 1. Why

A callback a C library calls later has to stay alive after the call that registered it. Under gc a
TypeScript wrapper keeps it in a module-level array that is only ever pushed to, so Boehm sees it:

```ts
let retained: Callback[] = [];
setRenderCallback(handler: Callback) { retained.push(handler); Donut_SetRenderCallback(this.handle, handler); }
```

Under own that push is a move: the wrapper keeps `handler`, so its caller must give it up, and a
bound method `this.onRender` cannot be given up (its object is the caller's `this`, owned by
`main`). A closure that captures a local fails the same way ("captured by a closure that escapes,
and is still used here"). Since `__MEMORY_MODEL__` the generated wrappers skip the push under own,
and the lifetime is the C++ one: the pass objects outlive `App.run()`. This design lets own prove it
instead: what such an array keeps lives to the end of the program, so it is made immortal where it
is kept, as an immortal global is (spec 25).

## 2. Keepers

A **keeper** is a `ts.Global` that:

- is not exported or imported (no `export`, `import`, `dllexport`, `dllimport`), and is not reached
through a vtable;
- is an array whose element type is a class, a bound function, a function value (`hybrid_func`), a
string or an array;
- is given its value only by its region, which yields a new array (`[]`, `ts.Constant` of an array,
`ts.CreateArray`, `ts.NewArray`);
- is used only by `ts.AddressOf`s whose users are a `ts.ArrayPush` (the array operand), and
`ts.Load`s whose users read it: `ts.LengthOf`, and `ts.ElementRef`s that are only loaded.

Nothing ever takes an element out of a keeper or overwrites one (no `pop`, `shift`, `splice`,
`length =`, element store, nor the array given to anything), and nothing releases a global. So
what it holds is never released: it lives to the end of the program.

`findKeepers` (OwnershipSignaturePass) marks each `ts.AddressOf` of a keeper
`__own_keeper_global`, and each `ts.Load` of one of its elements `__own_keeper_read`.

## 3. Immortal at the push

A value pushed into a keeper is made immortal there: its block's header becomes
`HEAP_BLOCK_IMMORTAL`, so every release skips it, its fields included (a release of an immortal
block runs no destroy body). Writing the header only leaks; it frees nothing. So it is sound wherever
the block is a heap block with a header, and every block the value relies on is made immortal too.
Two blocks need more than the value's own:

- **A bound method** (`this.onRender`) holds its `this` without owning it, so the object is
marked.
- **A closure that does not escape** borrows its cells and the values it captured by value from the
frame that built it, which releases them. Its box, each cell and each value captured by value
are marked.

Only the function that builds a value knows these blocks: a callee given a `hybrid_func` does not
know whether its context is an object, a box (whose layout it does not know) or a C++ object with
no header at all. So the mark is made by the function that knows the value's origin, and a function
that pushes a parameter passes the duty to its callers:

- **The value is a parameter** (a load of the parameter's slot, through casts): the function
**immortalizes** that parameter (`__own_immortalizes`, argument indices). Nothing is marked
there; every call of it marks its argument, by these same rules.
- **The value is built here, or read out of an owning local whose initializer it is**: a bound
method (`ts.ThisSymbolRef`, `ts.ThisVirtualSymbolRef` of a class that owns its block, not
`@cpp`), a closure (`ts.CreateBoundFunction` of a capture box), an allocation (`ts.New`,
`ts.CreateArray`, `ts.NewArray`), or a string. It is marked here.
- **It is immortal already**: a literal, an immortal global's read, a keeper's element.
- **Anything else** (a field's value, a call's result, a merge): an error at the push, "-mm=own
cannot make the value kept in 'retained' immortal here".

A call passes an argument to a parameter its callee immortalizes. That argument is decided by the
same rules: a parameter of the caller propagates (a fixpoint over the calls, as `@keeps` facts
are), and anything else is marked at the call.

## 4. In the IR

- `%i = ts.MakeImmortal(%v)`: the same value, now immortal. Inserted right after `%v`'s definition
(the root, before casts); every other use of `%v` is given `%i`. With `assumed` it marks nothing:
it wraps a parameter its callers made immortal.
- `ts.MarkImmortalCell(%cell)`: marks a captured variable's cell.

To inference, `ts.MakeImmortal`'s result is immortal (`isImmortalLiteral`): its retains go, and it
may be pushed, stored, returned or given to a call that keeps it, as a string literal may. Its
operand is only borrowed, so the frame still owns what it built and releases it at the end, which
the header makes a no-op. A keeper's element read is immortal too, and is no place read. A keeper's
`ts.AddressOf` is no global read either: the array is never replaced, only appended to. A push of
an immortal value keeps nothing, so a parameter pushed through `ts.MakeImmortal` is not
`__own_params`. That is why the caller's `this` can go to `setRenderCallback`.

The lowering, under own only:

- a class or object instance, a string: the block, when not null and not already immortal (a stack
object and a literal have immortal headers, and a literal's may be read-only);
- an array: its header block, when there is one;
- a bound function: its `this`, an object or a capture box;
- `assumed`: nothing.

## 5. Across modules: `@immortalizes`

A function another module may call (open: exported, or its address taken) cannot tell callers it
does not see to mark their arguments. Like `@keeps`, an open function that immortalizes a parameter
must say so: `@immortalizes("handler")`. It is checked against the body (`checkDeclared`): a
parameter it names that the body does not immortalize, or one the body immortalizes that it does
not name, is an error. A bodyless declaration's `@immortalizes` is trusted, as `@nodrops` is: a C
function that keeps a callback for good. The decorator is carried in an importer's re-parsed
declaration and in a shared library's declarations, so every caller marks its arguments.

A call through a class family or an interface immortalizes a parameter only when every callee does.
When the callees disagree, the function that immortalizes is an error: some calls of it would not
mark.

## 6. Not here

- A keeper of optionals, unions or tuples: their payloads would need marking through the tag.
- A function value of unknown origin (a field's `hybrid_func`): its context may be a bound method's
object, which only its type tells.
- Removing elements from a keeper: that is an ordinary array, and the push is the move it is
today.

## 7. As built

- `OwnershipSignatureKeepers.cpp`: `findKeepers`, `classifyKept`, `decideKeptForGood` (runs after
`findOpen`, before `computeFacts`: an immortal value keeps nothing, so a parameter pushed through
`ts.MakeImmortal` is not `__own_params`), `makeImmortal`. A call's callees are its resolved
functions, or, for a call the pass knows nothing else of (another module's function with no
facts), the declarations of the symbols it names, whose `@immortalizes` is read.
- Inference: `isImmortalLiteral` and the retain decision accept `isKeptForGood`; a keeper's element
read is neither a place read nor a global read; `ts.MakeImmortal` and `ts.MarkImmortalCell` are
borrows; `followClosure` takes `ts.MakeImmortal` as a use and follows it no further, so a closure
kept for good borrows its cells from the frame (which then may still use the captured variables),
and whatever is done with the immortal value afterwards bounds nothing.
- Stack promotion (`StackEscapeFacts`): `ts.MakeImmortal` and `ts.MarkImmortalCell` are an escape,
reason "kept for good", so nothing kept is ever a stack object.
- The decorator is carried like `@keeps`: `processOwnParamMarkers`, the global a declaration's calls
go through, a shared library's printed declarations (a 32-bit mask in a class's method info, which
fits where a 64-bit one would grow the vtable's `SmallVector` past its inline limit).

Existing programs change only where an array was a keeper: `own_err_closure_escape_twice`, `_loop`
and `_some_paths` pushed closures into a global that is now one, so they were accepted (soundly);
they now empty it once (`handlers.length = 0`), which keeps their errors. `own_closure_escape` and
the stack-promotion test `pass_to_keeper` push into keepers and pass, the latter with the reason
"kept for good" under own.

## 8. Tests

- `own_immortal_keepers` (own, gc, rc, none; compile and JIT): a registry pushing a parameter into
a keeper and using it after; a constructor registering `this.onTick` from a function that returns;
a closure over a local the frame still uses; a forwarding function, and an exported one that says
`@immortalizes`; objects pushed directly, fresh and from a local; a keeper's element stored into a
field; churn between, so a freed block would be handed out again.
- `test-own-keepers-objects` (own-keepers-objects.cmake): the keeper in a library object, an
importer registering a bound method and a closure from functions that return; `2 102 2`.
- `own_err_keeper_*`: a value of unknown origin pushed (`unknown_value`), an exported function
without `@immortalizes` (`exported`), an `@immortalizes` the body disagrees with (`declared`), a
function that keeps for good passed on as a value (`called_through_value`), and an array that is
also popped, which is no keeper, so the move error stays (`popped`).
6 changes: 6 additions & 0 deletions tslang/include/TypeScript/Defines.h
Original file line number Diff line number Diff line change
Expand Up @@ -331,6 +331,12 @@
// that returns such a record has to say it. A unit attribute on the FuncOp.
#define RECORD_DECORATOR "record"
#define OWN_DECLARED_RECORD_ATTR_NAME "ts.own_declared_record"
// `@immortalizes` names the parameters the function keeps for good, in an append-only global (a
// keeper, docs/superpowers/specs/2026-10-25-own-immortal-keepers-design.md): its callers make each
// argument immortal. Checked against a body; trusted on a declaration, a C function that keeps a
// callback for good. A FuncOp attribute of argument indices.
#define IMMORTALIZES_DECORATOR "immortalizes"
#define OWN_DECLARED_IMMORTALIZES_ATTR_NAME "ts.own_declared_immortalizes"
// the names of the arguments of a function that says any, for -mm=own's errors about it
#define OWN_DECLARED_PARAM_NAMES_ATTR_NAME "ts.own_declared_param_names"

Expand Down
30 changes: 30 additions & 0 deletions tslang/include/TypeScript/LowerToLLVM/OwnershipRoutineLogic.h
Original file line number Diff line number Diff line change
Expand Up @@ -479,6 +479,36 @@ class OwnershipRoutineLogic
});
}

// The same for a block that may be immortal already (ts.MakeImmortal, own's keepers): a stack
// object's header is, and a literal's, which may be read-only, so the header is written only
// when it is mortal.
void emitMarkImmortalIfMortal(mlir::Value payloadPtr)
{
emitIfNonNull(payloadPtr, [&]() {
TypeConverterHelper tch(typeConverter);
TypeHelper th(rewriter);
LLVMCodeHelperBase ch(op, rewriter, typeConverter, compileOptions);
auto loc = op->getLoc();

auto isMortal = emitIsMortal(payloadPtr);
auto *currentBlock = rewriter.getInsertionBlock();
auto *continuationBlock = rewriter.splitBlock(currentBlock, rewriter.getInsertionPoint());
auto *markBlock = rewriter.createBlock(continuationBlock);

rewriter.setInsertionPointToEnd(markBlock);
auto llvmIndexType = tch.convertType(th.getIndexType());
auto blockPtr = ch.getBlockPtrFromPayloadPtr(loc, payloadPtr, llvmIndexType);
rewriter.create<LLVM::StoreOp>(
loc, rewriter.create<LLVM::ConstantOp>(loc, llvmIndexType, rewriter.getIntegerAttr(llvmIndexType, HEAP_BLOCK_IMMORTAL)),
blockPtr);
rewriter.create<LLVM::BrOp>(loc, ValueRange{}, continuationBlock);

rewriter.setInsertionPointToEnd(currentBlock);
rewriter.create<LLVM::CondBrOp>(loc, isMortal, markBlock, continuationBlock);
rewriter.setInsertionPointToStart(continuationBlock);
});
}

private:
// Field types of a record-shaped type, empty for anything else.
llvm::SmallVector<mlir::Type> getFieldTypes(mlir::Type type)
Expand Down
5 changes: 3 additions & 2 deletions tslang/include/TypeScript/MLIRLogic/MLIRDeclarationPrinter.h
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@ namespace typescript
void printVariableDeclaration(StringRef, NamespaceInfo::TypePtr, mlir::Type, bool, StringRef = StringRef());
void print(StringRef, NamespaceInfo::TypePtr, mlir_ts::FunctionType, StringRef = StringRef(),
ArrayRef<int32_t> ownKeeps = {}, ArrayRef<int32_t> ownBorrows = {}, ArrayRef<int32_t> ownLends = {},
bool ownRecord = false);
bool ownRecord = false, ArrayRef<int32_t> ownImmortalizes = {});
void print(ClassInfo::TypePtr);
void print(InterfaceInfo::TypePtr);
void printGenericClass(NamespaceInfo::TypePtr, StringRef);
Expand All @@ -41,7 +41,8 @@ namespace typescript
bool filterName(StringRef);
bool filterField(mlir::Attribute);
void printParams(ArrayRef<mlir::Type>, mlir::Type);
void printOwnMarkers(ArrayRef<int32_t>, ArrayRef<int32_t>, ArrayRef<int32_t>, bool, bool, unsigned);
void printOwnMarkers(ArrayRef<int32_t>, ArrayRef<int32_t>, ArrayRef<int32_t>, bool, bool, unsigned,
ArrayRef<int32_t> = {});
void printFunction(StringRef, ArrayRef<mlir::Type>, mlir::Type);
void printMethod(bool, StringRef, ArrayRef<mlir::Type>, mlir::Type, mlir::Type);
void printAccessor(bool, StringRef, StringRef, mlir_ts::AccessLevel, ArrayRef<mlir::Type>, mlir::Type, mlir::Type, StringRef);
Expand Down
4 changes: 4 additions & 0 deletions tslang/include/TypeScript/MLIRLogic/MLIRGenStore.h
Original file line number Diff line number Diff line change
Expand Up @@ -172,6 +172,10 @@ struct MethodInfo
uint64_t ownLendsMask = 0;
// `@record` (OWN_DECLARED_RECORD_ATTR_NAME): what `@lends` names, the result is a record of
bool ownRecord = false;
// `@immortalizes` (OWN_DECLARED_IMMORTALIZES_ATTR_NAME), as a mask like `@lends`'s, of 32 bits:
// it fits beside `ownRecord`, where a 64-bit one would grow the vtable's SmallVector past its
// inline-size limit
uint32_t ownImmortalizesMask = 0;
};

struct GenericMethodInfo
Expand Down
27 changes: 27 additions & 0 deletions tslang/include/TypeScript/TypeScriptOps.td
Original file line number Diff line number Diff line change
Expand Up @@ -625,6 +625,33 @@ def TypeScript_ReleaseContentsOp : TypeScript_Op<"ReleaseContents"> {
let arguments = (ins AnyType:$instance, UnitAttr:$reset);
}

def TypeScript_MakeImmortalOp : TypeScript_Op<"MakeImmortal", [AllTypesMatch<["value", "result"]>]> {
let summary = "the same value, its block marked immortal";
let description = [{
-mm=own (docs/superpowers/specs/2026-10-25-own-immortal-keepers-design.md): a value an
append-only global keeps for good. Its block - an object's, a string's, an array's header, a
bound function's `this` - is marked HEAP_BLOCK_IMMORTAL, unless it is null or immortal already,
so every release skips it. The result is that value, immortal: owned by no one. With `assumed`
nothing is marked: the value is a parameter its callers made immortal.

Only OwnershipSignaturePass makes it; under the other models it is never there.
}];

let arguments = (ins AnyType:$value, UnitAttr:$assumed);
let results = (outs AnyType:$result);
}

def TypeScript_MarkImmortalCellOp : TypeScript_Op<"MarkImmortalCell"> {
let summary = "mark a captured variable's cell immortal";
let description = [{
The cell of a variable a closure captures, when that closure is kept for good and borrows the
cell from the frame that declared it (-mm=own, MakeImmortal): the frame's release of the cell
then skips it.
}];

let arguments = (ins TypeScript_Ref:$slot);
}

def TypeScript_SizeOfOp : TypeScript_Op<"SizeOf", [Pure]> {
let summary = "size of type";
let description = [{
Expand Down
1 change: 1 addition & 0 deletions tslang/lib/TypeScript/CMakeLists.txt
Original file line number Diff line number Diff line change
Expand Up @@ -49,6 +49,7 @@ add_mlir_dialect_library(MLIRTypeScript
OwnershipSignatureGenerators.cpp
OwnershipSignatureGlobals.cpp
OwnershipSignatureInterfaces.cpp
OwnershipSignatureKeepers.cpp
OwnershipSignatureRecords.cpp
OwnershipSignatureResolve.cpp
OwnedReturnConsumptionPass.cpp
Expand Down
19 changes: 14 additions & 5 deletions tslang/lib/TypeScript/DeclarationPrinter.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -232,7 +232,7 @@ namespace typescript
// the receiver of a method, so the importer reads the same argument indices back. `@record` after
// `@lends`: the importer's only way to know the result is a record it owns (own spec 32).
void MLIRDeclarationPrinter::printOwnMarkers(ArrayRef<int32_t> keeps, ArrayRef<int32_t> borrows, ArrayRef<int32_t> lends,
bool record, bool hasThis, unsigned indent)
bool record, bool hasThis, unsigned indent, ArrayRef<int32_t> immortalizes)
{
auto printMarker = [&](StringRef name, ArrayRef<int32_t> indices) {
if (indices.empty())
Expand Down Expand Up @@ -262,6 +262,7 @@ namespace typescript
};

printMarker(KEEPS_DECORATOR, keeps);
printMarker(IMMORTALIZES_DECORATOR, immortalizes);
printMarker(BORROWS_DECORATOR, borrows);
printMarker(LENDS_DECORATOR, lends);
if (record && !lends.empty())
Expand Down Expand Up @@ -448,7 +449,7 @@ namespace typescript

void MLIRDeclarationPrinter::print(StringRef name, NamespaceInfo::TypePtr elementNamespace, mlir_ts::FunctionType funcType, StringRef dllName,
ArrayRef<int32_t> ownKeeps, ArrayRef<int32_t> ownBorrows, ArrayRef<int32_t> ownLends,
bool ownRecord)
bool ownRecord, ArrayRef<int32_t> ownImmortalizes)
{
printNamespaceBegin(elementNamespace);

Expand All @@ -460,7 +461,7 @@ namespace typescript
newline();
}

printOwnMarkers(ownKeeps, ownBorrows, ownLends, ownRecord, /*hasThis=*/false, 0);
printOwnMarkers(ownKeeps, ownBorrows, ownLends, ownRecord, /*hasThis=*/false, 0, ownImmortalizes);

printFunction(
name,
Expand Down Expand Up @@ -731,17 +732,25 @@ namespace typescript
newline();
}

// every index `@lends` names: MLIRGen refuses one past 63, which the mask cannot hold
// every index `@lends` and `@immortalizes` name: MLIRGen refuses one past 63, which the
// masks cannot hold
SmallVector<int32_t> lends;
SmallVector<int32_t> immortalizes;
for (int32_t index = 0; index < 64; ++index)
{
if (method.ownLendsMask & (uint64_t(1) << index))
{
lends.push_back(index);
}

if (index < 32 && (method.ownImmortalizesMask & (uint32_t(1) << index)))
{
immortalizes.push_back(index);
}
}

printOwnMarkers(method.ownKeeps, method.ownBorrows, lends, method.ownRecord, /*hasThis=*/!method.isStatic, 4);
printOwnMarkers(method.ownKeeps, method.ownBorrows, lends, method.ownRecord, /*hasThis=*/!method.isStatic, 4,
immortalizes);

// the slot of a @cpp class's virtual method: without it the importer takes the method
// for a non-virtual one
Expand Down
Loading