libsnobol4 1.0.2
High-performance SNOBOL4-style pattern matching library
Loading...
Searching...
No Matches
vm.h File Reference

Virtual machine types, opcodes, and execution API for libsnobol4. More...

#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
#include "snobol/dynamic_pattern.h"
Include dependency graph for vm.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes

struct  cp_range
 Unicode codepoint range [start, end] (both inclusive). More...
struct  snobol_range_meta_t
 Cached range metadata for a single charclass set. More...
struct  snobol_buf
 Generic growable byte buffer used for VM output accumulation. More...
struct  WriteLogEntry
 Write-log entry recording a single capture register modification. More...
struct  UndoRecord
 A single trail undo record. More...
struct  CompactChoiceHeader
 Header for a compact choice stack record (trail-based). More...
struct  choice
 Legacy full-snapshot choice stack entry. More...
struct  ChoiceArenaPage
struct  ChoiceArena
struct  VM
 VM state: all mutable state for a single pattern execution. More...
struct  search_vm_t
 Lightweight VM state for search-mode execution (Tier 1-7). More...

Macros

#define SNOBOL_DYNAMIC_PATTERN   1
 Enable dynamic pattern and table support.

Typedefs

typedef struct cp_range CpRange
 Unicode codepoint range [start, end] (both inclusive).
typedef void(* emit_cb) (const char *data, size_t len, void *udata)
 Callback invoked by OP_EMIT_* instructions to stream output.
typedef struct ChoiceArenaPage ChoiceArenaPage
typedef struct ChoiceArena ChoiceArena

Enumerations

enum  { MAX_CAPS = 64 }
 Maximum number of capture registers per VM execution. More...
enum  { MAX_VARS = 64 }
 Maximum number of named variable registers per VM execution. More...
enum  OpCode {
  OP_ACCEPT = 0 , OP_FAIL , OP_JMP , OP_SPLIT ,
  OP_LIT , OP_ANY , OP_NOTANY , OP_SPAN ,
  OP_BREAK , OP_CAP_START , OP_CAP_END , OP_ASSIGN ,
  OP_LEN , OP_EVAL , OP_ANCHOR , OP_REPEAT_INIT ,
  OP_REPEAT_STEP , OP_EMIT_LITERAL , OP_EMIT_CAPTURE , OP_EMIT_EXPR ,
  OP_EMIT_TABLE , OP_EMIT_FORMAT , OP_LABEL , OP_GOTO ,
  OP_GOTO_F , OP_TABLE_GET , OP_TABLE_SET , OP_ARRAY_GET ,
  OP_ARRAY_SET , OP_DYNAMIC , OP_DYNAMIC_DEF , OP_BREAKX ,
  OP_BAL , OP_FENCE , OP_REM , OP_RPOS ,
  OP_RTAB , OP_POS , OP_TAB , OP_ABORT ,
  OP_SUCCEED , OP_NOP
}
 Bytecode opcodes for the SNOBOL4 VM. More...
