Carry lifetime regions across await and reuse freed region chunks

[cramforce]

Summary

LifetimeRegion regions now work for async request handling, and regions that are freed over and over cost less.

Regions cross await. Before this change, an async function called inside region.run(fn) allocated in the region only until its first await. Everything it created after that went to the default region, which is never freed. Those objects usually pointed back at the objects created before the await, so the request's region could never be freed either. With one region per request, an async server's memory grew without bound, and every release() also triggered a full cycle-collector pass over the heap. Now:

• Every async fiber records the region that was current when it was spawned (ScrFiber.region). The event loop makes that region current while it resumes the fiber and restores the previous region afterwards. The runtime calls nothing for this until the program creates its first region: a process-wide hook table (scr_region_fiber_hooks) installed by scr_region_create.
• A region is not freed while any fiber that carries it exists (ScrRegion.fibers), and no release check runs on it in that time. So a region released while its async work is pending keeps receiving that work's objects. It is freed once the work ends and nothing outside the region refers into it. Escaping references still keep a region, as before. Exceptional exits are unchanged: run leaves the region in a finally, and a rejected async body drops its hold when its fiber is destroyed.
• Generators behave as before: their bodies run in the region of whoever resumes them. Timers, queueMicrotask callbacks, event listeners and async-generator bodies run in the loop's (default) region. The docs say so.

Freed chunks are reused. A freed region's 2 MiB chunks used to be unmapped immediately. A program that frees a region per request or per batch therefore mapped, faulted in and unmapped new memory every time. In the request benchmark that came to about 30 page faults per request and about 19% of samples in the kernel. Each thread now keeps freed chunks in a cache:

• The cache holds at most 8 MiB of resident memory per thread.
• A cached chunk keeps only its first 256 KiB resident, cleared with memset. Past that it gets fresh pages via mmap(MAP_FIXED), so a small region that reuses a large region's chunk does not inherit its memory.
• Chunks that huge pages may back are not cached.
• Sanitized and RC-audit builds never reuse a chunk, so the use-after-free trap still works.

A cache bug caught and fixed during development. The first version kept cached chunks fully resident. It doubled steady-state RSS in generations-edit (76 → 159 MB), because small per-file regions kept reusing chunks that the checker region had fully touched. The 256 KiB warm limit fixes this.

Measurements

Linux Vercel Sandbox, 8 vCPU. Each benchmark is compiled with base (origin/main 8620fa5) and with this branch, and the two run interleaved; values are medians of 9 runs (ab-regions.mjs). RSS figures come from /proc/self/status.

benchmark	metric	main	this PR
requests-async (4000 requests, 16 concurrent, 100 items, new)	total	2130 ms	668 ms (−69%)
	RSS at end / peak	995 / 995 MB	8.9 / 8.9 MB
requests-async, 1 at a time	total	2048 ms	599 ms (−71%)
	RSS at end	995 MB	3.4 MB
requests-async, 64 concurrent, 400 items	total	7513 ms	4260 ms (−43%)
	RSS at end / peak	4060 / 4060 MB	61.6 / 79.8 MB
emit-small (20000 per-file regions)	emit	694 ms	504 ms (−27%)
emit-files (200 per-file regions, large live heap)	emit	70.4 ms	61.1 ms (−13%)
generations-all	median generation	50.2 ms	45.3 ms (−10%)
	steady RSS	39.8 MB	47.6 MB (the chunk cache)
generations-edit	median generation / steady RSS	25.0 ms / 76.4 MB	25.1 ms / 80.0 MB
compiler-watch (large regions, huge pages)	median rebuild / RSS at end	316 ms / 171.8 MB	317 ms / 174.6 MB

Context for requests-async on this branch (medians of 5 interleaved runs, same VM):

• on: the same classes as ProgramLifetime without regions, so nothing is ever freed. 551 ms, 979 MB.
• off: plain reference-counted classes. 1288 ms, 26.6 MB.
• region: this PR. 680 ms, 8.9 MB.
• Node.js: 819 ms, 206 MB.

Per-request regions now run close to leak-everything speed. Against plain reference counting they are 1.9× faster and use a third of the memory.

How the requests-async gain splits between the two changes (separate, non-interleaved runs on a second sandbox): crossing await without chunk reuse took it from about 2.37 s to about 1.0 s. Chunk reuse then took it to about 0.71 s, and minor page faults fell from 121k to 1.7k.

scripts/bench-runtime.mjs --layouts=4 --runs=16 (base vs candidate) is neutral. The geomean ratio is 0.995. region-builds changes by −0.0% and async-pipeline by −0.8%. Every workload is within ±3% except http-api, at −4.4%. Async binaries grow by 48 bytes.

Tests

• New corpus program 5023-lifetime-region-await (byte-identical to Node.js). It covers:
  • eight concurrent request regions that interleave at awaits, with children spawned after a resume;
  • a nested region inside an async continuation;
  • a sync generator driven from a continuation;
  • a rejection after an await;
  • a release while the work is pending;
  • background work that outlives its request;
  • an escaping result held in a cache.
• tests/harness/lifetime-regions.test.ts checks, from SCRIPTC_REGION_STATS, that all 15 regions of 5023 are freed. Regions whose work was pending are freed without a kept attempt; the nested region and the escaping one are kept first and freed later. 5013 now frees 7 of 7 regions (was 2 of 7).
• scr_region.test.c adds a check that a freed region's chunk serves the next region, cleared.
• Docs: the /docs/experimental LifetimeRegion section gains an "Async work" subsection with an example whose output was run, the API and cost text is updated, and the @scriptc/experimental README and index.d.ts say the same.

Validation, all in a Linux Vercel Sandbox:

• pnpm lint and pnpm format:check are clean.
• pnpm test:ts7 --baselines-only passes. Re-recording added exactly the 5023 baseline and changed no existing entry.
• Differential tests: the lifetime-region programs pass 15/15 in the plain lane, and SCRIPTC_SAN=1 passes 62/62 across the differential and region-harness tests.
• The async|await|promise|generator differential subset passes 194/195. The one failure, 5570-fs-cp-async, also fails on the untouched base.
• Unit and harness suites pass: scr_region.test.ts 3/3 (size-class, sanitized, TSan workers), lifetime-regions.test.ts 9/9, scr_async.test.ts, and regions.test.ts.
• The self-hosting --emit=ir build reports no diagnostics, and self-hosting-native-driver.test.ts passes 1/1.
• The docs check (NEXT_DIST_DIR=.next-check pnpm check) passes 25/25.

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
scriptc	Ready	Preview, v0	Oct 18, 2026 1:24pm UTC