Skip to content

stdlib.debug

Debug Utilities (assert, hexdump, tracing, logging)

Generated from v0.60.1. 4 source files, 43 documented symbols.

debug.xi

fn debug_print(msg: Str)

Write a message to stderr with a "DEBUG:" prefix. Uses xiom.io.println which goes to stdout; stderr is not directly exposed in the current io module. The prefix clearly distinguishes debug output.

  • Precondition: msg.len() >= 0

fn assert_debug(cond: Bool, msg: Str)

Assert that a condition holds; panics with the given message if false. In a release build, this should be a no-op (stripped by the compiler). Currently unconditionally calls xiom.core.panic on failure. The compiler may optimize this away when debug assertions are disabled.

  • Precondition: msg.len() > 0

fn hexdump(data: &Vec[UInt8], width: Int) -> Str

Produce a formatted hex + ASCII dump string for a byte vector. Each line shows: 8-digit hex offset, 16 bytes in hex (grouped 8+8), then the ASCII representation (printable chars or '.').

Example output: 00000000 48 65 6C 6C 6F 20 57 6F 72 6C 64 21 00 00 00 00 |Hello World!....|

Complexity: O(n) where n = data.len().

  • Precondition: width > 0
  • Postcondition: result.len() >= 0

fn trace_point(name: Str) -> Str

Return a timestamped marker string for tracing execution flow. Uses xiom.time.time(0) for the current Unix timestamp. Format: "[TRACE] @ "

  • Precondition: name.len() > 0
  • Postcondition: result.len() > 0

fn elapsed_ms(start_ns: Int) -> Float64

Convert a nanosecond timestamp (e.g., from xiom.time) to elapsed milliseconds as a Float64. Use with xiom.time.Instant for measuring code sections.

Example: let start = xiom.time.Instant.now(); // ... work ... let ms = elapsed_ms(start.elapsed().as_nanos());

  • Postcondition: result >= 0

fn type_name_of[T]() -> Str

Return the name of a type at runtime. Delegates to xiom.reflect.type_name which currently returns "unknown" for most types due to limited RTTI support. This is a best-effort debugging aid.

  • Postcondition: result.len() > 0

fn log_debug(msg: Str)

Log a message at DEBUG level. Delegates to xiom.log.debug.

  • Precondition: msg.len() >= 0

fn log_info(msg: Str)

Log a message at INFO level. Delegates to xiom.log.info.

  • Precondition: msg.len() > 0

fn log_warn(msg: Str)

Log a message at WARN level. Delegates to xiom.log.warn.

  • Precondition: msg.len() > 0

fn log_error(msg: Str)

Log a message at ERROR level. Delegates to xiom.log.error.

  • Precondition: msg.len() > 0

disasm.xi

fn disasm_bytes(code: &Vec[UInt8], arch: Str) -> Result[Vec[Str], Str]

Disassemble raw bytes into mnemonic lines. Not supported in this build. Complexity: O(1).

fn disasm_function(ptr: Int, length: Int) -> Result[Vec[Str], Str]

Disassemble length bytes at an address. Not supported in this build. Complexity: O(1).

fn disasm_instruction_length(code: &Vec[UInt8], offset: Int) -> Result[Int, Str]

The byte length of the instruction at offset. Not supported in this build. Complexity: O(1).

fn disasm_arch_supported(arch: Str) -> Bool

Whether an architecture string is supported by a disassembly backend. Always false in this build. Complexity: O(1).

fn disasm_syntax(arch: Str, intel: Bool) -> Result[Unit, Str]

Select Intel or AT&T syntax for an architecture. Not supported in this build. Complexity: O(1).

fn disasm_symbolize(addr: Int) -> Option[Str]

Resolve an address to a symbol name. No symbol table is loaded in this build, so this always returns None. Complexity: O(1).

fn disasm_debug_info(addr: Int) -> Option[(Str, Int)]

Source debug info (file, line) for an address. No debug info is loaded in this build, so this always returns None. Complexity: O(1).

heap_report.xi

type HeapEntry

A heap snapshot entry: allocation address, size and call site.

Field Type
address Int
size Int
call_site Str

Derives: Clone

fn heap_usage() -> Int

Current heap bytes in use. See the header note: counters are inert in this build. Complexity: O(1).

fn heap_allocations() -> Int

Total allocation count since start or reset. Complexity: O(1).

fn heap_frees() -> Int

Total free count since start or reset. Complexity: O(1).

fn heap_live_objects() -> Int

Allocations minus frees. Complexity: O(1).

fn heap_report() -> Str

A human-readable heap summary. Complexity: O(1).

fn heap_report_json() -> Str

The heap summary as JSON. Complexity: O(1).

fn heap_peak_usage() -> Int

The highest heap bytes observed. Complexity: O(1).

fn heap_reset_stats()

Zero all counters, keeping the current usage. Callers can then observe deltas. In this build the counters are already inert. Complexity: O(1).

fn heap_snapshot() -> Vec[HeapEntry]

Capture all live allocations as entries. No live-allocation registry is available in this build, so the snapshot is empty. Complexity: O(1).

fn heap_top_allocations(n: Int) -> Vec[HeapEntry]

The n largest live allocations. Empty in this build (no live allocations are tracked). Complexity: O(1).

fn heap_is_empty() -> Bool

True when no live allocations remain. Complexity: O(1).

trace.xi

type TraceStack

Trace scope stack (module-level struct with a Vec[Str] -- primitive element type, which is codegen-safe in this build).

Field Type
names Vec[Str]
fn trace_backtrace() -> Vec[Str]

Capture the current call stack as symbol strings. Without a stack-walking intrinsic this returns the traced scope stack (deepest scope first); empty when tracing has not recorded any scopes. Complexity: O(scope depth).

fn trace_backtrace_symbols(frames: &Vec[Int]) -> Vec[Str]

Symbolize raw frame addresses as 0x hex strings. Invalid or negative addresses render as "0x0". Complexity: O(frames).

fn trace_source_location() -> Str

The current source location as "file:line". Without source-location intrinsics this returns the top of the traced scope stack (or "unknown"). Complexity: O(1).

fn trace_current_function() -> Str

The name of the calling function: the top of the traced scope stack, or "unknown". Complexity: O(1).

fn trace_current_file() -> Str

The file of the calling site. Not available in this build -- "unknown". Complexity: O(1).

fn trace_current_line() -> Int

The line of the calling site. Not available in this build -- 0. Complexity: O(1).

fn trace_print()

Print the current backtrace to the console (io.println; a raw stderr writer is not exposed in this build). Complexity: O(scope depth).

fn trace_log(msg: Str)

Emit a trace log line when tracing is enabled. Complexity: O(1).

fn trace_enabled() -> Bool

Whether tracing is currently enabled. Complexity: O(1).

fn trace_set_enabled(on: Bool)

Enable or disable tracing. Complexity: O(1).

fn trace_depth() -> Int

The current entry/exit nesting depth. Complexity: O(1).

fn trace_enter(name: Str)

Record entry to a named scope: pushes name and increments the depth. Complexity: O(1).

fn trace_exit(name: Str)

Record exit from a named scope: pops the matching scope and decrements the depth (clamped at 0). No-op when the stack is empty. Complexity: O(scope depth).