Module shared_nan_value 

SharedNaNValue - 64-bit NaN-boxed heterogeneous value cell.

Packs f64 | i32 | u32 | bool | nil | OffsetPtr<T> into a single u64, distinguishing types via the IEEE 754 NaN bit patterns the FPU never produces during normal computation.

Encoding

  bit 63        bit 51    bits 50-48    bits 47-0
  [sign=1][exp=0x7FF][qNaN=1][ tag(3) ][   payload (48)   ]

The boxed prefix is 0xFFF8_0000_0000_0000 (sign=1 + all-ones exponent + qNaN bit). Real float NaNs from computation usually have sign=0, so we don’t collide with them. To be safe, every from_f64(NaN) canonicalises the bit pattern to 0x7FF8_0000_0000_0000 (positive canonical qNaN) so the stored bits never look boxed when they aren’t.

Type tags (3 bits, 8 slots; 6 used, 2 reserved)

tag	meaning	payload encoding
0	nil	payload bits ignored (all 0)
1	i32	low 32 bits
2	u32	low 32 bits
3	bool	low 1 bit
4	OffsetPtr	low 32 bits = index
5	reserved	for TaggedOffsetPtr
6	reserved
7	reserved

Cross-process angle

When tag = 4 (OffsetPtr), the payload is a 32-bit INDEX, not a virtual address. Same u64 bit pattern resolves to the same pointer in every process that maps the underlying SharedRegion. That’s what makes this primitive cross-process safe where V8 / SpiderMonkey NaN boxing is single-process only.

Use cases

• Cross-process scripting / dynamic-language interpreters.
• Heterogeneous config maps: SharedHashMap<K, SharedNaNValue> where V can be int/float/ bool/ptr without per-variant storage.
• Tagged-union slots in shared state.
• Weakly-typed message payloads in event streams.

Structs

SharedNaNValue

64-bit NaN-boxed value. Stores one of: f64, i32, u32, bool, nil, or OffsetPtr<T>. Discriminated via the IEEE 754 NaN bit pattern.

Enums

NaNValueType

Discriminator for a SharedNaNValue’s payload.

Constants

BOXED_MASK

Mask covering the boxed-marker prefix (top 13 bits).

BOXED_PREFIX

The exact bit pattern that marks a boxed value.

CANONICAL_QNAN

Canonical positive qNaN. Any NaN input to from_f64 is rewritten to this so we never accidentally write a bit pattern that looks boxed.

PAYLOAD_MASK

Mask for the 48-bit payload.

TAG_BOOL

TAG_I32

TAG_MASK

Mask for the 3-bit tag once shifted into low bits.

TAG_NIL

TAG_OFFSET_PTR

TAG_SHIFT

Bit position of the type tag.

TAG_TAGGED_OFFSET_PTR

TAG_U32