Module closure_raw

Expand description

Raw TypedClosureHeader allocation + accessor helpers.

This module is the VM-side counterpart to the JIT’s crate::v2::closure_layout layout definitions. It provides a stable C-ABI-compatible way to allocate, retain, release, read, and write TypedClosureHeader blocks without going through HeapValue::Closure.

§Closure-spec §13 H3.B.1

The H3.B migration replaces HeapValue::Closure { function_id, upvalues } (an Arc<HeapValue> carrying a Vec<Upvalue>) with a raw *const TypedClosureHeader block matching the JIT’s Phase H1 memory layout. This module is the shared infrastructure both the VM’s op_make_closure_heap and the JIT’s emit_heap_closure converge on.

H3.B.1 introduces this module and its helpers; H3.B.2 wires them into the 20+ HeapValue::Closure consumer sites.

§Memory layout (same as `closure_layout::TypedClosureHeader`)

  Offset  Size  Field
  ------  ----  -----
    0       8   HeapHeader (refcount @ 0, kind @ 4, flags @ 6, _pad @ 7)
    8       4   function_id (u32)
   12       4   type_id (u32, ClosureTypeId.0)
   16       N   captures[] (C-laid-out per ClosureLayout)

Every capture slot is 8-byte wide in practice (the layout rounds up to 8-byte alignment), but the typed width at the slot is dictated by the FieldKind: F64/I64/U64 use 8 bytes; I32/U32 use 4; I16/U16 use 2; I8/U8/Bool use 1; Ptr uses 8 and participates in the heap_capture_mask retain/release cycle.

Structs§

ClosureCell: Kind-aware closure capture cell store (§2.7.8 / Q10).
OwnedClosureBlock: Owning handle for a raw TypedClosureHeader block paired with its layout.

Functions§

