Module bytecode_dispatch_table_pack 

Pack an opcode → handler dispatch table into one u32 per entry for fast GPU-side bytecode interpretation. Foundational primitive for warp-specialized interpreter loops where every thread executes the same opcode in the same warp. bytecode_dispatch_table_pack - pack an opcode-handler dispatch table into a constant-buffer for fast GPU-side bytecode interpretation.

Op id: vyre-primitives::parsing::bytecode_dispatch_table_pack. Soundness: Exact over the opcode → handler-offset mapping. The canonical bytecode-on-GPU interpreter loop reads dispatch_table[opcode] to find which handler program to invoke, then executes it. Centralising the table layout and validation here lets every interpreter dialect (Lua-shape, JVM-shape, WASM-shape) share one well-typed packing format.

Why it matters

Bytecode interpreter loops on GPU lose on naive implementations because the dispatch-table fetch + indirect-branch pattern is the canonical “GPU loses to CPU” workload (CPU has branch predictor + huge L1; GPU has neither). The fix: pack the dispatch table into a constant-buffer that resides in shared memory + use uniform-control-flow patterns where every thread executes the same handler in the same warp (warp-specialized interpretation).

This module ships the packing part. Interpreter loops read the packed table through this stable wire layout.

Wire format

Each table entry is one u32 packed as:

  bits 0..23   -  handler_offset (max 2^24 = 16M handlers  -  plenty)
  bits 24..27  -  handler_arity  (number of operand bytes, 0..15)
  bits 28..31  -  flags          (bit 28 = side_effecting, bit 29 = control_flow)

The packed format means dispatch is one u32 load + one mask-and-shift per opcode. No pointer chasing.

Structs

OpcodeHandlerEntry

One opcode → handler entry, the host-side representation that pack_dispatch_table turns into a packed u32.

Enums

PackError

Pack errors. Returned when the host-side entry can’t be encoded into the 1-u32 wire format.

Functions

pack_dispatch_table

Pack a dispatch table of OpcodeHandlerEntry into one u32 per entry, suitable for upload as a constant buffer. The output index matches the input index; output[opcode_byte] is the packed entry.

pack_dispatch_table_into

Pack a dispatch table into caller-owned storage.

pack_entry

Pack one dispatch-table entry without validation.

packed_dispatch_table_len

Number of packed u32 words required for entries.

unpack_entry

Unpack one u32 entry back into the host-side representation. Used by interpreter Programs that read dispatch_table[opcode] and need to know which handler to invoke + how many operand bytes to consume.