Skip to main content

Module stack

Module stack 

Source
Expand description

Stack operations for the concatenative runtime.

Provides push / pop / peek, the shuffle FFI ops (dup / swap / rot / over / nip / tuck / 2dup / pick / roll), coroutine-local stack-base tracking for nested strands, stack allocation helpers, and the REPL stack-dump operation.

The tagged-value encoding itself (StackValue, tag constants, tag_int / untag_int, TaggedStack backing storage) lives in tagged_stack.

The Stack type is a pointer to the “current position” — where the next push goes. Push stores at *sp and returns sp + 1; pop returns sp - 1 and reads from *(sp - 1).

Constants§

DISC_BOOL
DISC_CHANNEL
DISC_CLOSURE
DISC_FLOAT
DISC_INT
Discriminant constants — retained for API compatibility with codegen and runtime code that switches on type. In tagged-ptr mode, these values are NOT stored in the StackValue itself (the tag is in the pointer bits). They are used only when the runtime unpacks a Value (via pop()) and needs to identify its type. Phase 2 codegen will use bit-level tag checks instead of loading these discriminants from memory.
DISC_MAP
DISC_QUOTATION
DISC_STRING
DISC_SYMBOL
DISC_VARIANT
DISC_WEAVECTX

Functions§

alloc_stack
Allocate a fresh stack buffer and return its base pointer.
alloc_test_stack
Allocate a fresh stack and register it as the current strand’s base.
clone_stack⚠
Safety
clone_stack_value⚠
Clone a tagged StackValue, handling heap types.
clone_stack_with_base⚠
Safety
drop_stack_value⚠
Drop a tagged StackValue, freeing heap types.
drop_top⚠
Pop the top value and drop it (decrement Arc refcount for heap types).
dup⚠
Duplicate the top value: ( a – a a )
get_stack_base
Read the current strand’s stack base, or a null pointer if unset.
heap_value_mut⚠
Get a mutable reference to a heap Value at the given stack position without popping (no Arc alloc/dealloc cycle).
nip⚠
Remove the second value: ( a b – b )
over⚠
Copy the second value to the top: ( a b – a b a )
patch_seq_2dup⚠
Duplicate top two values: ( a b – a b a b )
patch_seq_clone_value⚠
Clone a StackValue from LLVM IR.
patch_seq_drop_op⚠
Safety
patch_seq_dup⚠
Duplicate the top value: ( a – a a )
patch_seq_nip⚠
Remove the second value: ( a b – b )
patch_seq_over⚠
Copy the second value to the top: ( a b – a b a )
patch_seq_pick_op⚠
Pick: Copy the nth value to the top.
patch_seq_push_value⚠
Safety
patch_seq_roll⚠
Roll: Rotate n+1 items, bringing the item at depth n to the top.
patch_seq_rot⚠
Rotate the top three values: ( a b c – b c a )
patch_seq_set_stack_base⚠
Safety
patch_seq_stack_dump⚠
Dump all values on the stack (for REPL debugging).
patch_seq_swap⚠
Swap the top two values: ( a b – b a )
patch_seq_tuck⚠
Copy top value below second: ( a b – b a b )
peek⚠
Peek at the top value without removing it.
peek_heap_mut⚠
Convenience: get a mutable reference to the heap Value at stack top (sp - 1).
peek_heap_mut_second⚠
Convenience: get a mutable reference to the heap Value at sp - 2 (second from top).
peek_sv⚠
Peek at the raw StackValue without removing it.
pick⚠
Pick: Copy the nth value to the top.
pop⚠
Pop a value from the stack.
pop_sv⚠
Pop a StackValue directly from the stack.
pop_two⚠
Pop two values from the stack.
push⚠
Push a value onto the stack.
push_sv⚠
Push a StackValue directly onto the stack.
roll⚠
Roll: Rotate n+1 items, bringing the item at depth n to the top.
rot⚠
Rotate the top three values: ( a b c – b c a )
stack_value_size
stack_value_to_value⚠
Convert a tagged StackValue back to a Value (takes ownership)
swap⚠
Swap the top two values: ( a b – b a )
tuck⚠
Copy top value below second: ( a b – b a b )
two_dup⚠
Duplicate top two values: ( a b – a b a b )
value_to_stack_value
Convert a Value to a tagged StackValue

Type Aliases§

Stack
Stack: A pointer to the current position in a contiguous array of u64.