13.1. Debug agent API

The DEBUGAPI module provides the debug agent infrastructure — creating, installing, and communicating with persistent debug agents that live in their own forked contexts. It supports cross-context function invocation, agent method calls, log interception, data and stack walking, instrumentation, and breakpoint management.

See Debug Agents and Data Walking with DapiDataWalker for hands-on tutorials.

All functions and symbols are in “debugapi” module, use require to get access to it.

require daslib/debugger

13.1.1. Handled structures

Prologue

Annotation for inspecting function call prologues. Provides access to call metadata inside the annotated block.

Fields:

  • _block : block<void>? - The block to execute with prologue context.

  • info : FuncInfo? - Pointer to the FuncInfo of the called function.

  • fileName : string - Pointer to the function argument values.

  • arguments : any? - Source file name of the call site.

  • cmres : void? - Pointer to the copy-on-return result slot.

  • line : LineInfo? - Line number of the call site.

  • stackSize : int - Stack size used by the function.

StackWalker

Annotation for declaring a stack walker class. Generates the boilerplate to subclass StackWalker from C++.

DataWalker

Annotation for declaring a data walker class. Generates the boilerplate to subclass DataWalker from C++.

DebugAgent
Fields:

  • isThreadLocal : bool - Annotation for declaring a debug agent class. Generates the boilerplate to subclass DebugAgent from C++. The optional isThreadLocal field installs as a thread-local agent.

13.1.2. Agent lifecycle

delete_debug_agent_context(category: string)

Removes the debug agent with the given category name. Notifies all other agents via onUninstall, then destroys the agent and its context. Safe no-op if the agent does not exist.

Arguments:

  • category : string implicit

fork_debug_agent_context(function: function<():void>)

Clones the current context and calls the setup function inside the clone. The cloned context becomes an agent context that stays resident for the lifetime of the program.

Arguments:

  • function : function<void>

get_debug_agent_context(category: string): Context&

Returns a reference to the Context of the named debug agent. Panics if the agent does not exist check with has_debug_agent_context first.

Arguments:

  • category : string implicit

has_debug_agent_context(category: string): bool

Returns true if a debug agent with the given category name is currently installed.

Arguments:

  • category : string implicit

install_debug_agent(agent: smart_ptr<DebugAgent>; category: string)

Installs a low-level smart_ptr<DebugAgent> under the given category name. Prefer install_new_debug_agent for the high-level pattern.

Arguments:

  • agent : smart_ptr< DebugAgent> implicit

  • category : string implicit

install_debug_agent_thread_local(agent: smart_ptr<DebugAgent>)

Installs a low-level smart_ptr<DebugAgent> as the thread-local debug agent. There can be only one thread-local agent per thread — installing a new one replaces the previous.

Arguments:
is_in_debug_agent_creation(): bool

Returns true if the current thread is inside a fork_debug_agent_context call. Used in auto-start guards to prevent recursive agent creation.

lock_debug_agent(block: block<():void>)

Warning

This is unsafe operation.

Executes the block while holding the global debug agent mutex. Use when iterating or modifying agent state that must be thread-safe.

Arguments:

  • block : block<void> implicit

13.1.3. Cross-context invocation

13.1.3.1. invoke_debug_agent_function

invoke_debug_agent_function(arg0: string; arg1: string; arg2: any; arg3: any; arg4: any; arg5: any; arg6: any)

Warning

This is unsafe operation.

Calls an [export, pinvoke] function in the named agent’s context. Similar to invoke_in_context but resolves the agent context automatically from the category name.

When category is an empty string (""), the call targets the thread-local debug agent’s context instead of a globally named one. There can be only one thread-local agent per thread, so no name is needed. The thread-local path is faster because it skips the global agent map lookup.

Arguments:

  • arg0 : string

  • arg1 : string

  • arg2 : any

  • arg3 : any

  • arg4 : any

  • arg5 : any

  • arg6 : any

