Struct HeapHeader 

#[repr(C)]
pub struct HeapHeader {
    pub refcount: AtomicU32,
    pub kind: u16,
    pub flags: u8,
    pub _pad: u8,
}

Fixed-layout header for heap-allocated objects (v2 runtime spec).

This struct is designed to be readable by JIT-generated code at known offsets. The refcount lives at offset 0 for single-cycle atomic access. Kind and flags follow at offsets 4 and 6 respectively.

Fields

refcount: AtomicU32

Reference count. Starts at 1 on allocation. Clone: fetch_add(1, Relaxed). Drop: fetch_sub(1, Release).

kind: u16

Object type discriminator (matches HeapKind and HEAP_KIND_* constants).

flags: u8

Bitfield flags (FLAG_MARKED, FLAG_PINNED, FLAG_READONLY).

_pad: u8

Padding byte to reach 8-byte total size. Must be zero.

Implementations

impl HeapHeader

pub const OFFSET_REFCOUNT: usize = 0

Byte offset of the refcount field (AtomicU32, 4 bytes).

pub const OFFSET_KIND: usize = 4

Byte offset of the kind field (u16, 2 bytes).

pub const OFFSET_FLAGS: usize = 6

Byte offset of the flags field (u8, 1 byte).

pub const DATA_OFFSET: usize = DATA_OFFSET

Byte offset where payload data starts, immediately after the header.

pub fn new(kind: u16) -> Self

Create a new HeapHeader with the given kind. Refcount starts at 1, flags and padding are zeroed.

pub fn retain(&self)

Increment the reference count (clone semantics).

Uses Relaxed ordering — the caller is responsible for establishing a happens-before relationship when sharing the pointer across threads.

pub fn release(&self) -> bool

Decrement the reference count (drop semantics).

Returns true if the refcount reached zero, meaning the caller should deallocate the object. Uses Release ordering on the decrement and an Acquire fence when the count reaches zero, matching the Arc drop protocol.

pub fn refcount(&self) -> u32

Get the current reference count (for debugging / testing only).

pub fn heap_kind(&self) -> Option<HeapKind>

Get the HeapKind from this header.

pub fn has_flag(&self, flag: u8) -> bool

Check if a flag is set.

pub fn set_flag(&mut self, flag: u8)

Set a flag.

pub fn clear_flag(&mut self, flag: u8)

Clear a flag.

Trait Implementations

impl Debug for HeapHeader

HeapHeader contains an AtomicU32 which is not Clone/Copy. We provide a manual Debug impl since we cannot derive it on the atomic field cleanly.

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.