enum  { SNBL_FMT_UPPER = 1 }
enum  { SNBL_FMT_LOWER = 2 }
enum  { SNBL_FMT_LENGTH = 3 }
enum  { SNBL_FMT_LPAD = 4 }
enum  { SNBL_FMT_RPAD = 5 }
enum  { SNBL_TABLE_ID_UNBOUND = 0xFFFFU }
enum  snobol_builtin_fn_t {
  SNOBOL_FN_NONE = 0 , SNOBOL_FN_SIZE = 1 , SNOBOL_FN_TRIM = 2 , SNOBOL_FN_DUPL = 3 ,
  SNOBOL_FN_REVERSE = 4 , SNOBOL_FN_SUBSTR = 5 , SNOBOL_FN_REPLACE = 6 , SNOBOL_FN_REPLACE_CHAR = 7 ,
  SNOBOL_FN_LPAD = 8 , SNOBOL_FN_RPAD = 9 , SNOBOL_FN_CHAR = 10 , SNOBOL_FN_ORD = 11 ,
  SNOBOL_FN_UPPER = 12 , SNOBOL_FN_LOWER = 13 , SNOBOL_FN_IDENT = 14 , SNOBOL_FN_DIFFER = 15 ,
  SNOBOL_FN_LEXEQ = 16 , SNOBOL_FN_LEXLT = 17 , SNOBOL_FN_LEXGT = 18 , SNOBOL_FN_INTEGER = 19 ,
  SNOBOL_FN_REAL = 20 , SNOBOL_FN_NUMERIC = 21 , SNOBOL_FN_EQ = 22 , SNOBOL_FN_NE = 23 ,
  SNOBOL_FN_LT = 24 , SNOBOL_FN_GT = 25 , SNOBOL_FN_LE = 26 , SNOBOL_FN_GE = 27 ,
  SNOBOL_FN_MAX
}
 Built-in function dispatch IDs for direct C dispatch via OP_EVAL. More...
enum  { MAX_LOOPS = 16 }
 Maximum number of bounded-repetition loop counters per VM. More...
enum  UndoKind { UNDO_COUNTER_DEC = 0 , UNDO_CAP_WRITE , UNDO_WL_POP , UNDO_VAR_WRITE }
 Undo-record op kinds for the per-thread backtracking trail. More...
enum  { CHOICE_ARENA_PAGE_SIZE = 4096 }

Functions

ChoiceArena * vm_arena_create (void)
void vm_arena_destroy (ChoiceArena *arena)
void vm_arena_reset (ChoiceArena *arena)
uint8_t * vm_arena_alloc (ChoiceArena *arena, size_t n)
void vm_arena_pop_last (ChoiceArena *arena)
const uint8_t * get_ranges_ptr (const VM *vm, uint16_t set_id, uint16_t *out_count, uint16_t *out_case)
 Retrieve charclass range data for a set ID.
void snobol_build_range_meta (const uint8_t *bc, size_t bc_len, snobol_range_meta_t **out_table, size_t *out_count)
 Build a range metadata table from bytecode for O(1) set_id lookup.
bool ranges_to_ascii_bitmap (const uint8_t *ranges_ptr, size_t count, uint64_t map[2])
 Build a 128-bit ASCII bitmap from range data; returns false if any range exceeds 127.
bool ranges_to_full_bitmap (const uint8_t *ranges_ptr, size_t count, uint64_t map[4])
 Build a 256-bit byte-level bitmap from range data; supports the full 0-255 byte range (UTF-8 safe).
bool range_contains (const uint8_t *ranges_ptr, size_t count, uint32_t cp)
 Test whether a codepoint is contained in a packed range array.
bool vm_exec (VM *vm)
 Execute a single pass of VM bytecode (used internally by vm_run).
bool vm_run (VM *vm)
 Run the VM, re-executing on backtrack until accept or exhausted.
void vm_init_labels (VM *vm)
 Allocate label offset table; call before vm_run().
void vm_free_labels (VM *vm)
 Free label offset table.
bool vm_register_label (VM *vm, uint16_t label_id, uint32_t offset)
 Register a label at a given bytecode offset.
uint32_t vm_get_label_offset (VM *vm, uint16_t label_id)
 Retrieve the bytecode offset for a label; returns UINT32_MAX if not found.
void vm_init_tables (VM *vm)
 Initialise the VM's table registry.
void vm_free_tables (VM *vm)
 Free the VM's table registry.
bool vm_register_table (VM *vm, snobol_table_t *table, uint16_t *out_id)
 Register a table and return its runtime ID via out_id.
snobol_table_t * vm_get_table (VM *vm, uint16_t table_id)
 Look up a table by runtime ID; returns NULL if not found.
void vm_init_arrays (VM *vm)
 Initialise the VM's array registry.
void vm_free_arrays (VM *vm)
 Free the VM's array registry.