invoke_debug_agent_function(arg0: string; arg1: string; arg2: any; arg3: any; arg4: any; arg5: any; arg6: any; arg7: any; arg8: any; arg9: any; arg10: any; arg11: any)
invoke_debug_agent_function(arg0: string; arg1: string; arg2: any; arg3: any; arg4: any; arg5: any; arg6: any; arg7: any; arg8: any; arg9: any)
invoke_debug_agent_function(arg0: string; arg1: string; arg2: any; arg3: any; arg4: any; arg5: any; arg6: any; arg7: any; arg8: any; arg9: any; arg10: any)
invoke_debug_agent_function(arg0: string; arg1: string; arg2: any; arg3: any; arg4: any; arg5: any; arg6: any; arg7: any; arg8: any)
invoke_debug_agent_function(arg0: string; arg1: string; arg2: any; arg3: any; arg4: any; arg5: any; arg6: any; arg7: any)
invoke_debug_agent_function(arg0: string; arg1: string; arg2: any)
invoke_debug_agent_function(arg0: string; arg1: string; arg2: any; arg3: any; arg4: any; arg5: any)
invoke_debug_agent_function(arg0: string; arg1: string; arg2: any; arg3: any; arg4: any)
invoke_debug_agent_function(arg0: string; arg1: string; arg2: any; arg3: any)
invoke_debug_agent_function(arg0: string; arg1: string)

13.1.3.2. invoke_debug_agent_method

invoke_debug_agent_method(arg0: string; arg1: string; arg2: any; arg3: any; arg4: any; arg5: any; arg6: any; arg7: any; arg8: any; arg9: any; arg10: any; arg11: any)

Warning

This is unsafe operation.

Calls a method on the debug agent’s class instance by name. The first argument is the agent category, the second is the method name, followed by up to 10 user arguments. The agent’s self is passed automatically.

When category is an empty string (""), the call targets the thread-local debug agent instead of a globally named one. There can be only one thread-local agent per thread — that is why it needs no name. The thread-local path is faster than a named agent lookup because it skips the global map search.

Arguments:

  • arg0 : string

  • arg1 : string

  • arg2 : any

  • arg3 : any

  • arg4 : any

  • arg5 : any

  • arg6 : any

  • arg7 : any

  • arg8 : any

  • arg9 : any

  • arg10 : any

  • arg11 : any

invoke_debug_agent_method(arg0: string; arg1: string; arg2: any; arg3: any; arg4: any; arg5: any; arg6: any; arg7: any; arg8: any; arg9: any)
invoke_debug_agent_method(arg0: string; arg1: string; arg2: any; arg3: any; arg4: any; arg5: any; arg6: any; arg7: any; arg8: any)
invoke_debug_agent_method(arg0: string; arg1: string; arg2: any)
invoke_debug_agent_method(arg0: string; arg1: string; arg2: any; arg3: any; arg4: any; arg5: any)
invoke_debug_agent_method(arg0: string; arg1: string; arg2: any; arg3: any)
invoke_debug_agent_method(arg0: string; arg1: string; arg2: any; arg3: any; arg4: any; arg5: any; arg6: any)
invoke_debug_agent_method(arg0: string; arg1: string; arg2: any; arg3: any; arg4: any)
invoke_debug_agent_method(arg0: string; arg1: string; arg2: any; arg3: any; arg4: any; arg5: any; arg6: any; arg7: any)
invoke_debug_agent_method(arg0: string; arg1: string)
invoke_debug_agent_method(arg0: string; arg1: string; arg2: any; arg3: any; arg4: any; arg5: any; arg6: any; arg7: any; arg8: any; arg9: any; arg10: any)

13.1.3.3. invoke_in_context

invoke_in_context(arg0: any; arg1: function<():void>; arg2: any; arg3: any; arg4: any; arg5: any; arg6: any; arg7: any; arg8: any; arg9: any; arg10: any; arg11: any)

Warning

This is unsafe operation.

