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

@@ -11,14 +11,14 @@ main :: () -> s32 {
// Recover BEFORE first dispatch.
recovered : *GPA = xx a;
print("recovered == gpa? {}\n", recovered == gpa);
print("recovered == gpa? {}\n", recovered == @gpa);
p := a.alloc(64);
print("alloc count after first alloc: {}\n", gpa.alloc_count);
// Recover AFTER dispatch — still works.
recovered2 : *GPA = xx a;
print("recovered2 == gpa? {}\n", recovered2 == gpa);
print("recovered2 == gpa? {}\n", recovered2 == @gpa);
a.dealloc(p);
print("alloc count after dealloc: {}\n", gpa.alloc_count);

View File

@@ -12,8 +12,7 @@
main :: () -> s32 {
gpa := GPA.init();
tracker_ptr := TrackingAllocator.init(xx gpa);
tracker := tracker_ptr.*; // dereference into a stack-local VALUE
tracker := TrackingAllocator.init(xx gpa); // value, stack-local
// xx tracker — operand is an identifier (lvalue), so the protocol
// borrows tracker's storage. No heap copy. Mutations propagate.

View File

@@ -1691,12 +1691,13 @@ END;
// First chunk fits 80 usable bytes
a1 := a.alloc(40);
a2 := a.alloc(40);
// Counts: Arena struct itself + first chunk = 2 (Arena.init
// allocates its own state through the parent allocator).
print("arena chunks: {}\n", gpa3.alloc_count); // arena chunks: 2
// Counts: just the first chunk = 1. Arena.init returns the
// state by value; the local IS the Arena struct, no parent
// allocation for the state itself.
print("arena chunks: {}\n", gpa3.alloc_count); // arena chunks: 1
// Overflow → new chunk
a3 := a.alloc(16);
print("arena overflow: {}\n", gpa3.alloc_count); // arena overflow: 3
print("arena overflow: {}\n", gpa3.alloc_count); // arena overflow: 2
// Verify memory works across chunks
p1 : [*]u8 = xx a1;
p3 : [*]u8 = xx a3;
@@ -1704,11 +1705,12 @@ END;
p3[0] = 99;
print("arena a1: {}\n", p1[0]); // arena a1: 42
print("arena a3: {}\n", p3[0]); // arena a3: 99
// Reset retains newest chunk
// Reset retains the first chunk
arena.reset();
print("arena reset idx: {}\n", arena.end_index); // arena reset idx: 0
print("arena reset gpa: {}\n", gpa3.alloc_count); // arena reset gpa: 2
// Deinit frees all chunks + the Arena state itself
print("arena reset gpa: {}\n", gpa3.alloc_count); // arena reset gpa: 1
// Deinit frees all chunks (caller's local is the state — no
// dealloc of the struct itself).
arena.deinit();
print("arena deinit: {}\n", gpa3.alloc_count); // arena deinit: 0
}