Skip to main content

Module heap_element

shape_value::v2

Module heap_element 

Source
Expand description

v2-raw HeapHeader-equipped element carrier trait.

§Purpose

HeapElement is the compile-time trait that constrains the element type T of a TypedArray<*const T> instantiation to a HeapHeader-equipped v2-raw carrier. Implementors (StringObj, DecimalObj, …) own the per-T drop semantics: release_elem decrements the refcount and fully deallocates when the count reaches zero.

§Authority

Per ADR-006 §2.7.24 Q25.A SUPERSEDED + R20 S2-prime audit deliverable (b) §4.1.B decision: option (a) — HeapElement trait dispatch.

The trait is the compile-time-monomorphized per-T release dispatcher for TypedArray<*const T>::drop_array_heap. Bodies dispatch via the Rust type system; no runtime NativeKind parameter, no is_heap() probe, no Bool-default fallback.

§Discipline

  • One method (release_elem), one *const Self parameter.
  • Implementor types must have HeapHeader at offset 0 (so v2_release(&(*ptr).header) is sound). The #[repr(C)] + first-field- header invariant per StringObj precedent enforces this structurally.
  • The trait is unsafe because callers must guarantee ptr validity (live allocation, no concurrent free).

§Forbidden

Per ADR-006 §2.7.24 Q25.A SUPERSEDED + audit §4.1.B.3:

  • HeapElement::release_elem taking a NativeKind parameter — refused; the trait dispatches via the Rust type system, not via a runtime kind probe. This is the §2.7.7 #4/#7 forbidden pattern (tag_bits-style runtime dispatch on the kind discriminator) at the per-element layer.
  • Bool-default fallback in release_elem body — surface-and-stop with NotImplemented(SURFACE: ...) at the construction-site when an inner payload’s drop semantics are unproven. Per §2.7.7 #9.
  • Implementing HeapElement for non-HeapHeader-equipped types (e.g. Arc<>-wrapped storage). The trait is structurally constrained to types with HeapHeader at offset 0; implementing it for an Arc<>-wrapped struct would fail the (*ptr).header field access at compile time.
  • Renaming HeapElement to defection-attractor framing (heap-bridge, elem-helper, release-translator, etc.) — per CLAUDE.md broader-family regex. The trait describes a structural property (this T lives on the v2-raw heap), not a dispatch role.

Traits§

HeapElement
v2-raw HeapHeader-equipped element carrier trait.