mem: allocator init returns state by value (drops state-struct heap alloc)

Building on the Option 3 lvalue-borrow rule, the long-lived allocators
in `library/modules/allocators.sx` (GPA, Arena, TrackingAllocator) now
return their state by value instead of via a heap-allocated `*T`. The
caller binds the result to a local; the local IS the allocator state.
`xx local` borrows that storage under Option 3, so the `Allocator`
protocol value's `ctx` points at the local — no heap allocation for
the state struct, no `free` of the state needed.

```sx
gpa     := GPA.init();                          // GPA (value)
arena   := Arena.init(xx gpa, 4096);            // Arena (value)
tracker := TrackingAllocator.init(xx gpa);      // TrackingAllocator (value)

push Context.{ allocator = xx tracker, data = null } { ... }
```

Why by-value:
- One fewer `libc_malloc` per allocator instance.
- No state-struct leak. The local is reclaimed at scope exit; `deinit`
  only handles downstream resources (chunks, etc.) — not its own struct.
- Owning structs can embed allocators as value fields directly.

Callsite changes:

- `library/modules/ui/pipeline.sx`: `arena_a: Arena;` / `arena_b:
  Arena;` (was `*Arena;`). The `build_arena: *Arena` local takes
  `@self.arena_a` / `@self.arena_b`.
- `examples/126-xx-recover-then-dispatch.sx`: `recovered == @gpa`
  instead of `recovered == gpa` (gpa is a value now).
- `examples/135-xx-lvalue-borrows.sx`: drop the `tracker_ptr.*`
  deref — `init` already returns the value.
- `examples/50-smoke.sx`: Arena alloc counts dropped by 1 (no
  state-struct allocation). Comments + snapshot updated.

`Arena.deinit` drops the trailing `parent.dealloc(xx a)` — the
caller's local owns the storage.

FFI IR snapshots regenerated to reflect the new signatures:
`@GPA.init` returns `i64` (was `ptr`); `@Arena.init` and
`@TrackingAllocator.init` use sret returns (was `ptr`).

CLAUDE.md "Allocator construction" rule rewritten around the
by-value convention. The forbidden caller-provides-storage and
redundant-pointer-rename patterns are still forbidden but for the
right reasons now (verbose, fragile) rather than as a workaround
for the old `init() -> *T` shape.

157/157 example tests pass; chess clean on macOS, iOS sim, and
Android via `tools/verify-step.sh`.
This commit is contained in:
agra
2026-05-25 15:33:28 +03:00
parent b710a0a42a
commit da1063f1bb
19 changed files with 191 additions and 141 deletions

View File

@@ -5,6 +5,35 @@ Tracking checkpoint for the mem.sx Zig-aligned implementation
## Last completed step
- **Allocator `init` returns the state by value.** Building on the
Option 3 lvalue-borrow rule, `GPA.init`, `Arena.init`, and
`TrackingAllocator.init` now return `T` (not `*T`). The caller binds
the local; the local IS the storage. `xx local` borrows under Option
3 so the `Allocator` protocol value's `ctx` points at the local.
Saves one `libc_malloc` per allocator instance; closes the
state-struct leak surface (the local goes away with its scope, no
explicit `deinit` needed for the struct itself).
Migration:
- `library/modules/allocators.sx`: `init` signatures changed
(`-> T` instead of `-> *T`); `Arena.deinit` drops the trailing
`parent.dealloc(xx a)` — caller owns the storage.
- `library/modules/ui/pipeline.sx`: `arena_a: Arena;` /
`arena_b: Arena;` (was `*Arena;`); `@self.arena_a` /
`@self.arena_b` at the use site that needs `*Arena` for the
`build_arena` local.
- `examples/126-xx-recover-then-dispatch.sx` updated: comparisons
against `*GPA` use `@gpa` now.
- `examples/135-xx-lvalue-borrows.sx` simplified: no
`tracker_ptr.*` deref needed.
- `examples/50-smoke.sx` Arena counts dropped by 1 each (no
state-struct alloc); comments + snapshots updated to match.
- CLAUDE.md "Allocator construction" rule rewritten around the
by-value convention.
157/157 example tests + chess clean on macOS / iOS sim / Android
(`tools/verify-step.sh` ran green).
- **`xx <lvalue>` borrows the operand's storage** (Option 3 in the
protocol-erasure design discussion). Today's behavior — `xx
<struct-typed local>` heap-copies the value — was a silent footgun:
@@ -242,7 +271,16 @@ Allocator value naturally.
## Log
- **2026-05-25 (latest)** — `xx <lvalue>` semantics changed to borrow.
- **2026-05-25 (latest)** — Allocator `init` returns the state by
value. GPA / Arena / TrackingAllocator all changed; `Arena.deinit`
no longer self-deallocs. `UIPipeline.arena_a/_b` embedded as values;
`@self.arena_a` at the *Arena use site. `examples/50-smoke.sx`
Arena alloc counts dropped by 1 (no state struct alloc); FFI IR
snapshots regenerated to reflect new signatures (`-> ptr`
`-> i64`/`-> void sret(...)`). CLAUDE.md "Allocator construction"
rewritten around the by-value convention. 157/157 + chess green
on all three platforms via `tools/verify-step.sh`.
- **2026-05-25 (penultimate)** — `xx <lvalue>` semantics changed to borrow.
Single change at `lower.zig:10334` (`buildProtocolErasure`) gated by
new `isLvalueExpr` helper at `lower.zig:10322`. specs.md §3
ownership table extended (three modes: rvalue / lvalue / pointer).