alloc_owned_mutable_bool: Allocate a fresh OwnedMutable cell holding a bool payload.
alloc_owned_mutable_f64: Allocate a fresh OwnedMutable cell holding an f64 payload.
alloc_owned_mutable_i8: Allocate a fresh OwnedMutable cell holding an i8 payload.
alloc_owned_mutable_i16: Allocate a fresh OwnedMutable cell holding an i16 payload.
alloc_owned_mutable_i32: Allocate a fresh OwnedMutable cell holding an i32 payload.
alloc_owned_mutable_i64: Allocate a fresh OwnedMutable cell holding an i64 payload.
alloc_owned_mutable_ptr: Allocate a fresh OwnedMutable cell holding a Ptr payload.
alloc_owned_mutable_u8: Allocate a fresh OwnedMutable cell holding a u8 payload.
alloc_owned_mutable_u16: Allocate a fresh OwnedMutable cell holding a u16 payload.
alloc_owned_mutable_u32: Allocate a fresh OwnedMutable cell holding a u32 payload.
alloc_owned_mutable_u64: Allocate a fresh OwnedMutable cell holding a u64 payload.
alloc_typed_closure^⚠: Allocate a zero-initialised TypedClosureHeader block matching the given layout. The HeapHeader is written with refcount = 1, kind = HEAP_KIND_V2_CLOSURE, flags = 0. The function_id and type_id fields are written from the arguments. The captures area is zero-filled — callers are responsible for writing each capture at its typed offset via write_capture_raw_u64 before handing the pointer out.
dealloc_typed_closure_no_drop^⚠: Deallocate a TypedClosureHeader block without walking the heap-capture mask. The caller is responsible for having already consumed or released each heap-typed capture’s refcount share.
drop_owned_mutable_capture^⚠: Drop the OwnedMutable capture at index i of a closure block.
drop_shared_capture^⚠: Release a Shared capture: read the cell pointer at the slot, decode the interior FieldKind, drop any heap refcount share carried by a Ptr payload, and finally Arc::from_raw + drop the cell to release its strong-count share.
read_capture_as_value_bits^⚠: Read a capture slot as a typed u64 bit pattern suitable for ValueWord::from_raw_bits.
read_owned_mutable_bool^⚠: Read the bool payload of an OwnedMutable cell.
read_owned_mutable_f64^⚠: Read the f64 payload of an OwnedMutable cell.
read_owned_mutable_i8^⚠: Read the i8 payload of an OwnedMutable cell.
read_owned_mutable_i16^⚠: Read the i16 payload of an OwnedMutable cell.
read_owned_mutable_i32^⚠: Read the i32 payload of an OwnedMutable cell.
read_owned_mutable_i64^⚠: Read the i64 payload of an OwnedMutable cell.
read_owned_mutable_ptr^⚠: Read the raw u64 (Ptr-shaped) payload of an OwnedMutable cell.
read_owned_mutable_u8^⚠: Read the u8 payload of an OwnedMutable cell.
read_owned_mutable_u16^⚠: Read the u16 payload of an OwnedMutable cell.
read_owned_mutable_u32^⚠: Read the u32 payload of an OwnedMutable cell.
read_owned_mutable_u64^⚠: Read the u64 payload of an OwnedMutable cell.
read_shared_bool^⚠: Read a bool from a SharedCell’s payload — false iff every byte of the 8-byte payload is zero, true otherwise. (write_shared_bool stores 0 or 1, so this is just the standard “any non-zero byte” test.)
read_shared_f64^⚠: Read a f64 from a SharedCell’s payload while holding its lock.
read_shared_i8^⚠: Read an i8 from a SharedCell’s payload, truncating the upper bytes.
read_shared_i16^⚠: Read an i16 from a SharedCell’s payload, truncating the upper bytes.
read_shared_i32^⚠: Read an i32 from a SharedCell’s payload, truncating the upper bytes.
read_shared_i64^⚠: Read an i64 from a SharedCell’s payload.
read_shared_ptr^⚠: Read the raw 8-byte pointer payload of a SharedCell whose interior FieldKind is Ptr. The returned u64 is a ValueWord bit pattern (NaN-boxed Arc/Box pointer) that can be clone_from_bits’d to obtain a retained share.
read_shared_u8^⚠: Read a u8 from a SharedCell’s payload, truncating the upper bytes.
read_shared_u16^⚠: Read a u16 from a SharedCell’s payload, truncating the upper bytes.
read_shared_u32^⚠: Read a u32 from a SharedCell’s payload, truncating the upper bytes.
read_shared_u64^⚠: Read a u64 from a SharedCell’s payload.
release_typed_closure^⚠: Release one refcount share of a TypedClosureHeader block. If the refcount reaches zero, this function walks all three per-capture masks to release each mutable-cell and heap-typed capture, then frees the block itself. The three masks are:
retain_typed_closure^⚠: Retain (bump refcount) on a TypedClosureHeader block.
typed_closure_function_id^⚠: Read the function_id from a TypedClosureHeader block.
typed_closure_kind^⚠: Read the HeapHeader kind tag for a TypedClosureHeader block.
typed_closure_refcount^⚠: Get the current refcount of a TypedClosureHeader block (for debugging / tests).
typed_closure_type_id^⚠: Read the type_id from a TypedClosureHeader block.
write_capture_raw_u64^⚠: Write a raw 8-byte capture slot at the given index.
write_capture_typed^⚠: Write a capture slot from a ValueWord bit pattern, selecting the correct native width based on the capture’s FieldKind.
write_owned_mutable_bool^⚠: Write the bool payload of an OwnedMutable cell.
write_owned_mutable_f64^⚠: Write the f64 payload of an OwnedMutable cell.
write_owned_mutable_i8^⚠: Write the i8 payload of an OwnedMutable cell.
write_owned_mutable_i16^⚠: Write the i16 payload of an OwnedMutable cell.
write_owned_mutable_i32^⚠: Write the i32 payload of an OwnedMutable cell.
write_owned_mutable_i64^⚠: Write the i64 payload of an OwnedMutable cell.
write_owned_mutable_ptr^⚠: Write a new u64 (Ptr-shaped) payload into an OwnedMutable cell.
write_owned_mutable_u8^⚠: Write the u8 payload of an OwnedMutable cell.
write_owned_mutable_u16^⚠: Write the u16 payload of an OwnedMutable cell.
write_owned_mutable_u32^⚠: Write the u32 payload of an OwnedMutable cell.
write_owned_mutable_u64^⚠: Write the u64 payload of an OwnedMutable cell.
write_shared_bool^⚠: Write a bool to a SharedCell’s payload as a 0/1 byte, zero-extended to 8 bytes.
write_shared_f64^⚠: Write a f64 to a SharedCell’s payload while holding its lock.
write_shared_i8^⚠: Write an i8 to a SharedCell’s payload, sign-extending to 8 bytes.
write_shared_i16^⚠: Write an i16 to a SharedCell’s payload, sign-extending to 8 bytes.
write_shared_i32^⚠: Write an i32 to a SharedCell’s payload, sign-extending to 8 bytes.
write_shared_i64^⚠: Write an i64 to a SharedCell’s payload.
write_shared_ptr^⚠: Write a raw 8-byte pointer payload to a SharedCell whose interior FieldKind is Ptr. The caller is responsible for refcount semantics — this writer does NOT release the previous payload nor retain the new one. For Ptr payloads the standard pattern is to read the old bits, release them, then write the new (already-retained) bits.
write_shared_u8^⚠: Write a u8 to a SharedCell’s payload, zero-extending to 8 bytes.
write_shared_u16^⚠: Write a u16 to a SharedCell’s payload, zero-extending to 8 bytes.
write_shared_u32^⚠: Write a u32 to a SharedCell’s payload, zero-extending to 8 bytes.
write_shared_u64^⚠: Write a u64 to a SharedCell’s payload.