Calls a function in another context. Accepts a Context reference and either a function name (string), a function pointer, or a lambda, plus up to 10 extra arguments. Target functions must be marked [export, pinvoke].

Arguments:

  • arg0 : any

  • arg1 : function<void>

  • arg2 : any

  • arg3 : any

  • arg4 : any

  • arg5 : any

  • arg6 : any

  • arg7 : any

  • arg8 : any

  • arg9 : any

  • arg10 : any

  • arg11 : any

invoke_in_context(arg0: any; arg1: function<():void>; arg2: any; arg3: any; arg4: any; arg5: any; arg6: any; arg7: any; arg8: any; arg9: any; arg10: any)
invoke_in_context(arg0: any; arg1: lambda<():void>)
invoke_in_context(arg0: any; arg1: function<():void>; arg2: any; arg3: any; arg4: any; arg5: any; arg6: any; arg7: any; arg8: any)
invoke_in_context(arg0: any; arg1: function<():void>; arg2: any; arg3: any; arg4: any; arg5: any; arg6: any)
invoke_in_context(arg0: any; arg1: function<():void>; arg2: any; arg3: any; arg4: any; arg5: any)
invoke_in_context(arg0: any; arg1: function<():void>; arg2: any; arg3: any; arg4: any; arg5: any; arg6: any; arg7: any)
invoke_in_context(arg0: any; arg1: function<():void>; arg2: any; arg3: any; arg4: any; arg5: any; arg6: any; arg7: any; arg8: any; arg9: any)
invoke_in_context(arg0: any; arg1: lambda<():void>; arg2: any; arg3: any; arg4: any; arg5: any; arg6: any; arg7: any; arg8: any; arg9: any; arg10: any)
invoke_in_context(arg0: any; arg1: lambda<():void>; arg2: any)
invoke_in_context(arg0: any; arg1: lambda<():void>; arg2: any; arg3: any; arg4: any; arg5: any; arg6: any)
invoke_in_context(arg0: any; arg1: lambda<():void>; arg2: any; arg3: any; arg4: any; arg5: any; arg6: any; arg7: any; arg8: any; arg9: any)
invoke_in_context(arg0: any; arg1: lambda<():void>; arg2: any; arg3: any; arg4: any; arg5: any; arg6: any; arg7: any; arg8: any; arg9: any; arg10: any; arg11: any)
invoke_in_context(arg0: any; arg1: lambda<():void>; arg2: any; arg3: any; arg4: any; arg5: any; arg6: any; arg7: any)
invoke_in_context(arg0: any; arg1: lambda<():void>; arg2: any; arg3: any; arg4: any; arg5: any)
invoke_in_context(arg0: any; arg1: lambda<():void>; arg2: any; arg3: any; arg4: any)
invoke_in_context(arg0: any; arg1: lambda<():void>; arg2: any; arg3: any; arg4: any; arg5: any; arg6: any; arg7: any; arg8: any)
invoke_in_context(arg0: any; arg1: function<():void>; arg2: any)
invoke_in_context(arg0: any; arg1: string; arg2: any; arg3: any; arg4: any; arg5: any; arg6: any; arg7: any; arg8: any; arg9: any; arg10: any; arg11: any)
invoke_in_context(arg0: any; arg1: string; arg2: any; arg3: any; arg4: any; arg5: any; arg6: any; arg7: any; arg8: any; arg9: any; arg10: any)
invoke_in_context(arg0: any; arg1: function<():void>)
invoke_in_context(arg0: any; arg1: function<():void>; arg2: any; arg3: any)
invoke_in_context(arg0: any; arg1: string; arg2: any; arg3: any; arg4: any; arg5: any; arg6: any; arg7: any)
invoke_in_context(arg0: any; arg1: string; arg2: any; arg3: any; arg4: any; arg5: any; arg6: any)
invoke_in_context(arg0: any; arg1: string; arg2: any; arg3: any; arg4: any; arg5: any; arg6: any; arg7: any; arg8: any)
invoke_in_context(arg0: any; arg1: string; arg2: any; arg3: any; arg4: any)
invoke_in_context(arg0: any; arg1: string; arg2: any)
invoke_in_context(arg0: any; arg1: string)
invoke_in_context(arg0: any; arg1: string; arg2: any; arg3: any)
invoke_in_context(arg0: any; arg1: string; arg2: any; arg3: any; arg4: any; arg5: any)
invoke_in_context(arg0: any; arg1: string; arg2: any; arg3: any; arg4: any; arg5: any; arg6: any; arg7: any; arg8: any; arg9: any)
invoke_in_context(arg0: any; arg1: function<():void>; arg2: any; arg3: any; arg4: any)
invoke_in_context(arg0: any; arg1: lambda<():void>; arg2: any; arg3: any)

