Module heap_value

Expand description

Heap-allocated value types reachable through HeapValue.

After the strict-typing Phase-2 bulldozer (option C — heterogeneous collections / dynamic single-value wrappers excised), HeapValue carries only typed payloads:

typed primitives (string, decimal, bigint, char, future-id),
typed handles (datatable, content, instant, io-handle, native scalars),
typed object slots (TypedObject with Box<[ValueSlot]>),
the typed-closure-raw block (ClosureRaw),
typed temporal data (TemporalData),
typed table views (TableViewData).

V3-S5 ckpt-1..ckpt-4 (2026-05-15): the inline TypedArrayData enum + the outer HeapValue::TypedArray(Arc<TypedArrayData>) arm + TypedBuffer<T> / AlignedTypedBuffer wrapper layer were retired wholesale per W12-typed-array-data-deletion-audit §3.5 + §B + ADR-006 §2.7.24 Q25.A SUPERSEDED. The canonical replacement is the v2-raw TypedArray<T> flat struct at crate::v2::typed_array::TypedArray<T> (per docs/runtime-v2-spec.md). The HeapKind::TypedArray = 8 ordinal is vacated; do not reuse.

Variants that previously held ValueWord (the deleted dynamic word) — Some/Ok/Err/Range/TraitObject/FunctionRef, HashMap/Set/Deque/PriorityQueue, Iterator/Generator/ ProjectedRef, Concurrency (Mutex/Atomic/Lazy/Channel), Rare, Enum, Array (heterogeneous-element), HostClosure — were removed together with their *Data structs. The corresponding HeapKind ordinals are preserved (annotated “(removed)” in heap_variants.rs) and await monomorphized typed replacements per docs/runtime-v2-spec.md.

Structs§

AtomicData: Atomic<i64> storage — wraps a std::sync::atomic::AtomicI64 for the atomic operations exposed by the Atomic.load / store / fetch_add / fetch_sub / compare_exchange method surface.
ChannelData: MPSC-style synchronous channel storage.
DequeData: Double-ended queue storage. Heterogeneous element kinds are stored as Arc<HeapValue> payloads (mirror of HashMapData::values per ADR-005 §1 single-discriminator) — the deque is element-kind-agnostic at landing, in line with the W13-hashmap precedent.
HashMapData: HashMap storage — keys buffer (string-typed v2-raw *mut TypedArray<*const StringObj>)
HashSetData: HashSet storage — one keyspace, no values. Mirror of HashMapData with the values buffer dropped.
IoHandleData: Data for IoHandle variant (Arc-wrapped at the HeapValue level to keep HeapValue small and to enable cluster #2 marshal FromSlot for Arc<IoHandleData>).
LazyData: Lazy<T> storage — wraps an initializer closure (KindedSlot of kind Ptr(HeapKind::Closure)) and a cached value slot. get() runs the initializer the first time and caches the result; subsequent calls return the cached value.
MatrixData: Flat, SIMD-aligned matrix storage (row-major order).
MatrixSliceData: Row/column projection into a parent MatrixData ({ parent, offset, len }).
MutexData: Mutex<T> storage — a single typed payload protected by a Rust Mutex so concurrent Arc<MutexData> shares observe each other’s mutations (the canonical “shared cell with exclusion” shape, mirror of ChannelData’s Mutex<ChannelInner> interior-mutability shape).
NativeLayoutField: Field layout metadata for type C structs.
NativeTypeLayout: Runtime layout descriptor for one native type.
NativeViewData: Pointer-backed zero-copy view into native memory.
OptionData: Option carrier. is_some discriminates Some vs None; payload carries the inner value for Some. For None the payload is a KindedSlot::none() placeholder (Bool-kind, zero bits) so KindedSlot::Drop is a no-op.
PriorityQueueData: PriorityQueue storage — i64-priority min-heap.
RangeData: Range value carrier — an inclusive-or-exclusive integer interval with step. Built by MakeRange from the surface syntax start..end (exclusive) and start..=end (inclusive); produced as a typed Arc<RangeData> slot labeled NativeKind::Ptr(HeapKind::Range).
ResultData: Result<T, E> carrier. is_ok discriminates Ok vs Err; payload carries the inner value (T for Ok, E for Err). Both arms share the same payload slot — the variant tag is the discriminator, not the slot’s physical layout.
TaskGroupData: Task-group payload. Extracted from the inline HeapValue::TaskGroup { kind, task_ids } struct variant per ADR-006 §2.3 so HeapValue::TaskGroup becomes a single-tuple Arc<T> payload like every other ADR-006 §2.3 heap arm.
TraitObjectPtr: Owning newtype around *const TraitObjectStorage carrying one v2-raw refcount share on the pointed-to allocation’s HeapHeader.
TraitObjectStorage: dyn Trait storage — the typed-Arc replacement for the bulldozer-deleted HeapValue::TraitObject { value: Box<u64>, vtable: Arc<VTable> }. Pairs the boxed data half (always a TypedObject per §Q25.C.4 universal-dyn ruling — scalars/strings that implement traits are boxed into TypedObject first; the auto-boxing rule lifts Rust’s object-safety restrictions at the cost of one heap indirection per dyn coerce) with the vtable half (shared Arc<VTable> so per-impl vtables are constructed once and IC-cached per §Q25.C.6).
TypedObjectPtr: Owning newtype around *const TypedObjectStorage carrying one v2-raw refcount share on the pointed-to allocation’s HeapHeader.
TypedObjectStorage: Schema-keyed object storage. Extracted from the inline HeapValue::TypedObject { schema_id, slots, heap_mask } struct variant per ADR-006 §2.3, so that:

Enums§

HashMapKindedRef: HashMapKindedRef — kinded carrier for Arc<HashMapData<V>> per audit §C.4 option (a.2). Bundles per-V monomorphized payload types as enum variants; the variant tag IS the NativeKind discriminator at the carrier layer.
HeapKind: Discriminator for HeapValue variants, usable without full pattern match.
HeapValue: Compact heap-allocated value. Strict-typed variants only — every payload is either a typed primitive (i64, char, f64 via TypedArray), a typed structure (TypedObject slots, typed FFI pointers, typed temporal data), or a typed handle.
IoHandleKind: I/O handle kind discriminant.
IoResource: The underlying OS resource wrapped by an IoHandle.
NativeScalar: Native ABI-width scalars used by C ABI / extern C fn boundaries.
TableViewData: Table view data — consolidates TypedTable, RowView, ColumnRef, and IndexedTable.
TemporalData: Temporal data — consolidates Time, Duration, TimeSpan, Timeframe, TimeReference, DateTimeExpr, and DataDateTimeRef.

Traits§

HashMapValueElem: Per-V dispatcher trait for HashMapData<V>::Drop — releases the value buffer (*mut TypedArray<V>) at refcount-0 of the enclosing Arc<HashMapData<V>>.