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 debugapi

13.1.1. Structures

debugapi::DapiArray

Lightweight descriptor for an array encountered during data walking.

Fields

  • data : void? - Pointer to the array data.

  • size : uint - Number of elements currently in the array.

  • capacity : uint - Allocated capacity of the array.

  • lock : uint - Reference count lock for the array.

  • flags : bitfield<_shared;_hopeless> - Bitfield flags (_shared, _hopeless).

debugapi::DapiTable : DapiArray

Lightweight descriptor for a table encountered during data walking. Extends DapiArray.

Fields

  • keys : void? - Pointer to the table keys data.

  • hashes : uint? - Pointer to the hash values array.

debugapi::DapiBlock

Lightweight descriptor for a block encountered during data walking.

Fields

  • stackOffset : uint - Stack offset of the block.

  • argumentsOffset : uint - Arguments offset on the stack.

  • body : void? - Pointer to the block’s simulation node (SimNode).

  • aotFunction : void? - Pointer to the AOT-compiled function (if any).

  • functionArguments : float4? - Pointer to the block’s function arguments.

  • info : FuncInfo? - Pointer to the block’s FuncInfo metadata.

debugapi::DapiFunc

Lightweight descriptor for a function pointer encountered during data walking.

Fields

  • index : int - Index of the function in the context’s function table.

debugapi::DapiLambda

Lightweight descriptor for a lambda encountered during data walking.

Fields

  • captured : void? - Pointer to the lambda’s captured variable block.

debugapi::DapiSequence

Lightweight descriptor for an iterator/sequence encountered during data walking.

Fields

  • iter : void? - Pointer to the underlying Iterator object.

13.1.2. Handled structures

debugapi::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.

  • arguments : any? - Pointer to the function argument values.

  • fileName : string - 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.

debugapi::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.

debugapi::DataWalker

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

debugapi::StackWalker

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

13.1.3. Classes

debugapi::DapiDebugAgent
Fields

  • thisAgent : DebugAgent? - Base class for debug agents. Subclass and override methods (onLog, onCollect, onBreakpoint, etc.) to intercept runtime events. Register with install_new_debug_agent.

debugapi::DapiDataWalker

Base class for walking daslang data structures. Subclass and override per-type visitor methods (Int, Float, String, Array, Table, etc.) to inspect values. Create with make_data_walker.

debugapi::DapiStackWalker

Base class for walking the call stack. Subclass and override onBeforeCall, onAfterPop, onArgument, onVariable, etc. Create with make_stack_walker.

13.1.4. Agent lifecycle

debugapi::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

debugapi::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>

debugapi::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

debugapi::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

debugapi::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

debugapi::install_debug_agent_thread_local(agent: smart_ptr<DebugAgent>)

Installs a low-level smart_ptr<DebugAgent> as the thread-local debug agent.

Arguments
debugapi::install_new_debug_agent(agentPtr: auto; category: string) : auto()

Creates and installs a debug agent from a DapiDebugAgent subclass instance. This is the recommended high-level function for agent installation.

Arguments

  • agentPtr : auto

  • category : string

debugapi::install_new_thread_local_debug_agent(agentPtr: auto) : auto()

Creates and installs a thread-local debug agent from a DapiDebugAgent subclass instance.

Arguments

  • agentPtr : auto

debugapi::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.

debugapi::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.5. Cross-context invocation

13.1.5.1. invoke_debug_agent_function

debugapi::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.

Arguments

  • arg0 : string

  • arg1 : string

  • arg2 : any

  • arg3 : any

  • arg4 : any

  • arg5 : any

  • arg6 : any

