Stop a scalar created inside a scope costing value-pool slots

A scalar now lives in the variable record (`akbasic_Variable::inlinevalue`)
rather than drawing from the value pool, so a `GOSUB` local, a `FOR` counter and
a `DEF` parameter cost nothing at all.

The pool is a bump allocator with no free, and its comment justified that with
"nothing in BASIC destroys a variable". Scope exit does: it marks the variable
slot unused, `new_variable()` memsets the slot it hands back -- clearing
`values` -- and `variable_init()` therefore took *fresh* slots for a variable
whose old ones were still counted. Every scope that created a local leaked, with
no diagnostic until the pool ran dry on whichever line happened to be unlucky.

Six thousand `GOSUB`s creating one local used to die on the 4091st at `LOC# = 1`
with "Array of 1 elements does not fit in the 0 remaining value slots". They now
run. A `DEF` called eight thousand times used to die between the four and five
thousandth -- the leaking slot was the call scope's parameter, which is a scalar
-- and both forms now run. A game creating one name per tick was dead in half a
minute; the Breakout in examples/ was, after twenty-five seconds.

**A `@` name is the one exclusion, and it is the whole of it.** A structure or a
pointer to one keeps pool storage, because a pointer into a record outlives the
scope that DIMmed it -- docs/16-structures.md says nothing is reclaimed and
`prev_environment()` relies on it. The name suffix is the right test rather than
`structtype`, which the DIM path sets *after* calling `variable_init()`. A local
array therefore still leaks, deliberately, and is now the narrow rule the
tutorial teaches.

`SWAP` needed the other half: it copies whole variable records, so the `values`
pointer that came over named the other variable's inline slot -- which by then
held this variable's own old value -- and SWAP silently did nothing. Caught by
tests/language/housekeeping/verbs.bas, which is the golden corpus earning its
keep.

tests/value_pool.c is the new coverage. It asserts the mechanism as well as the
consequence: a later change that moved arrays inline too would pass every
behavioural case and quietly break the pointer guarantee. The sharpest case
takes the pool's whole 4096 slots in four arrays after two hundred scope
entries, so one leaked slot has nowhere to go.

Chapter 17 Step 3 taught "declare every name at the top" and no longer needs to.
It now teaches what is still true -- a name first seen inside a subroutine dies
at RETURN, so a routine cannot answer its caller through one -- and its
demonstration is the array case, which still fails.

TODO.md section 6 item 30 and section 9 item 1, both struck.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
2026-08-01 23:47:49 -04:00
parent caebc1a174
commit 05f241aca1
10 changed files with 419 additions and 97 deletions

25
TODO.md
View File

@@ -1863,8 +1863,22 @@ the reference's semantics reproduced faithfully; the third is the port's own.
A complete Breakout, sprites and text grid and keyboard, running for minutes at a time. Nothing
in either corpus runs for minutes, which is why the first of these had never been seen.
30. **A variable created inside a scope costs pool slots that never come back, so a long-running
program has a hard budget of 4096 name creations.** `akbasic_ValuePool` is a bump allocator
30. ~~**A variable created inside a scope costs pool slots that never come back, so a
long-running program has a hard budget of 4096 name creations.**~~ **Done** — a scalar now
lives in the variable rather than in the pool (`akbasic_Variable::inlinevalue`,
`src/variable.c`), so a `GOSUB` local, a `FOR` counter and a `DEF` parameter all cost
nothing at all. Twenty thousand scoped creations where four thousand used to be the whole
run. `tests/value_pool.c` is the coverage, and it asserts the mechanism as well as the
consequence — a later change that moved arrays inline too would pass every behavioural
case and break the pointer guarantee. **An array created in a scope still leaks**, which is
deliberate and is the same statement `akbasic_ValuePool` has always made: a pointer into a
record outlives the scope that DIMmed it. The record below is what was found and why.
**Also fixed with it:** `SWAP` exchanges whole variable records, so the `values` pointer
that came over named the other variable's inline slot and SWAP silently did nothing. Caught
by `tests/language/housekeeping/verbs.bas`, which is the golden corpus earning its keep.
The original report: `akbasic_ValuePool` is a bump allocator
on purpose (`include/akbasic/value.h:30`), and the reason given is that "nothing in BASIC
destroys a variable". **Scope exit destroys variables.**
`akbasic_runtime_prev_environment()` (`src/runtime.c:121`) marks a popped environment's
@@ -2440,8 +2454,11 @@ using the thing rather than by testing it.** The corpus reaches none of them.
Ordered by blast radius. Each has a minimal reproduction that fits on a screen; every one was
reduced against `build/basic`, the stdio build, unless it says otherwise.
1. **Every call to a user-defined function leaks value-pool slots, so a program may call one
about four thousand times and then die.**
1. ~~**Every call to a user-defined function leaks value-pool slots, so a program may call one
about four thousand times and then die.**~~ **Done** with §6 item 30, and by the same
change: the leaking slot was the call scope's parameter, which is a scalar and no longer
comes from the pool. Both `DEF` forms run eight thousand calls in
`tests/user_functions.c`. The original report:
```basic
DEF ADDIT(N#)