bool vm_register_array (VM *vm, snobol_array_t *array, uint16_t *out_id)
 Register an array and return its runtime ID via out_id.
snobol_array_t * vm_get_array (VM *vm, uint16_t array_id)
 Look up an array by runtime ID; returns NULL if not found.
void snobol_buf_init (snobol_buf *b)
 Initialise a snobol_buf to empty state (no allocation).
void snobol_buf_append (snobol_buf *b, const char *data, size_t len)
 Append len bytes from data to the buffer, growing as needed.
void snobol_buf_clear (snobol_buf *b)
 Reset buffer length to 0 (keeps allocation).
void snobol_buf_free (snobol_buf *b)
 Free buffer memory and reset to empty state.
void vm_push_choice (VM *vm, size_t ip, size_t pos)
 Push a backtracking choice point onto the VM's choice stack.
bool vm_pop_choice (VM *vm)
 Pop the most recent choice point; return false if stack is empty.
void snobol_vm_reset (VM *vm)
 Reset VM state between match attempts while keeping choice/allocation. Clears captures, counters, and rewinds the choice stack. The caller is responsible for setting ip/pos to appropriate values.
void vm_write_log_init (VM *vm)
 Allocate write-log circular buffer.
void vm_write_log_free (VM *vm)
 Free write-log buffer.
void vm_write_log_clear (VM *vm)
 Clear all write-log entries without freeing memory.
void vm_write_log_track_cap_start (VM *vm, uint8_t cap, size_t old_start)
 Track an old cap_start value before overwriting register cap.
void vm_write_log_track_cap_end (VM *vm, uint8_t cap, size_t old_end)
 Track an old cap_end value before overwriting register cap.
size_t vm_write_log_count_entries (const VM *vm)
 Return the current number of valid write-log entries.
void vm_write_log_copy_entries (const VM *vm, WriteLogEntry *dst, size_t dst_cap)
 Copy write-log entries into a caller-provided buffer.
size_t vm_compact_choice_record_size (const CompactChoiceHeader *hdr)
 Return the total size in bytes of a compact choice record.
void vm_trail_init (VM *vm)
 Allocate the undo trail buffer.
void vm_trail_free (VM *vm)
 Free the undo trail buffer.
void vm_trail_clear (VM *vm)
 Reset trail depth to zero without freeing memory.
void vm_trail_push (VM *vm, UndoRecord rec)
 Push a record onto the trail, growing the buffer as needed.
void vm_trail_counter_inc (VM *vm, uint8_t loop_id, uint32_t prior_count, size_t prior_last_pos)
 Record a counter increment (OP_REPEAT_STEP) for undo on backtrack.
void vm_trail_cap_write (VM *vm, uint8_t cap, uint8_t sub, size_t prior_start, size_t prior_end)
 Record a capture-register write (OP_CAP_START/OP_CAP_END) for undo. sub is 0 to restore only prior_start, 1 to restore only prior_end, and 2 to restore both.
void vm_trail_var_write (VM *vm, uint8_t var, size_t prior_start, size_t prior_end)
 Record a named-variable write (OP_ASSIGN) for undo on backtrack.
void vm_trail_replay (VM *vm, size_t base)
 Replay trail entries [base, top) in reverse, restoring prior state.
size_t vm_trail_depth (const VM *vm)
 Return the current number of live trail records.
size_t vm_choice_stack_memory_usage (VM *vm)
 Return the current bytes used by the choice stack.
size_t vm_choice_record_average_size (VM *vm)
 Return the average choice record size in bytes (computed from accumulated stats).
size_t vm_choice_stack_depth (VM *vm)
 Return the current number of live choice points on the stack.

Detailed Description

Virtual machine types, opcodes, and execution API for libsnobol4.

Defines the bytecode instruction set, VM state structure, and all functions for executing compiled SNOBOL4 patterns. This is an internal API used by the language bindings and the public snobol.h wrapper.

Definition in file vm.h.

Macro Definition Documentation

