Module trace 

Infinite recursion debugging tools (force chain, trace, depth limit, stats). Infinite recursion debugging tools for the tree-walker evaluator.

Five integrated tools:

1. Force chain capture — always-on, captures the chain of thunk forces leading to a blackhole cycle.
2. Trace mode (SUI_TRACE_EVAL=1 or =verbose) — logs every thunk force to stderr or a ring buffer.
3. Max force depth (--max-force-depth N) — caps the force stack and reports early.
4. Thunk stats — extends perf.rs counters with thunk-specific metrics (created, forced unique, max depth).
5. Static cycle detection — lives in the compiler; see sui-bytecode/src/compiler.rs.

Structs

ForceChain

The chain of forces that led to a cycle.

ForceFrame

A single entry on the force stack.

Functions

add_overlay_flatten_nanos

Add nanos to the cumulative overlay-flatten-build timer.

add_self_rec_walk_nanos

Add nanos to the cumulative Storm-A (referenced_idents) timer.

add_sorted_entries_nanos

Add nanos to the cumulative sorted_entries timer.

capture_cycle

Capture the cycle portion of the force stack starting from the frame whose thunk_id matches the blackholed thunk.

check_force_depth

Check whether the current force depth exceeds the configured limit. Returns Ok(()) if within bounds or no limit is set.

current_force_depth

Get current force depth (debug).

dump_force_stack_ids

Diagnostic: dump the whole force stack’s thunk ids + files + descriptions.

dump_ring_tail

Dump the last n ring-buffer entries to stderr (for inline diagnostics).

dump_trace_on_error

Dump the trace ring buffer to stderr. Called on error paths.

force_stack_contains

Diagnostic: is thunk_id present anywhere on the current force stack? A true means the SAME thunk pointer is being re-entered (a genuine self-cycle); a false means the blackholed thunk is NOT on the stack (a re-created / distinct thunk — a sharing gap).

get_overlay_flatten_nanos

Read the cumulative overlay-flatten-build nanoseconds.

get_self_rec_walk_nanos

Read the cumulative Storm-A (referenced_idents) nanoseconds.

get_sorted_entries_nanos

Read the cumulative sorted_entries nanoseconds.

get_thunks_created

Get thunks created count (for progress snapshots).

get_thunks_forced

Get thunks forced count (for progress snapshots).

inc_maybe_other_kind

inc_thunks_created

Increment the thunks-created counter.

inc_thunks_forced_unique

Increment the thunks-forced-unique counter.

init_trace

Initialize tracing from the SUI_TRACE_EVAL environment variable.

pop_force

Pop a frame from the force stack. Called when a thunk finishes forcing.

push_force

Push a frame onto the force stack. Called when a thunk begins forcing.

report_maybe_other_kinds

report_thunk_stats

Report thunk stats to stderr (called from perf::report).

reset_thunk_stats

Zero the thunk-creation/force counters. Used by perf::reset / perf::with_scope to establish a clean measurement window.

set_max_force_depth

Set the maximum allowed force depth. 0 means no limit.

trace_enabled

Whether any trace mode is active.

trace_force_enter

Log a force-enter event. In verbose mode, prints immediately. In ring-buffer mode, stores for later dump.

trace_force_exit

Log a force-exit event (decrements trace depth).