Skip to content

-mm=own: WeakRef<T>, a non-owning back-reference (spec 84) - #871

Merged
ASDAlexander77 merged 10 commits into
mainfrom
own-weakref
Nov 16, 2026
Merged

ASDAlexander77 merged 10 commits into
mainfrom
own-weakref

Conversation

@ASDAlexander77

Copy link
Copy Markdown
Owner

Readiness item 1: a non-owning back-reference. WeakRef<T> is now built into the compiler, so a tree with parent links works under -mm=own without Shared<T> cycles:

class Node {
    parent: WeakRef<Node> | null = null;
    children: Node[] = [];
    add(c: Node) { c.parent = new WeakRef(this); this.children.push(c); }
    depth(): number { const p = this.parent?.deref(); return p ? 1 + p.depth() : 0; }
}

What works where

Model WeakRef<T>
gc any object; a link the collector clears (what the default library's class did)
own a class object; deref() gives undefined once the owner frees the target
none a class object; never freed, so deref() always gives it
rc compile error: rc's header word is already the strong count

How it works under own

  • No object grows. The weak count lives in the header word every heap block already has. The low bits hold the count, bit bits-2 is the dead bit, and the top bit stays the shared mark (Defines.h).
  • Tombstones. When the owner frees a target that still has WeakRefs, own releases its fields, sets the dead bit and keeps the block. The last WeakRef to go frees it. deref() checks for null, then for immortal or not dead.
  • A WeakRef is a counted handle, like Shared<T>: own keeps rc's retains and releases of it, and lowering turns them into weak increments and decrements.
  • The object deref() gives is a borrow.
    • It cannot be stored, returned or captured.
    • It ends at anything that may free an object of its type: a release, anywhere in the function, of a slot or value whose type may hold T, and any call that may drop (unless all it overwrites are fields that cannot hold T).
    • So read what you need right away. A @final target class keeps more of these borrows.
  • Weak targets stay on the heap. Stack promotion treats new WeakRef(x) as an escape of x.
  • Threads (coarse rule). The weak count is not atomic. So a module that makes a WeakRef to a class may not share with another thread anything whose type may hold that class (Thread.spawn, a worker, Shared.share). In practice that means no Thread.spawn of a closure in such a module. The error is reported at the new WeakRef, with a note where the value is shared.

Use-after-free holes found and fixed on the way (each pinned by an error test)

  • let n = new Node(); const p = w.deref(); n = new Node(); p.v was accepted and read freed memory. A release of a local whose type may hold T now ends the borrow (own_err_weakref_local_reassigned).
  • A call that frees the target (const p = w.deref(); dropAll(h); p.v) never ended the borrow. A deref borrow has no root, and a chain with no roots counted as "caught" (own_err_weakref_after_call).
  • The final review found that a WeakRef or Shared made inside an object literal or tuple ({ w: new WeakRef(n), x: 1 }, return { s: new Shared(k) }) was released twice. The target was freed while WeakRefs remained, and the heap was corrupted. The Shared case predates this branch. Own moves the record in, but it kept rc's release of the temporary handle; that release now goes with the move (00weakref_literal).

Validation

  • Windows ctest: 7567/7567.
  • Linux own, WeakRef and shared tests (MALLOC_PERTURB_=165, tcache off): 2693/2693.
  • Differential fuzzer, seed 918000 ×500: 922 programs, 0 failures. Corpus sweep: no new refusals, no crashes.
  • AOT churn of 20M iterations: memory stays flat (a leaked tombstone per iteration would grow it by about 1 GB).
  • Default library (with the companion PR): every test passes under gc, own, none and rc. The only tests not run are those skipped by design (gc only, not own, linux only).

Known limits (deferred)

  • A target narrowed by assignment (let n: Node | null = new Node(); new WeakRef(n)) is not narrowed for the WeakRef. Under own it is refused; under gc a later cast of the WeakRef fails verification.
  • The thread rule is per module. A WeakRef in a -shared library with the spawn in the exe, or the reverse, is not caught.
  • A deref() borrow held across await is accepted.
  • A discarded call result (a.pop();) is released at the end of its function, so its object counts as alive until then.

Spec: tslang/docs/superpowers/specs/2026-11-16-own-weakref-design.md, recorded as section 84 of the own memory model spec.

Companion: the default library renames its gc-only WeakRef class to GcWeakLink, which WeakMap and WeakSet keep using. Merge this PR first.

🤖 Generated with Claude Code

ASDAlexander77 and others added 10 commits November 16, 2026 11:14
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
WeakRef<T> is resolved by the compiler before any declaration of that name
(the default library's gc-only class). new WeakRef(x) and w.deref() /
w?.deref() lower to a collector-cleared link block under gc and to the target
pointer under none. rc refuses it; own and none take class objects only; own
is not implemented yet.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…bstones

A WeakRef under own is its target's pointer, counted like a Shared handle on
the target's header word (low bits up to the dead bit). A class object freed
while WeakRefs remain releases its fields and keeps its block as a tombstone;
deref() then gives undefined, and the last WeakRef frees it. A deref result is
a borrow of an unknown place, ended by a release of anything that may hold
its type or a call that may drop; WeakRef releases end no borrow and drop
nothing.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A deref result cannot be stored, returned or captured, and a call that may
drop (unless all it overwrites are fields that cannot hold the target's type)
ends it, as a release of any holder of its type does. Six error tests and a
positive one where a @Final class's calls keep the borrow.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…l one

Stack promotion names new WeakRef(x) as an escape of x ("weak-target") rather
than leaving it to the unclassified default. new WeakRef(m) takes m narrowed
out of C | null, and own's deref() of a null target gives undefined without
reading a header.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…arget

A weak count is not atomic. The signature pass refuses a WeakRef to a class
in a module that shares (ts.MarkShared: Thread.spawn, a worker, Shared.share)
a value whose type may hold that class; reported at the WeakRef, with a note
where the value is shared.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…eadiness)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ed under rc)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…leased once

A fresh handle stored into a record literal moves in with the record (rc's retain of
the record is erased as the move), but own kept the temporary's rc release of the
handle, so the count went down twice: the target was freed while a WeakRef still
referred to it, and later releases wrote into freed memory. The temporary's release
of a handle that moves into such a record now goes with the record's retain.

Found by the final review (C1); 00weakref_literal covers literal, tuple, returned
literal and a Shared in a literal.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@ASDAlexander77
ASDAlexander77 merged commit c513028 into main Nov 16, 2026
8 checks passed
@ASDAlexander77
ASDAlexander77 deleted the own-weakref branch November 16, 2026 13:40
ASDAlexander77 added a commit that referenced this pull request Nov 16, 2026
…f a nullable target (#872)

* -mm=own: a callback declaring fewer parameters keeps a string it is lent

`m.forEach((v, k) => { names.push(k); })` over a Map or a Set failed under own with
"argument 'this value' is given to '...', which keeps it, but -mm=own cannot move it
here", at <unknown>:0. The callback declares fewer parameters than forEach's type, so
it is called through an adapter (fewerParametersThunk) that passed its block arguments
straight on: own saw an argument the adapter did not own given to a callee that keeps it.

The adapter now takes its parameters into slots, as any function does, so own reads it
as keeping what its callee keeps; when callbacks passed in its place disagree, a string
it only borrows is copied for the callee that keeps it (callCopies, spec 22), as one read
out of a field is. Without --di it carries the location it is made at, so an error found
in it points at the callback's use.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* WeakRef: new WeakRef(n) of a `C | null` declared target is a WeakRef<C>

`let n: Node | null = new Node(); new WeakRef(n)` was refused under own and none
("WeakRef needs a class object"), and under gc made a WeakRef<Node | null> that a later
store into `WeakRef<Node> | string` failed to verify. TypeScript reads n as Node there;
this compiler keeps the declared type, so T is now the target's type without null. A null
target makes a WeakRef whose deref() gives undefined.

Deferred minor M1 of the WeakRef review (#871).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs: own readiness after WeakRef and callbacks over Map/Set (spec 85)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* -mm=own: the adapter's copy of a lent string is made (dry run fails there)

The copy 3da319c meant for a string an adapter only borrows was recorded in the dry
run, which then passed, so the copies were never made: the adapter gave the Map's own
key to a callback that pushed it, and the key was freed twice (two forEach callbacks over
one Map, keeping the key and the value, crashed in a loop). The dry run now fails there,
as for a string read out of a place, and the real run finds the copy given.

own_callback_fewer_params now builds its strings at run time and frees the table's after
the callbacks: literals are immortal, so the test passed without the copy.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant