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

Structs

StackValue

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

TaggedStack

Stack state for the tagged value stack

Constants

DEFAULT_STACK_CAPACITY

Default stack capacity (number of stack values)

STACK_VALUE_SIZE

Size of StackValue in bytes (40 bytes = 5 x u64)

Functions

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)