debugapi::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)
debugapi::invoke_debug_agent_function(arg0: string; arg1: string; arg2: any; arg3: any; arg4: any; arg5: any; arg6: any; arg7: any; arg8: any; arg9: any)
debugapi::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)
debugapi::invoke_debug_agent_function(arg0: string; arg1: string; arg2: any; arg3: any; arg4: any; arg5: any; arg6: any; arg7: any; arg8: any)
debugapi::invoke_debug_agent_function(arg0: string; arg1: string; arg2: any; arg3: any; arg4: any; arg5: any; arg6: any; arg7: any)
debugapi::invoke_debug_agent_function(arg0: string; arg1: string; arg2: any)
debugapi::invoke_debug_agent_function(arg0: string; arg1: string; arg2: any; arg3: any; arg4: any; arg5: any)
debugapi::invoke_debug_agent_function(arg0: string; arg1: string; arg2: any; arg3: any; arg4: any)
debugapi::invoke_debug_agent_function(arg0: string; arg1: string; arg2: any; arg3: any)
debugapi::invoke_debug_agent_function(arg0: string; arg1: string)

13.1.5.2. invoke_debug_agent_method

debugapi::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.

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

debugapi::invoke_debug_agent_method(arg0: string; arg1: string; arg2: any; arg3: any; arg4: any; arg5: any; arg6: any; arg7: any; arg8: any; arg9: any)
debugapi::invoke_debug_agent_method(arg0: string; arg1: string; arg2: any; arg3: any; arg4: any; arg5: any; arg6: any; arg7: any; arg8: any)
debugapi::invoke_debug_agent_method(arg0: string; arg1: string; arg2: any)
debugapi::invoke_debug_agent_method(arg0: string; arg1: string; arg2: any; arg3: any; arg4: any; arg5: any)
debugapi::invoke_debug_agent_method(arg0: string; arg1: string; arg2: any; arg3: any)
debugapi::invoke_debug_agent_method(arg0: string; arg1: string; arg2: any; arg3: any; arg4: any; arg5: any; arg6: any)
debugapi::invoke_debug_agent_method(arg0: string; arg1: string; arg2: any; arg3: any; arg4: any)
debugapi::invoke_debug_agent_method(arg0: string; arg1: string; arg2: any; arg3: any; arg4: any; arg5: any; arg6: any; arg7: any)
debugapi::invoke_debug_agent_method(arg0: string; arg1: string)
debugapi::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.5.3. invoke_in_context

debugapi::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

debugapi::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)
debugapi::invoke_in_context(arg0: any; arg1: lambda<():void>)
debugapi::invoke_in_context(arg0: any; arg1: function<():void>; arg2: any; arg3: any; arg4: any; arg5: any; arg6: any; arg7: any; arg8: any)
debugapi::invoke_in_context(arg0: any; arg1: function<():void>; arg2: any; arg3: any; arg4: any; arg5: any; arg6: any)
debugapi::invoke_in_context(arg0: any; arg1: function<():void>; arg2: any; arg3: any; arg4: any; arg5: any)
debugapi::invoke_in_context(arg0: any; arg1: function<():void>; arg2: any; arg3: any; arg4: any; arg5: any; arg6: any; arg7: any)
debugapi::invoke_in_context(arg0: any; arg1: function<():void>; arg2: any; arg3: any; arg4: any; arg5: any; arg6: any; arg7: any; arg8: any; arg9: any)
debugapi::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)
debugapi::invoke_in_context(arg0: any; arg1: lambda<():void>; arg2: any)
debugapi::invoke_in_context(arg0: any; arg1: lambda<():void>; arg2: any; arg3: any; arg4: any; arg5: any; arg6: any)
debugapi::invoke_in_context(arg0: any; arg1: lambda<():void>; arg2: any; arg3: any; arg4: any; arg5: any; arg6: any; arg7: any; arg8: any; arg9: any)
debugapi::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)
debugapi::invoke_in_context(arg0: any; arg1: lambda<():void>; arg2: any; arg3: any; arg4: any; arg5: any; arg6: any; arg7: any)
debugapi::invoke_in_context(arg0: any; arg1: lambda<():void>; arg2: any; arg3: any; arg4: any; arg5: any)
debugapi::invoke_in_context(arg0: any; arg1: lambda<():void>; arg2: any; arg3: any; arg4: any)
debugapi::invoke_in_context(arg0: any; arg1: lambda<():void>; arg2: any; arg3: any; arg4: any; arg5: any; arg6: any; arg7: any; arg8: any)
debugapi::invoke_in_context(arg0: any; arg1: function<():void>; arg2: any)
debugapi::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)
debugapi::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)
debugapi::invoke_in_context(arg0: any; arg1: function<():void>)
debugapi::invoke_in_context(arg0: any; arg1: function<():void>; arg2: any; arg3: any)
debugapi::invoke_in_context(arg0: any; arg1: string; arg2: any; arg3: any; arg4: any; arg5: any; arg6: any; arg7: any)
debugapi::invoke_in_context(arg0: any; arg1: string; arg2: any; arg3: any; arg4: any; arg5: any; arg6: any)
debugapi::invoke_in_context(arg0: any; arg1: string; arg2: any; arg3: any; arg4: any; arg5: any; arg6: any; arg7: any; arg8: any)
debugapi::invoke_in_context(arg0: any; arg1: string; arg2: any; arg3: any; arg4: any)
debugapi::invoke_in_context(arg0: any; arg1: string; arg2: any)
debugapi::invoke_in_context(arg0: any; arg1: string)
debugapi::invoke_in_context(arg0: any; arg1: string; arg2: any; arg3: any)
debugapi::invoke_in_context(arg0: any; arg1: string; arg2: any; arg3: any; arg4: any; arg5: any)
debugapi::invoke_in_context(arg0: any; arg1: string; arg2: any; arg3: any; arg4: any; arg5: any; arg6: any; arg7: any; arg8: any; arg9: any)
debugapi::invoke_in_context(arg0: any; arg1: function<():void>; arg2: any; arg3: any; arg4: any)
debugapi::invoke_in_context(arg0: any; arg1: lambda<():void>; arg2: any; arg3: any)