◆ SNOBOL_DYNAMIC_PATTERN

#define SNOBOL_DYNAMIC_PATTERN   1

Enable dynamic pattern and table support.

Definition at line 27 of file vm.h.

Typedef Documentation

◆ ChoiceArena

typedef struct ChoiceArena ChoiceArena

◆ ChoiceArenaPage

typedef struct ChoiceArenaPage ChoiceArenaPage

◆ CpRange

typedef struct cp_range CpRange

Unicode codepoint range [start, end] (both inclusive).

Used to represent character class ranges in the bytecode charclass tables.

◆ emit_cb

typedef void(* emit_cb) (const char *data, size_t len, void *udata)

Callback invoked by OP_EMIT_* instructions to stream output.

Definition at line 326 of file vm.h.

Enumeration Type Documentation

◆ anonymous enum

anonymous enum

Maximum number of named variable registers per VM execution.

Enumerator
MAX_VARS 

Definition at line 41 of file vm.h.

◆ anonymous enum

anonymous enum
Enumerator
SNBL_FMT_RPAD 

Definition at line 257 of file vm.h.

◆ anonymous enum

anonymous enum

Maximum number of bounded-repetition loop counters per VM.

Enumerator
MAX_LOOPS 

Definition at line 314 of file vm.h.

◆ anonymous enum

anonymous enum
Enumerator
SNBL_FMT_LPAD 

Definition at line 256 of file vm.h.

◆ anonymous enum

anonymous enum
Enumerator
SNBL_FMT_LOWER 

Definition at line 250 of file vm.h.

◆ anonymous enum

anonymous enum

Sentinel table_id written by compile_template_to_bytecode() for any table reference that has not yet been bound to a runtime ID. Call snobol_template_bind_tables() to resolve these to real IDs.

Enumerator
SNBL_TABLE_ID_UNBOUND 

Definition at line 262 of file vm.h.

◆ anonymous enum

anonymous enum
Enumerator
CHOICE_ARENA_PAGE_SIZE 

Definition at line 415 of file vm.h.

◆ anonymous enum

anonymous enum
Enumerator
SNBL_FMT_UPPER 

Definition at line 247 of file vm.h.

◆ anonymous enum

anonymous enum
Enumerator
SNBL_FMT_LENGTH 

Definition at line 253 of file vm.h.

◆ anonymous enum

anonymous enum

Maximum number of capture registers per VM execution.

Enumerator
MAX_CAPS 

Definition at line 39 of file vm.h.

◆ OpCode

enum OpCode

Bytecode opcodes for the SNOBOL4 VM.

Each opcode is followed by zero or more operand bytes as documented in the inline comments. Operands are big-endian.

Enumerator
OP_ACCEPT 

Pattern succeeds; no operands

OP_FAIL 

Pattern fails unconditionally; no operands

OP_JMP 

Unconditional jump; target: u32

OP_SPLIT 

Non-deterministic branch; target_a: u32, target_b: u32

OP_LIT 

Match literal bytes; offset: u32, len: u32

OP_ANY 

Match char in class; charclass id: u16

OP_NOTANY 

Match char NOT in class; charclass id: u16

OP_SPAN 

Match 1+ chars in class; charclass id: u16

OP_BREAK 

Consume until char in set (0 or more); charclass id: u16

OP_CAP_START 

Begin capture region; reg: u8

OP_CAP_END 

End capture region; reg: u8

OP_ASSIGN 

Assign capture register to variable; var: u16, reg: u8

OP_LEN 

Match exactly n codepoints; n: u32

OP_EVAL 

Call back to host; fn: u16, reg: u8

OP_ANCHOR 

Position anchor; type: u8 (0=start, 1=end)

OP_REPEAT_INIT 

Begin bounded repetition; loop_id: u8, min: u32, max: u32, skip_target: u32

OP_REPEAT_STEP 

Step bounded repetition; loop_id: u8, jmp_target: u32

