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
8 changes: 5 additions & 3 deletions docs/memory-models.md
Original file line number Diff line number Diff line change
Expand Up @@ -89,9 +89,11 @@ holds exactly as much as `-mm=none` — that is, reference counting reclaims non
done with the structure, or store a key/index instead of a pointer back to the owner.
3. If neither fits, `-mm=rc` is not the right mode for that program.

A `WeakRef<T>` that lets you declare a back-reference as non-owning is designed but not
implemented; see `tslang/docs/reference-counting-evaluation.md` §9.8. When it lands it will be
the fourth option here, and it does not change anything above.
`WeakRef<T>` declares a back-reference that does not own what it refers to. It works under
`-mm=gc`, `-mm=own` and `-mm=none`; under `-mm=rc` it is a compile error, because rc's header word
is already the strong count and a weak count needs a second one (see
`tslang/docs/reference-counting-evaluation.md` §9.8). So for a program with parent links, `-mm=own`
with `WeakRef` is the fourth option here.

## The standard library

Expand Down
11 changes: 10 additions & 1 deletion docs/own-memory-model.md
Original file line number Diff line number Diff line change
Expand Up @@ -905,7 +905,16 @@ a reference gives it back on every path out of a function.
parameter (`while (n) { k++; n = n.next; }`) when every value it gives it is read out of the one it
holds: the parameter then borrows the caller's list. A parameter given anything else (`n = new
Node(0)` on some path) is kept, and the caller gives it up.
- `Shared<T>` cycles are never freed.
- A back-reference is a `WeakRef<T>` (`parent: WeakRef<Node> | null`, `c.parent = new WeakRef(this)`,
`this.parent?.deref()`). It does not own its target: when the target's owner frees it, `deref()`
gives `undefined` from then on. The object `deref()` gives is a borrow: it cannot be stored,
returned or captured, and anything that may free an object of its type (a release of a holder of
that type, a call that may drop) ends it, so read what you need right away. A `@final` target class
keeps more of those borrows. The target is a class object. A module that makes WeakRefs may not
share with another thread (`Thread.spawn`, a worker, `Shared.share`) anything that may hold their
target, since the count is not atomic; in practice no `Thread.spawn` of a closure in such a module.
Each object carries the count in the header word it already has: no object grows.
- `Shared<T>` cycles are never freed; break them with a `WeakRef` where one side only refers back.
- There are no lifetime annotations: a borrow that the compiler cannot follow is an error, even
when the program would be correct. The fix is usually a move, a fresh value or `Shared<T>`.

Expand Down
10 changes: 6 additions & 4 deletions docs/own-readiness.md
Original file line number Diff line number Diff line change
Expand Up @@ -104,8 +104,8 @@ Probed one by one under the JIT:
| Tree insert by recursion on a parameter: `t.l = ins(t.l, v)` | Compiles and runs, when the function is in the same module and never throws |
| Cutting while walking: `const nx = n.next; n.next = null; n = nx` | Rejected: the cut frees what `nx` names (accepted by mistake from 2026-11-16 until spec 83) |
| Tree insert and sum as methods recursing on `this` | Compiles and runs |
| Parent link: `k.parent = this` | Rejected; the answer is `Shared<T>`, whose cycles leak |
| `new WeakRef(a)` | Rejected: built on the collector |
| Parent link: `k.parent = new WeakRef(this)` | Compiles and runs (spec 84); `deref()` gives `undefined` once the parent is freed |
| `new WeakRef(a)` | Compiles and runs under own, gc and none; rc refuses it |
| `new Map<string, Node>()`, `filter` over class instances | Rejected by design; `Shared<Node>` |
| Swap through a local: `let t = a[i]; a[i] = a[j]; a[j] = t` | Rejected by design; `[a[i], a[j]] = [a[j], a[i]]` |
| `x ??= new B()` on a parameter | Rejected ("merged from several branches") |
Expand Down Expand Up @@ -148,8 +148,10 @@ assertions-enabled CI leg, and a soak run. The first holds today; the other two

## What is left, in order

1. **A non-owning back-reference.** `WeakRef<T>` under own, or a declared borrowing field. Without
it a tree with parent links either does not compile or leaks.
1. **Back-references beyond WeakRef.** `WeakRef<T>` works (spec 84): the target's header word holds
the weak count, and a freed target is a tombstone until its last WeakRef goes. Left: a module that
makes WeakRefs cannot spawn threads with closures, and a zero-cost borrowing field for shapes the
compiler can prove.
2. **The rest of linked structures.** A list, a node built from the old head, a walk that assigns a
parameter and the recursive tree insert work (spec 83). A call that may throw, or one into another
module, still cannot take a field this way, and the popped node cannot be used after the assignment that frees it.
Expand Down
Loading
Loading