Perf: split rare object state to reach the 256-byte GC slab

[chrisbbreuer]

Parent: #62
Related: #97, #44, #86, #87, #119

Evidence

An exact-row profile on 5100a966 sampled warmed eight-context object_churn for 20 seconds. The seven-sample screen measured exact checksum 8309369344; zig-js was 335.523 ms median versus JSC 184.239 ms. One-context zig-js remained faster (109.035 vs 115.561 ms), so the deficit was scaling under concurrent private-heap memory pressure rather than a shared runtime lock.

The profiler attributed the active worker stacks primarily to young sweeping/collection and 512-byte ordinary-object allocation/reuse. Object was 448 bytes and the zig-gc header brought each managed allocation to 496 bytes, forcing the 512-byte slab. The benchmark literal used three inline values while most of the cell was default-initialized exotic/callable/typed-array/Temporal state.

The completed refactor moved rare state behind cold sidecars, reduced ordinary objects to the 256-byte GC slab, and enlarged object chunks without exceeding the fixed reuse bitmap. The accepted order-balanced run at zig-js 0a74f7d1, published by 6c71f46f, preserved all 1,540 raw samples and beat JSC in every direct, warmed-eight, and cold-eight workload. Object-churn medians were 80.380 vs 117.343 ms direct, 170.179 vs 187.303 ms at eight warmed contexts, and 177.256 vs 189.788 ms across cold eight-context lifecycles.

Scope completed

• Split rare callable, primitive, proxy, buffer/view, weak/finalization, module, iterator-helper, Temporal, and other exotic state behind cold typed storage while keeping ordinary shape/inline-slot/prototype and dense-array access fast.
• Kept the ordinary managed Object plus zig-gc header within the 256-byte slab class and added a compile-time/layout regression test.
• Routed cold storage through context/GC ownership and finalizer accounting; traced moved managed edges and preserved no-GIL synchronization.
• Preserved prototypes, property/accessor semantics, callbacks/constructors, arrays, proxies, weak collections, typed arrays, Temporal, OOM rollback, GC tracing, and exact benchmark checksums.
• Landed the work as reviewable, compiling slices before the batched full normal/TSan/publication gates.

Acceptance

• Managed ordinary objects use the 256-byte GC slab with a guarded layout test.
• Beat JSC in direct and 1/2/4/8 independent object_churn rows on an order-balanced exact-parent A/B.
• Materially improve shared object_churn without regressing the other nine benchmark workloads.
• Pass focused object/exotic/GC/OOM/no-GIL tests, then one batched full normal and TSan gate.
• Publish clean report/TSV evidence and refresh README/docs with the latest scores and linked commits.

Accepted report: https://github.com/zig-utils/zig-js/blob/main/docs/.data/benchmark-comparison-2026-07-15.md

Raw samples: https://github.com/zig-utils/zig-js/blob/main/docs/.data/benchmark-comparison-2026-07-15.tsv

Final full normal/TSan verification: https://github.com/zig-utils/zig-js/actions/runs/29466730465

[chrisbbreuer]

Layout audit follow-up: Object is exactly 448 bytes (align(16)), while zig-gc adds a 48-byte aligned header, yielding a 496-byte allocation in the 512-byte slab. A viable 256-byte target exists without shrinking the four inline property values: retaining allocator/backing ownership, the cold pointer, three locks, shape + slots + 4 inline values, prototype, accessor/private-brand/key-order metadata, dense elements, attrs, extensibility/indexed-array state, array length, restriction owner, and holes totals about 195 bytes and aligns to 208; 208 + 48 = 256 exactly. The moved state should therefore be the primitive/callable/error/proxy/buffer-view/weak/module/iterator/Temporal/private-data families. The existing cold payloads are mutually exclusive enough to use typed/category unions rather than one oversized sidecar, avoiding a cold-lifecycle regression for function objects.

[chrisbbreuer]

First seven bisectable layout slices are now on main:

• e88232b moves the mutually exclusive Symbol/BigInt payload cold;
• 1f09a03 moves error instance/constructor names cold;
• c2cb1d0 moves Date, module-namespace, and WeakRef scalar state cold;
• b2df6ad moves C-ABI host callback state cold;
• aad4556 moves boxed primitive-wrapper payloads cold;
• 6c2790d moves generator and iterator-helper links cold;
• 338d209 moves bound-function links cold;
• 6268a1a unions those disjoint rare categories so an exotic object pays only for its active payload.

Measured layout progress: Object is 304 bytes, down from 448 (32.1% smaller). The zig-gc header therefore yields 352 bytes today; the 208-byte payload / 256-byte slab target still requires another 96 bytes. The cold sidecar briefly grew as fields moved, then the tagged union reduced ObjectColdState from 312 to 208 bytes.

Focused gates are green with zero leaks across Symbol/BigInt, Error, Date, WeakRef/GC, module namespace, C-API callbacks, primitive wrappers, generators/concurrent GC, iterator helpers, and bind behavior. No benchmark claim yet: 304+48 still occupies the 512-byte slab, so publication remains gated on reaching 208 bytes and completing the batched semantic/TSan gates.