perf(zig): table three-byte glyph decoding

Author: pmarreck

.dirtree-state

@@ -15,7 +15,7 @@ annotate=[
 	rust/src/main.rs = Minimal Rust CLI (encode default, -d decode; stdin->stdout) for cross-impl verification
 	src/container_json.h = Shared pure transport-resistant flat-JSON helpers for the .pbf.json container (C FFI + standalone C)
 	src/zig/ffi.zig = C ABI (FFI) export surface: all 12 pb_* C functions; root of libprintable_binary.a; keeps C symbols OUT of the importable printable_binary module so static (musl) consumers don't collide
-	src/zig/printable_binary.zig = Pure Zig codec core; default encode uses four-byte padded internal glyph slots while returning compact UTF-8.
+	src/zig/printable_binary.zig = Pure Zig codec core; default encode uses four-byte padded slots and decode uses compact direct UTF-8 lookup tables.
 	test/module_consumer.zig = Test fixture: minimal downstream importer of the printable_binary Zig module (mirrors how difz/blip consume it) for the FFI-symbol-leak test
 	test/test_container = Container (.pbf.json) CLI round-trip + self-verify test, parameterized by IMPLEMENTATION_TO_TEST (issue #1)
 	test/test_container_cross = Cross-impl container differential: impl-A container decodes via impl-B (MFIC, issue #1)

PLAN.md

@@ -33,10 +33,12 @@ maintained_by: agent
       capacity; exposing an owned-capacity buffer is an API design, not a
       transparent micro-optimization. Curiosity poke: callers must never
       observe stale bytes after a shorter subsequent encode/decode.
-- [ ] Prototype and measure a cache-resident O(1) decoder for the 28 three-byte
-      glyphs before replacing the current ~100-byte binary-search table.
-      Curiosity poke: a 24 KB direct table may cost more cache than five
-      predictable comparisons.
+- [x] Prototype and measure a cache-resident O(1) decoder for the 28 three-byte
+      glyphs. The compact three-lead-byte table is 24 KiB and improves mixed
+      decode from ~310 to 330–341 MB/s (~8%), so it replaces the ~100-byte
+      binary-search table. Curiosity poke: cross-architecture measurements
+      still decide whether the cache trade holds beyond this x86_64 host.
+      (2026-07-23 12:22 AM EDT)
 - [ ] Prototype a portable SIMD/hybrid classifier only if the measured
       scalar loop remains dominant. Use `simdutf` as a technique reference,
       not a dependency: its UTF-8 transcoder cannot directly express this

README.md

@@ -77,7 +77,7 @@ The Rust crate also has an in-process codec microbenchmark (`nix develop -c carg
 Key optimizations in the Zig core:
 - **Pre-allocated buffers**: encode/decode output sized upfront (no growth checks in the hot loop).
 - **Flat character map**: a comptime-built contiguous byte buffer (~1.5 KB) replacing 256 scattered fat pointers — fits in L1 cache.
-- **O(1) decode lookup**: direct tables for 1-, 2-, and 3-byte UTF-8 sequences instead of an O(log 256) binary search.
+- **O(1) decode lookup**: direct tables for 1- and 2-byte UTF-8 sequences plus a compact 24 KiB table for the map's three 3-byte lead-byte planes, replacing the former binary search.
 - **No inner decode loop**: a single UTF-8 length check + direct lookup per character.
 
 The C and Lua decoders were tuned in a measured pass: C uses direct 1-/2-byte lookup tables (**1.9×** decode). Lua got two passes — resolving each glyph by its UTF-8 leading-byte length (instead of brute-forcing all four), then writing decoded bytes straight into a LuaJIT `string.buffer` via its FFI `reserve`/`commit` API (no per-byte `string.char`). Together that took Lua **decode from ~8 to ~91 MB/s** — now faster than its own encode (which uses `string.buffer:put`, ~1.2×). Every optimization is benchmarked before and after (hyperfine), and a continuous memory-leak suite (`test/leak_test`) guards the FFI/C paths against regressions.

src/zig/printable_binary.zig

@@ -139,65 +139,57 @@ const decode_2byte: [32][64]?u8 = blk: {
     break :blk table;
 };
 
-/// Sorted lookup table for 3-byte UTF-8 sequences (binary search on ~30 entries)
-const Decode3Entry = struct {
-    codepoint: u16,
-    value: u8,
-};
-
-const decode_3byte_count: usize = blk: {
+/// Number of distinct UTF-8 lead bytes used by the map's 3-byte glyphs.
+/// The current map uses E1, E2, and EA, so its direct table occupies 24 KiB.
+const decode_3byte_lead_count: usize = blk: {
+    var seen = [_]bool{false} ** 256;
     var count: usize = 0;
-    for (0..256) |i| {
-        if (character_map[i].len == 3) count += 1;
+    for (character_map) |glyph| {
+        if (glyph.len == 3 and !seen[glyph[0]]) {
+            seen[glyph[0]] = true;
+            count += 1;
+        }
     }
     break :blk count;
 };
 
-const decode_3byte_table: [decode_3byte_count]Decode3Entry = blk: {
-    @setEvalBranchQuota(100000);
-    var entries: [decode_3byte_count]Decode3Entry = undefined;
-    var idx: usize = 0;
-    for (0..256) |i| {
-        if (character_map[i].len == 3) {
-            const b = character_map[i];
-            const cp: u16 = (@as(u16, b[0] & 0x0F) << 12) |
-                (@as(u16, b[1] & 0x3F) << 6) |
-                @as(u16, b[2] & 0x3F);
-            entries[idx] = .{ .codepoint = cp, .value = @intCast(i) };
-            idx += 1;
+/// Maps a 3-byte UTF-8 lead byte to its compact table index, if present.
+const decode_3byte_lead_index: [256]?u8 = blk: {
+    var indices = [_]?u8{null} ** 256;
+    var next: u8 = 0;
+    for (character_map) |glyph| {
+        if (glyph.len == 3 and indices[glyph[0]] == null) {
+            indices[glyph[0]] = next;
+            next += 1;
+        }
+    }
+    break :blk indices;
+};
+
+/// Direct O(1) lookup for 3-byte glyphs, compacted by actual lead bytes.
+/// 0x100 is an out-of-range sentinel, avoiding a collision with source byte FF.
+const decode_3byte: [decode_3byte_lead_count][64][64]u16 = blk: {
+    @setEvalBranchQuota(300000);
+    var table: [decode_3byte_lead_count][64][64]u16 = undefined;
+    for (0..decode_3byte_lead_count) |lead| {
+        for (0..64) |second| {
+            for (0..64) |third| table[lead][second][third] = 0x100;
         }
     }
-    // Insertion sort by codepoint
-    for (0..decode_3byte_count) |i| {
-        var j = i;
-        while (j > 0 and entries[j].codepoint < entries[j - 1].codepoint) {
-            const tmp = entries[j];
-            entries[j] = entries[j - 1];
-            entries[j - 1] = tmp;
-            j -= 1;
+    for (character_map, 0..) |glyph, i| {
+        if (glyph.len == 3) {
+            const lead = decode_3byte_lead_index[glyph[0]].?;
+            table[lead][glyph[1] & 0x3F][glyph[2] & 0x3F] = @intCast(i);
         }
     }
-    break :blk entries;
+    break :blk table;
 };
 
 fn decode3ByteLookup(bytes: []const u8) ?u8 {
     if (bytes.len < 3) return null;
-    const cp: u16 = (@as(u16, bytes[0] & 0x0F) << 12) |
-        (@as(u16, bytes[1] & 0x3F) << 6) |
-        @as(u16, bytes[2] & 0x3F);
-    var left: usize = 0;
-    var right: usize = decode_3byte_count;
-    while (left < right) {
-        const mid = left + (right - left) / 2;
-        if (decode_3byte_table[mid].codepoint == cp) {
-            return decode_3byte_table[mid].value;
-        } else if (decode_3byte_table[mid].codepoint < cp) {
-            left = mid + 1;
-        } else {
-            right = mid;
-        }
-    }
-    return null;
+    const lead = decode_3byte_lead_index[bytes[0]] orelse return null;
+    const value = decode_3byte[lead][bytes[1] & 0x3F][bytes[2] & 0x3F];
+    return if (value == 0x100) null else @intCast(value);
 }
 
 /// Encoding options