OP_EMIT_LITERAL 

Append literal to output; offset: u32, len: u32

OP_EMIT_CAPTURE 

Append capture register to output; reg: u8

OP_EMIT_EXPR 

LEGACY: emit with expression; reg: u8, expr_type: u8 — use OP_EMIT_FORMAT in new code

OP_EMIT_TABLE 

Table-backed lookup emit; see vm.h inline encoding doc

OP_EMIT_FORMAT 

Formatted capture emit; reg: u8, format_type: u8 (see SNBL_FMT_*)

OP_LABEL 

Define label target; label_id: u16

OP_GOTO 

Unconditional label jump; label_id: u16

OP_GOTO_F 

Jump to label if last match failed; label_id: u16

OP_TABLE_GET 

Match a bound table value; table_id: u16, key_kind: u8, key payload, flags: u8, name_len: u8, name: bytes[name_len]. key_kind 0 = register (u8), 1 = inline literal (len u16 + bytes); a register key is a capture-derived subject range, a literal key is data. flags bit 0 = case-insensitive value matching. The stored value is matched against the subject and consumed; a missing key fails. Variable-length instruction.

OP_TABLE_SET 

Update: table[key] = value_reg; table_id: u16, key_kind: u8, key payload (same encoding as OP_TABLE_GET), value_reg: u8, name_len: u8, name: bytes[name_len]. The value register must hold a capture range (an empty range stores an empty value); the key is data and is not consumed. Variable-length.

OP_ARRAY_GET 

Lookup: dest_reg = array[key_reg]; array_id: u16, key_reg: u8, dest_reg: u8, name_len: u8, name: bytes[name_len]

OP_ARRAY_SET 

Update: array[key_reg] = value_reg; array_id: u16, key_reg: u8, value_reg: u8, name_len: u8, name: bytes[name_len]

OP_DYNAMIC 

Evaluate dynamic pattern from pending definition; no operands

OP_DYNAMIC_DEF 

Define inline dynamic pattern block; len: u32, bytecode...

OP_BREAKX 

BREAK with retry choice for O(n) tokenization; charclass id: u16

OP_BAL 

Match balanced delimiter pair; open_cp: u32, close_cp: u32

OP_FENCE 

Cut choice stack (no backtrack past this point); no operands

OP_REM 

Match remainder of subject to end; no operands

OP_RPOS 

Succeed when cursor is n codepoints from end; n: u32

OP_RTAB 

Advance cursor to n codepoints from end; n: u32

OP_POS 

Succeed when cursor is exactly n codepoints from start; n: u32

OP_TAB 

Advance cursor to n codepoints from start; n: u32

OP_ABORT 

Terminate entire match immediately; no operands

OP_SUCCEED 

Force immediate match success at current position; no operands

OP_NOP 

No-op — skip one byte (emitted by fusion pass)

Definition at line 167 of file vm.h.

◆ snobol_builtin_fn_t

Built-in function dispatch IDs for direct C dispatch via OP_EVAL.

IDs start at 1; ID 0 (SNOBOL_FN_NONE) means "host callback". All IDs < SNOBOL_FN_MAX are recognised built-ins.

Enumerator
SNOBOL_FN_NONE 

Not a built-in: use eval_fn host callback