13.1.4. Agent construction

make_data_walker(class: void?; info: StructInfo const?; block: block<(DataWalker?):void>)

Wraps a DapiDataWalker class pointer into a DataWalker? for use with walk_data.

Arguments:
make_debug_agent(class: void?; info: StructInfo const?): smart_ptr<DebugAgent>

Low-level constructor that wraps a DapiDebugAgent class pointer into a smart_ptr<DebugAgent>. Called internally by install_new_debug_agent.

Arguments:

  • class : void? implicit

  • info : StructInfo? implicit

make_stack_walker(class: void?; info: StructInfo const?; block: block<(StackWalker?):void>)

Wraps a DapiStackWalker class pointer into a smart_ptr<StackWalker> for use with walk_stack.

Arguments:

13.1.5. Agent tick and state collection

collect_debug_agent_state(context: Context; at: LineInfo)

Triggers onCollect on all installed debug agents, passing the calling context and line info. Agents can inspect the context and report variables via report_context_state.

Arguments:
debug_agent_command(command: string)

Sends a user-defined command string to all debug agents. Agents receive it in onUserCommand.

Arguments:

  • command : string implicit

debugger_stop_requested(): bool

Returns true if any debug agent has requested the program to stop (e.g. via a breakpoint or user interrupt).

on_breakpoints_reset(file: string; breakpointsNum: int)

Notifies all debug agents that breakpoints for the given file have been reset. The breakpointsNum parameter indicates the new breakpoint count.

Arguments:

  • file : string implicit

  • breakpointsNum : int

report_context_state(context: Context; category: string; name: string; info: TypeInfo const?; data: void?)

Reports a named variable from inside onCollect back to the debug system. Each call triggers onVariable on all agents with the category, name, type info, and data pointer.

Arguments:

  • context : Context implicit

  • category : string implicit

  • name : string implicit

  • info : TypeInfo? implicit

  • data : void? implicit

13.1.5.1. tick_debug_agent

tick_debug_agent()

Calls onTick on all installed debug agents (no-arg variant), or on a specific named agent (string variant). Typically called once per frame by the host application.

tick_debug_agent(agent: string)

13.1.6. Instrumentation

clear_instruments(context: Context)

Removes all instrumentation from the given context, restoring original execution.

Arguments:

13.1.6.1. instrument_all_functions

instrument_all_functions(context: Context)

Enables or disables instrumentation for all functions in the given context. Overloaded: the no-block variant instruments everything; the block variant calls a filter to select functions.

Arguments:
instrument_all_functions(ctx: Context; block: block<(function<():void>;SimFunction const?):uint64>)

13.1.6.2. instrument_all_functions_thread_local

instrument_all_functions_thread_local(ctx: Context; block: block<(function<():void>;SimFunction const?):uint64>)

Thread-local variant of instrument_all_functions. Instruments functions only on the current thread.

Arguments:
instrument_all_functions_thread_local(context: Context)
instrument_context_allocations(context: Context; isInstrumenting: bool)

Enables or disables allocation tracking on the given context. When enabled, the debug agent receives onAllocate / onReallocate / onFree callbacks.

Arguments:

  • context : Context implicit

  • isInstrumenting : bool

