Move large per-thread canvas scratch out of static TLS (#117)

* Move large per-thread canvas scratch out of static TLS

- Add canvas.lazy_tls.LazyTls: per-thread scratch behind one TLS pointer, heap-allocated and default-initialized on a thread's first use
- Convert the planner/diff/cache scratch giants (advance cache, span wrap cache, frame planner arrays, image decode buffer, probe tables) to lazy per-thread state; only threads that actually plan frames pay for them
- Windows cloned the full static TLS template per thread (~6.5 MiB x every window-host/COM/accessibility/worker thread); the template now carries pointers instead

Co-authored-by: SunkenInTime <76637177+SunkenInTime@users.noreply.github.com>

* Add changelog fragment for the static-TLS working-set fix

- Working-set drop, .tls shrink, and smaller executables, told from the user's side

---------

Co-authored-by: SunkenInTime <76637177+SunkenInTime@users.noreply.github.com>

Author: ctate

changelog.d/static-tls-working-set.md

@@ -0,0 +1 @@
+fix: **Per-thread memory no longer scales with the canvas scratch**: the render planner's fixed scratch buffers lived in static thread-local storage, so on Windows every thread the process spawned (window host, COM, accessibility, workers) privately committed a full ~6.5 MB copy — most of a small app's working set. The scratch now allocates lazily on the one thread that actually plans frames: a scaffolded counter app's private working set drops ~4x, its `.tls` section shrinks from ~6.5 MB to under 200 bytes, and the executable itself is ~6.5 MB smaller. Linux and macOS binaries shed the same per-thread TLS block.

src/primitives/canvas/commands.zig

@@ -191,8 +191,14 @@ pub const DisplayList = struct {
 /// half-full bound; small or oversized lists keep the linear scans.
 const diff_id_index_slots = 4096;
 const DiffIdIndex = plan_key_index.HashSlots(diff_id_index_slots);
-threadlocal var diff_previous_id_index: DiffIdIndex = .{};
-threadlocal var diff_next_id_index: DiffIdIndex = .{};
+// Lazily heap-allocated per thread (32 KiB of probe tables): reset per
+// diff, so first-use init on the diffing thread is the only contract —
+// threads that never diff never allocate it.
+const DiffIdScratch = struct {
+    previous: DiffIdIndex = .{},
+    next: DiffIdIndex = .{},
+};
+const diff_id_scratch = @import("lazy_tls.zig").LazyTls(DiffIdScratch);
 
 /// Fill `table` with the keyed commands' id->index mapping, erroring on
 /// the duplicate ids `validateUniqueObjectIds` rejects — one pass does
@@ -229,9 +235,10 @@ fn diffDisplayLists(previous: DisplayList, next: DisplayList, output: []DiffChan
         next.commands.len >= plan_key_index.min_entries_for_index) and
         plan_key_index.fitsHashSlots(diff_id_index_slots, previous.commands.len) and
         plan_key_index.fitsHashSlots(diff_id_index_slots, next.commands.len);
-    if (use_index) {
-        try buildDiffIdIndex(previous, &diff_previous_id_index);
-        try buildDiffIdIndex(next, &diff_next_id_index);
+    const id_scratch: ?*DiffIdScratch = if (use_index) diff_id_scratch.get() else null;
+    if (id_scratch) |scratch| {
+        try buildDiffIdIndex(previous, &scratch.previous);
+        try buildDiffIdIndex(next, &scratch.next);
     } else {
         try validateUniqueObjectIds(previous);
         try validateUniqueObjectIds(next);
@@ -260,7 +267,7 @@ fn diffDisplayLists(previous: DisplayList, next: DisplayList, output: []DiffChan
 
     for (previous.commands, 0..) |previous_command, previous_index| {
         const id = previous_command.objectId() orelse continue;
-        const next_lookup = if (use_index) findCommandByIdIndexed(next, &diff_next_id_index, id) else next.findCommandById(id);
+        const next_lookup = if (id_scratch) |scratch| findCommandByIdIndexed(next, &scratch.next, id) else next.findCommandById(id);
         const next_ref = next_lookup orelse {
             try appendDiffChange(output, &len, .{
                 .kind = .removed,
@@ -284,7 +291,7 @@ fn diffDisplayLists(previous: DisplayList, next: DisplayList, output: []DiffChan
 
     for (next.commands, 0..) |next_command, next_index| {
         const id = next_command.objectId() orelse continue;
-        const previous_lookup = if (use_index) findCommandByIdIndexed(previous, &diff_previous_id_index, id) else previous.findCommandById(id);
+        const previous_lookup = if (id_scratch) |scratch| findCommandByIdIndexed(previous, &scratch.previous, id) else previous.findCommandById(id);
         if (previous_lookup == null) {
             try appendDiffChange(output, &len, .{
                 .kind = .added,

src/primitives/canvas/lazy_tls.zig

@@ -0,0 +1,73 @@
+//! Lazily heap-allocated per-thread scratch.
+//!
+//! Large `threadlocal` arrays land in the executable's static TLS
+//! template, and the OS loader materializes that whole template for
+//! EVERY thread of the process — window host, COM, accessibility, and
+//! worker threads all pay for the full multi-megabyte canvas planner
+//! scratch even though only a runtime loop thread ever touches it
+//! (measured on Windows as ~6.5 MiB of heap-backed private working set
+//! per thread). `LazyTls` keeps only one pointer in static TLS: the
+//! backing storage is heap-allocated the first time a thread actually
+//! asks for it, so threads that never plan a frame pay eight bytes
+//! instead of megabytes.
+//!
+//! Semantics match the `threadlocal var scratch: T = .{}` it replaces:
+//! each thread gets its own instance, initialized to the struct's field
+//! defaults on that thread's first access. Fields declared WITHOUT a
+//! default stay uninitialized, matching the `= undefined` statics they
+//! replace. The instance lives until process exit — one long-lived
+//! runtime loop thread per process is the designed shape, and a static
+//! TLS block was process-lifetime address space per thread too.
+//!
+//! Allocation failure panics: this is the render path's fixed scratch,
+//! sized at compile time, and a process that cannot commit it cannot
+//! render at all — the old static-TLS commit would have failed thread
+//! creation under the same pressure.
+
+const std = @import("std");
+
+pub fn LazyTls(comptime T: type) type {
+    return struct {
+        threadlocal var instance: ?*T = null;
+
+        /// This thread's instance, allocated and default-initialized on
+        /// first use. The pointer is stable for the thread's lifetime,
+        /// so hot loops may hoist it once per operation.
+        pub fn get() *T {
+            return instance orelse create();
+        }
+
+        /// This thread's instance only if something already used it —
+        /// for stats accessors that must observe without allocating.
+        pub fn peek() ?*T {
+            return instance;
+        }
+
+        fn create() *T {
+            const ptr = std.heap.page_allocator.create(T) catch
+                @panic("out of memory allocating per-thread canvas scratch");
+            inline for (@typeInfo(T).@"struct".fields) |field| {
+                if (comptime field.defaultValue()) |value| @field(ptr, field.name) = value;
+            }
+            instance = ptr;
+            return ptr;
+        }
+    };
+}
+
+test "lazy tls initializes defaults once per access pattern" {
+    const Scratch = struct {
+        counter: u64 = 7,
+        buffer: [32]u8, // no default: stays uninitialized, like `= undefined`
+    };
+    const tls = LazyTls(Scratch);
+    try std.testing.expectEqual(@as(?*Scratch, null), tls.peek());
+    const first = tls.get();
+    try std.testing.expectEqual(@as(u64, 7), first.counter);
+    first.counter += 1;
+    first.buffer[0] = 42;
+    const second = tls.get();
+    try std.testing.expectEqual(first, second);
+    try std.testing.expectEqual(@as(u64, 8), second.counter);
+    try std.testing.expectEqual(@as(?*Scratch, first), tls.peek());
+}

src/primitives/canvas/render_generic_resources.zig

@@ -231,30 +231,31 @@ pub const RenderResourceCachePlanner = struct {
             previous.len >= plan_key_index.min_entries_for_index) and
             plan_key_index.fitsHashSlots(resource_cache_index_slots, previous.len) and
             plan_key_index.fitsHashSlots(resource_cache_index_slots, resource_plan.resources.len);
-        if (use_index) {
-            resource_cache_previous_index.reset();
+        const index_scratch: ?*ResourceCacheIndexScratch = if (use_index) resource_cache_index_scratch.get() else null;
+        if (index_scratch) |scratch| {
+            scratch.previous.reset();
             for (previous, 0..) |entry, index| {
                 var p = ResourceCacheIndex.probe(renderResourceKeyHash(entry.key));
-                while (resource_cache_previous_index.next(&p)) |_| {}
-                resource_cache_previous_index.insert(p, @intCast(index));
+                while (scratch.previous.next(&p)) |_| {}
+                scratch.previous.insert(p, @intCast(index));
             }
-            resource_cache_entry_index.reset();
+            scratch.entry.reset();
         }
 
         for (resource_plan.resources, 0..) |resource, resource_index| {
             const key = renderResourceKey(resource);
             const key_hash = if (use_index) renderResourceKeyHash(key) else 0;
-            if (use_index) {
+            if (index_scratch) |scratch| {
                 var p = ResourceCacheIndex.probe(key_hash);
                 var duplicate = false;
-                while (resource_cache_entry_index.next(&p)) |candidate| {
+                while (scratch.entry.next(&p)) |candidate| {
                     if (renderResourceKeysEqual(self.entries[candidate].key, key)) {
                         duplicate = true;
                         break;
                     }
                 }
                 if (duplicate) continue;
-                const previous_index = findRenderResourceCacheEntryIndexed(previous, key, key_hash);
+                const previous_index = findRenderResourceCacheEntryIndexed(&scratch.previous, previous, key, key_hash);
                 try self.appendAction(.{
                     .kind = if (previous_index == null) .upload else .retain,
                     .key = key,
@@ -265,7 +266,7 @@ pub const RenderResourceCachePlanner = struct {
                     .key = key,
                     .last_used_frame = frame_index,
                 });
-                resource_cache_entry_index.insert(p, @intCast(self.entry_len - 1));
+                scratch.entry.insert(p, @intCast(self.entry_len - 1));
                 continue;
             }
             if (findRenderResourceCacheEntry(self.entries[0..self.entry_len], key) != null) continue;
@@ -284,10 +285,10 @@ pub const RenderResourceCachePlanner = struct {
         }
 
         for (previous, 0..) |entry, cache_index| {
-            if (use_index) {
+            if (index_scratch) |scratch| {
                 var p = ResourceCacheIndex.probe(renderResourceKeyHash(entry.key));
                 var kept = false;
-                while (resource_cache_entry_index.next(&p)) |candidate| {
+                while (scratch.entry.next(&p)) |candidate| {
                     if (renderResourceKeysEqual(self.entries[candidate].key, entry.key)) {
                         kept = true;
                         break;
@@ -346,14 +347,20 @@ fn findRenderResourceCacheEntry(entries: []const RenderResourceCacheEntry, key:
 /// half-full bound; bigger inputs fall back to the linear scans.
 const resource_cache_index_slots = 4096;
 const ResourceCacheIndex = plan_key_index.HashSlots(resource_cache_index_slots);
-threadlocal var resource_cache_previous_index: ResourceCacheIndex = .{};
-threadlocal var resource_cache_entry_index: ResourceCacheIndex = .{};
+// Lazily heap-allocated per thread (32 KiB of probe tables): reset per
+// build, so first-use init on the planning thread is the only contract —
+// threads that never plan resources never allocate it.
+const ResourceCacheIndexScratch = struct {
+    previous: ResourceCacheIndex = .{},
+    entry: ResourceCacheIndex = .{},
+};
+const resource_cache_index_scratch = @import("lazy_tls.zig").LazyTls(ResourceCacheIndexScratch);
 
 /// The chain's first equal candidate is the lowest-index equal entry —
 /// the exact value the linear scan returned.
-fn findRenderResourceCacheEntryIndexed(previous: []const RenderResourceCacheEntry, key: RenderResourceKey, key_hash: u64) ?usize {
+fn findRenderResourceCacheEntryIndexed(previous_index: *const ResourceCacheIndex, previous: []const RenderResourceCacheEntry, key: RenderResourceKey, key_hash: u64) ?usize {
     var p = ResourceCacheIndex.probe(key_hash);
-    while (resource_cache_previous_index.next(&p)) |candidate| {
+    while (previous_index.next(&p)) |candidate| {
         if (renderResourceKeysEqual(previous[candidate].key, key)) return candidate;
     }
     return null;

src/primitives/canvas/root.zig

@@ -469,6 +469,11 @@ pub const markdown = @import("markdown.zig");
 // the runtime's keyed diffs (see plan_key_index.zig).
 pub const plan_key_index = @import("plan_key_index.zig");
 
+// Lazily heap-allocated per-thread scratch: keeps the large planner
+// buffers out of the static TLS template every OS thread must clone
+// (see lazy_tls.zig for the working-set numbers).
+pub const lazy_tls = @import("lazy_tls.zig");
+
 // Experimental markup front-end lives in `ui_markup.zig` / `ui_markup_view.zig`
 // (runtime parse + interpret: the dev/hot-reload engine) and
 // `ui_markup_compiled.zig` (comptime parse: the release engine, no parser in

src/primitives/canvas/tests.zig

@@ -27,4 +27,5 @@ test {
     _ = @import("markdown_hostile_tests.zig");
     _ = @import("layout_audit_tests.zig");
     _ = @import("a11y_audit_tests.zig");
+    _ = @import("lazy_tls.zig");
 }