SNOBOL_FN_SIZE 
See also
snobol_size()
SNOBOL_FN_TRIM 
See also
snobol_trim()
SNOBOL_FN_DUPL 
See also
snobol_dupl()
SNOBOL_FN_REVERSE 
See also
snobol_reverse()
SNOBOL_FN_SUBSTR 
See also
snobol_substr()
SNOBOL_FN_REPLACE 
See also
snobol_replace()
SNOBOL_FN_REPLACE_CHAR 
See also
snobol_replace_char()
SNOBOL_FN_LPAD 
See also
snobol_lpad()
SNOBOL_FN_RPAD 
See also
snobol_rpad()
SNOBOL_FN_CHAR 
See also
snobol_char_fn()
SNOBOL_FN_ORD 
See also
snobol_ord()
SNOBOL_FN_UPPER 
See also
snobol_upper()
SNOBOL_FN_LOWER 
See also
snobol_lower()
SNOBOL_FN_IDENT 
See also
snobol_ident()
SNOBOL_FN_DIFFER 
See also
snobol_differ()
SNOBOL_FN_LEXEQ 
See also
snobol_lexeq()
SNOBOL_FN_LEXLT 
See also
snobol_lexlt()
SNOBOL_FN_LEXGT 
See also
snobol_lexgt()
SNOBOL_FN_INTEGER 
See also
snobol_integer()
SNOBOL_FN_REAL 
See also
snobol_real()
SNOBOL_FN_NUMERIC 
See also
snobol_numeric()
SNOBOL_FN_EQ 
See also
snobol_eq()
SNOBOL_FN_NE 
See also
snobol_ne()
SNOBOL_FN_LT 
See also
snobol_lt()
SNOBOL_FN_GT 
See also
snobol_gt()
SNOBOL_FN_LE 
See also
snobol_le()
SNOBOL_FN_GE 
See also
snobol_ge()
SNOBOL_FN_MAX 

Sentinel: all IDs < SNOBOL_FN_MAX are known built-ins

Definition at line 277 of file vm.h.

◆ UndoKind

enum UndoKind

Undo-record op kinds for the per-thread backtracking trail.

The trail records only the mutations a thread makes to live VM state (counters, captures, named variables) since the last choice point. On a choice pop, the records belonging to the abandoned thread are replayed in reverse to restore pre-choice state — replacing the full memcpy snapshot.

Enumerator
UNDO_COUNTER_DEC 

OP_REPEAT_STEP incremented a counter

UNDO_CAP_WRITE 

OP_CAP_START / OP_CAP_END wrote a capture reg

UNDO_WL_POP 

Write-log entry was appended (capture delta)

UNDO_VAR_WRITE 

OP_ASSIGN wrote a named variable reg

Definition at line 347 of file vm.h.

Function Documentation

◆ get_ranges_ptr()

const uint8_t * get_ranges_ptr ( const VM * vm,
uint16_t set_id,
uint16_t * out_count,
uint16_t * out_case )

Retrieve charclass range data for a set ID.

Parameters
[in]vmVM instance (for bytecode range table).
[in]set_idCharclass set ID from the bytecode.
[out]out_countNumber of ranges returned.
[out]out_caseNon-zero if set is case-insensitive.
Returns
Pointer to packed range data, or NULL if set_id is out of range.

◆ range_contains()

bool range_contains ( const uint8_t * ranges_ptr,
size_t count,
uint32_t cp )

Test whether a codepoint is contained in a packed range array.

Parameters
[in]ranges_ptrRange data from get_ranges_ptr().
[in]countNumber of ranges.
[in]cpCodepoint to test.
Returns
true if cp falls within any range.

◆ ranges_to_ascii_bitmap()

bool ranges_to_ascii_bitmap ( const uint8_t * ranges_ptr,
size_t count,
uint64_t map[2] )

Build a 128-bit ASCII bitmap from range data; returns false if any range exceeds 127.

Parameters
[in]ranges_ptrRange data from get_ranges_ptr().
[in]countNumber of ranges.
[out]mapOutput 2×uint64 bitmap, one bit per ASCII code.
Returns
true if all codepoints fit in ASCII; false otherwise.

◆ ranges_to_full_bitmap()

bool ranges_to_full_bitmap ( const uint8_t * ranges_ptr,
size_t count,
uint64_t map[4] )

Build a 256-bit byte-level bitmap from range data; supports the full 0-255 byte range (UTF-8 safe).

Each bit position corresponds to a byte value (bit 0 → byte 0x00, bit 255 → byte 0xFF). Returns false if any range exceeds 255.