instrument_function(context: Context; function: function<():void>; isInstrumenting: bool; userData: uint64)

Enables or disables instrumentation for a specific function in the given context. The userData value is passed to the instrumentation callback.

Arguments:

  • context : Context implicit

  • function : function<void>

  • isInstrumenting : bool

  • userData : uint64

instrument_node(context: Context; isInstrumenting: bool; block: block<(LineInfo):bool>)

Enables or disables per-node instrumentation on the given context. The block receives each LineInfo and returns true to instrument that node.

Arguments:

  • context : Context implicit

  • isInstrumenting : bool

  • block : block<( LineInfo):bool> implicit

set_single_step(context: Context; enabled: bool)

Enables or disables single-step execution on the given context. When enabled, the debug agent receives onSingleStep for each statement.

Arguments:

  • context : Context implicit

  • enabled : bool

13.1.7. Data and stack walking

stack_depth(context: Context): int

Returns the current call stack depth of the given context.

Arguments:
stackwalk(context: Context; line: LineInfo)

Prints a human-readable stack trace of the given context to the log output.

Arguments:

13.1.7.1. walk_data

walk_data(walker: DataWalker?; data: void?; struct_info: StructInfo)

Walks a daslang data structure using the provided DataWalker. The walker receives typed callbacks for each value encountered. Overloaded for raw data+`StructInfo`, float4`+`TypeInfo, and void?`+`TypeInfo.

Arguments:
walk_data(walker: DataWalker?; data: void?; info: TypeInfo)
walk_data(walker: DataWalker?; data: float4; info: TypeInfo)
walk_stack(walker: StackWalker?; context: Context; line: LineInfo)

Walks the call stack of the given context using the provided StackWalker. The walker receives callbacks for each stack frame, argument, and local variable.

Arguments:

13.1.8. Context inspection

13.1.8.1. get_context_global_variable

get_context_global_variable(context: any; index: int): void?

Warning

This is unsafe operation.

Returns a pointer to a global variable in the given context, looked up by name (string variant) or by index (int variant). Returns null if not found.

Arguments:

  • context : any

  • index : int

get_context_global_variable(context: any; name: string): void?
get_heap_stats(context: Context; bytes: uint64?)

Warning

This is unsafe operation.

Writes the heap allocation statistics of the given context into the provided uint64 pointer.

Arguments:

  • context : Context implicit

  • bytes : uint64? implicit

has_function(context: Context; function_name: string): bool

Returns true if the given context contains an exported function with the specified name.

Arguments:

  • context : Context implicit

  • function_name : string implicit

13.1.9. Breakpoints

clear_hw_breakpoint(arg0: int): bool

Warning

This is unsafe operation.

Clears the hardware breakpoint with the given index. Returns true on success.

Arguments:

  • arg0 : int

set_hw_breakpoint(context: Context; address: void?; size: int; writeOnly: bool): int

Warning

This is unsafe operation.

Sets a hardware breakpoint at the given memory address. Returns the breakpoint index, or -1 on failure. The writeOnly flag selects write-only vs. read/write watch.

Arguments:

  • context : Context implicit

  • address : void? implicit

  • size : int

  • writeOnly : bool

13.1.10. Memory

break_on_free(context: Context; ptr: void?; size: uint)

Warning

This is unsafe operation.

Triggers a debug break when the specified memory region is freed. Useful for tracking down use-after-free bugs.

Arguments:

  • context : Context implicit

  • ptr : void? implicit

  • size : uint

free_temp_string(context: Context)

Warning

This is unsafe operation.

Frees all temporary string allocations in the given context.

Arguments:
temp_string_size(context: Context): uint64

Warning

This is unsafe operation.

Returns the total size in bytes of temporary string allocations in the given context.

Arguments:
track_insane_pointer(ptr: void?)

Warning

This is unsafe operation.

Begins tracking the specified pointer for dangling-reference detection.

Arguments:

  • ptr : void? implicit