13.1.6. Agent construction

13.1.6.1. make_data_walker

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

Wraps a DapiDataWalker class pointer into a smart_ptr<DataWalker> for use with walk_data.

Arguments

  • class : void? implicit

  • info : StructInfo? implicit

debugapi::make_data_walker(classPtr: auto) : smart_ptr<DataWalker>()
debugapi::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

13.1.6.2. make_stack_walker

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

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

Arguments

  • class : void? implicit

  • info : StructInfo? implicit

debugapi::make_stack_walker(classPtr: auto) : smart_ptr<StackWalker>()

13.1.7. Agent tick and state collection

debugapi::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
debugapi::debug_agent_command(command: string)

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

Arguments

  • command : string implicit

debugapi::debugger_stop_requested() : bool()

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

debugapi::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

debugapi::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.7.1. tick_debug_agent

debugapi::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.

debugapi::tick_debug_agent(agent: string)

13.1.8. Instrumentation

debugapi::clear_instruments(context: Context)

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

Arguments

13.1.8.1. instrument_all_functions

debugapi::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
debugapi::instrument_all_functions(ctx: Context; block: block<(function<():void>;SimFunction const?):uint64>)

13.1.8.2. instrument_all_functions_thread_local

debugapi::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
debugapi::instrument_all_functions_thread_local(context: Context)
debugapi::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

debugapi::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

debugapi::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

debugapi::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.9. Data and stack walking

debugapi::stack_depth(context: Context) : int()

Returns the current call stack depth of the given context.

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

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

Arguments

13.1.9.1. walk_data

debugapi::walk_data(walker: smart_ptr<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
debugapi::walk_data(walker: smart_ptr<DataWalker>; data: void?; info: TypeInfo)
debugapi::walk_data(walker: smart_ptr<DataWalker>; data: float4; info: TypeInfo)
debugapi::walk_stack(walker: smart_ptr<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.10. Context inspection

13.1.10.1. get_context_global_variable

debugapi::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

debugapi::get_context_global_variable(context: any; name: string) : void?()
debugapi::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

debugapi::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.11. Breakpoints

debugapi::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

debugapi::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.12. Memory

debugapi::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

debugapi::free_temp_string(context: Context)

Warning

This is unsafe operation.

Frees all temporary string allocations in the given context.

Arguments
debugapi::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
debugapi::track_insane_pointer(ptr: void?)

Warning

This is unsafe operation.

Begins tracking the specified pointer for dangling-reference detection.

Arguments

  • ptr : void? implicit