Parameters
[in]ranges_ptrRange data from get_ranges_ptr().
[in]countNumber of ranges.
[out]mapOutput 4×uint64 bitmap (256 bits).
Returns
true if all codepoints fit in [0, 255]; false otherwise.

◆ snobol_buf_append()

void snobol_buf_append ( snobol_buf * b,
const char * data,
size_t len )

Append len bytes from data to the buffer, growing as needed.

◆ snobol_buf_clear()

void snobol_buf_clear ( snobol_buf * b)

Reset buffer length to 0 (keeps allocation).

◆ snobol_buf_free()

void snobol_buf_free ( snobol_buf * b)

Free buffer memory and reset to empty state.

◆ snobol_buf_init()

void snobol_buf_init ( snobol_buf * b)

Initialise a snobol_buf to empty state (no allocation).

◆ snobol_build_range_meta()

void snobol_build_range_meta ( const uint8_t * bc,
size_t bc_len,
snobol_range_meta_t ** out_table,
size_t * out_count )

Build a range metadata table from bytecode for O(1) set_id lookup.

Scans the bytecode for the charclass trailer, resolves each set_id via get_ranges_ptr() (fallback path), and stores the results in a table indexed by (set_id - 1). The caller owns the returned table and must free it with snobol_free().

Parameters
[in]bcBytecode buffer.
[in]bc_lenBytecode length.
[out]out_tableReceives pointer to allocated table (or NULL).
[out]out_countReceives number of table entries (0 if none).

◆ snobol_vm_reset()

void snobol_vm_reset ( VM * vm)

Reset VM state between match attempts while keeping choice/allocation. Clears captures, counters, and rewinds the choice stack. The caller is responsible for setting ip/pos to appropriate values.

◆ vm_arena_alloc()

uint8_t * vm_arena_alloc ( ChoiceArena * arena,
size_t n )

◆ vm_arena_create()

ChoiceArena * vm_arena_create ( void )

◆ vm_arena_destroy()

void vm_arena_destroy ( ChoiceArena * arena)

◆ vm_arena_pop_last()

void vm_arena_pop_last ( ChoiceArena * arena)

◆ vm_arena_reset()

void vm_arena_reset ( ChoiceArena * arena)

◆ vm_choice_record_average_size()

size_t vm_choice_record_average_size ( VM * vm)

Return the average choice record size in bytes (computed from accumulated stats).

◆ vm_choice_stack_depth()

size_t vm_choice_stack_depth ( VM * vm)

Return the current number of live choice points on the stack.

◆ vm_choice_stack_memory_usage()

size_t vm_choice_stack_memory_usage ( VM * vm)

Return the current bytes used by the choice stack.

◆ vm_compact_choice_record_size()

size_t vm_compact_choice_record_size ( const CompactChoiceHeader * hdr)

Return the total size in bytes of a compact choice record.

◆ vm_exec()

bool vm_exec ( VM * vm)

Execute a single pass of VM bytecode (used internally by vm_run).

Parameters
[in,out]vmVM state.
Returns
true if the pattern matched; false on failure.

◆ vm_free_arrays()

void vm_free_arrays ( VM * vm)

Free the VM's array registry.

◆ vm_free_labels()

void vm_free_labels ( VM * vm)

Free label offset table.

◆ vm_free_tables()

void vm_free_tables ( VM * vm)

Free the VM's table registry.

◆ vm_get_array()

snobol_array_t * vm_get_array ( VM * vm,
uint16_t array_id )

Look up an array by runtime ID; returns NULL if not found.

◆ vm_get_label_offset()

uint32_t vm_get_label_offset ( VM * vm,
uint16_t label_id )

Retrieve the bytecode offset for a label; returns UINT32_MAX if not found.

◆ vm_get_table()

snobol_table_t * vm_get_table ( VM * vm,
uint16_t table_id )

Look up a table by runtime ID; returns NULL if not found.

◆ vm_init_arrays()

void vm_init_arrays ( VM * vm)

