Skip to main content

Module nanbox

sui_bytecode

Module nanbox 

Source
Expand description

NaN-boxed value representation for the VM stack. NaN-boxed value representation for the VM stack.

Packs all value types into exactly 8 bytes using the quiet NaN payload bits of IEEE 754 doubles. This eliminates heap allocation for scalars and makes the value stack cache-friendly.

§Layout

IEEE 754 double:

[sign:1] [exponent:11] [mantissa:52]

A quiet NaN has exponent = all 1s and mantissa MSB = 1. We use the remaining bits for a type tag + payload:

Float:  any valid f64 that is not a signaling NaN with our tag pattern
Tagged: 0x7FF8_xxxx_xxxx_xxxx  (quiet NaN space)
  Tag bits [48..51] encode the type:
    0x0 = Null
    0x1 = Bool(false)
    0x2 = Bool(true)
    0x3 = Int (payload: i48 in bits [0..47])
    0x4 = Pointer to heap object (payload: 48-bit pointer)

§Performance Impact

  • Stack entries: 8 bytes instead of 40-80 bytes (enum VMValue)
  • No heap allocation for null, bool, int, float
  • Cache-friendly: entire stack fits in L1/L2 for typical expressions
  • Copy is a single 64-bit register move

Structs§

NanBox
A NaN-boxed value: 8 bytes encoding any VM value type.

Enums§

HeapObject
Heap-allocated object referenced by a NanBox pointer tag.