Module tagged_stack 

Tagged Stack Implementation

A contiguous array of 40-byte values for high-performance stack operations. The 40-byte size matches Rust’s Value enum with #[repr(C)] and the LLVM %Value = type { i64, i64, i64, i64, i64 } layout, enabling interoperability between inline IR and FFI operations.

Stack Value Layout (40 bytes)

┌─────────────────────────────────────────────────────────────────────────────┐
│  slot0 (8 bytes)  │  slot1  │  slot2  │  slot3  │  slot4  │
├───────────────────┼─────────┼─────────┼─────────┼─────────┤
│   Discriminant    │ Payload │  data   │  data   │  data   │
└─────────────────────────────────────────────────────────────────────────────┘

Value discriminants:
- 0 = Int:   slot1 contains i64 value
- 1 = Float: slot1 contains f64 bits
- 2 = Bool:  slot1 contains 0 or 1
- 3 = String, 4 = Variant, 5 = Map, 6 = Quotation, 7 = Closure

Stack Layout

Stack: contiguous array of 40-byte StackValue slots
┌──────────┬──────────┬──────────┬──────────┬─────────┐
│   v0     │   v1     │   v2     │   v3     │  ...    │
│ (40 B)   │ (40 B)   │ (40 B)   │ (40 B)   │         │
└──────────┴──────────┴──────────┴──────────┴─────────┘
                                             ↑ SP

- Grows upward
- SP points to next free slot
- Push: store at SP, increment SP
- Pop: decrement SP, load from SP

Performance Considerations

The 40-byte size enables:

• Direct compatibility with Rust’s Value enum (#[repr(C)])
• No conversion overhead when calling runtime functions
• Simple inline integer/boolean operations in compiled code

Modules

heap_flags

Flags for HeapObject

Structs

BoolObject

Bool heap object

FloatObject

Float heap object

HeapObject

Heap object header (8 bytes)

QuotationObject

Quotation heap object (stateless function)

StackValue

A 40-byte stack value, layout-compatible with LLVM’s %Value type.

TaggedStack

Stack state for the tagged value stack

Enums

HeapTag

Heap object type tags

Constants

DEFAULT_STACK_CAPACITY

Default stack capacity (number of stack values)

STACK_VALUE_SIZE

Size of StackValue in bytes (should be 40)

TAG_HEAP

Heap pointer tag (low bit clear)

TAG_INT

Integer tag (low bit set)

TAG_MASK

Tag bit mask

Functions

is_tagged_heap

Check if a tagged value is a heap pointer

is_tagged_int

Check if a tagged value is an integer

seq_alloc_bool

Allocate a bool heap object

seq_alloc_float

Allocate a float heap object

seq_alloc_quotation

Allocate a quotation heap object

seq_free_heap_object^⚠

Free a heap object based on its type tag

seq_get_bool^⚠

Get the bool value from a BoolObject

seq_get_float^⚠

Get the float value from a FloatObject

seq_heap_decref^⚠

Decrement the reference count of a heap object, freeing if zero

seq_heap_incref^⚠

Increment the reference count of a heap object

seq_stack_base^⚠

Get the base pointer of a tagged stack

seq_stack_capacity^⚠

Get the capacity of a tagged stack

seq_stack_clone^⚠

Clone a tagged stack (for spawn)

seq_stack_free^⚠

Free a tagged stack

seq_stack_grow^⚠

Grow a tagged stack to at least the given capacity

seq_stack_new

Allocate a new tagged stack

seq_stack_new_default

Allocate a new tagged stack with default capacity

seq_stack_set_sp^⚠

Set the current stack pointer (as index)

seq_stack_sp^⚠

Get the current stack pointer (as index)

tag_heap_ptr

Create a tagged heap pointer from a raw pointer

tag_int

Create a tagged integer from an i64

untag_heap_ptr

Extract a heap pointer from a tagged value

untag_int

Extract an i64 from a tagged integer

Type Aliases

TaggedValue

Legacy type alias for backward compatibility