Initialise the VM's array registry.

◆ vm_init_labels()

void vm_init_labels ( VM * vm)

Allocate label offset table; call before vm_run().

◆ vm_init_tables()

void vm_init_tables ( VM * vm)

Initialise the VM's table registry.

◆ vm_pop_choice()

bool vm_pop_choice ( VM * vm)

Pop the most recent choice point; return false if stack is empty.

◆ vm_push_choice()

void vm_push_choice ( VM * vm,
size_t ip,
size_t pos )

Push a backtracking choice point onto the VM's choice stack.

◆ vm_register_array()

bool vm_register_array ( VM * vm,
snobol_array_t * array,
uint16_t * out_id )

Register an array and return its runtime ID via out_id.

◆ vm_register_label()

bool vm_register_label ( VM * vm,
uint16_t label_id,
uint32_t offset )

Register a label at a given bytecode offset.

◆ vm_register_table()

bool vm_register_table ( VM * vm,
snobol_table_t * table,
uint16_t * out_id )

Register a table and return its runtime ID via out_id.

◆ vm_run()

bool vm_run ( VM * vm)

Run the VM, re-executing on backtrack until accept or exhausted.

Parameters
[in,out]vmVM state.
Returns
true if the pattern matched; false if all paths failed.

◆ vm_trail_cap_write()

void vm_trail_cap_write ( VM * vm,
uint8_t cap,
uint8_t sub,
size_t prior_start,
size_t prior_end )

Record a capture-register write (OP_CAP_START/OP_CAP_END) for undo. sub is 0 to restore only prior_start, 1 to restore only prior_end, and 2 to restore both.

◆ vm_trail_clear()

void vm_trail_clear ( VM * vm)

Reset trail depth to zero without freeing memory.

◆ vm_trail_counter_inc()

void vm_trail_counter_inc ( VM * vm,
uint8_t loop_id,
uint32_t prior_count,
size_t prior_last_pos )

Record a counter increment (OP_REPEAT_STEP) for undo on backtrack.

◆ vm_trail_depth()

size_t vm_trail_depth ( const VM * vm)

Return the current number of live trail records.

◆ vm_trail_free()

void vm_trail_free ( VM * vm)

Free the undo trail buffer.

◆ vm_trail_init()

void vm_trail_init ( VM * vm)

Allocate the undo trail buffer.

◆ vm_trail_push()

void vm_trail_push ( VM * vm,
UndoRecord rec )

Push a record onto the trail, growing the buffer as needed.

◆ vm_trail_replay()

void vm_trail_replay ( VM * vm,
size_t base )

Replay trail entries [base, top) in reverse, restoring prior state.

◆ vm_trail_var_write()

void vm_trail_var_write ( VM * vm,
uint8_t var,
size_t prior_start,
size_t prior_end )

Record a named-variable write (OP_ASSIGN) for undo on backtrack.

◆ vm_write_log_clear()

void vm_write_log_clear ( VM * vm)

Clear all write-log entries without freeing memory.

◆ vm_write_log_copy_entries()

void vm_write_log_copy_entries ( const VM * vm,
WriteLogEntry * dst,
size_t dst_cap )

Copy write-log entries into a caller-provided buffer.

◆ vm_write_log_count_entries()

size_t vm_write_log_count_entries ( const VM * vm)

Return the current number of valid write-log entries.

◆ vm_write_log_free()

void vm_write_log_free ( VM * vm)

Free write-log buffer.

◆ vm_write_log_init()

void vm_write_log_init ( VM * vm)

Allocate write-log circular buffer.

◆ vm_write_log_track_cap_end()

void vm_write_log_track_cap_end ( VM * vm,
uint8_t cap,
size_t old_end )

Track an old cap_end value before overwriting register cap.

◆ vm_write_log_track_cap_start()

void vm_write_log_track_cap_start ( VM * vm,
uint8_t cap,
size_t old_start )

Track an old cap_start value before overwriting register cap.