ddn.dev.gdbmi

An idiomatic, asynchronous wrapper around the GDB Machine Interface (MI).

The implementation focuses on:

  • A robust MI parser and value model (MiValue, MiRecord)
  • A cross-platform process wrapper (GdbMiSession) using threads + an event queue
  • An integration-friendly API for GUI and TUI applications (non-blocking event polling)

The wrapper is intentionally fully generic: you can send any MI command string. Higher-level helper functions can be layered on top without changing the core.

Authors

Dejan Lekić

Copyright

Copyright (c) 2026, DDN (D Developer Network) Members
var _debuggerAvailableCache DEFAULT_COMMAND_TIMEOUT DEFAULT_EVENT_TIMEOUT
alias MiRecord MiVisualizer
enum GdbMiDisassemblyMode GdbMiEngine GdbMiSessionState GdbMiWatchKind MiAsyncKind MiCommandPriority MiListKind MiStreamKind MiValueKind
struct DTypeInfo DubProjectInfo GdbMiConfig GdbMiEngineMetadata GdbMiEvent GdbMiInstruction GdbMiLogFilter MiAsyncRecord MiList MiParser MiPromptRecord MiQueuedCommand MiResult MiResultRecord MiStreamRecord MiToken MiTuple MiUnknownRecord MiVisualizerRegistry
class GdbCommandException GdbException GdbMemoryReadException GdbMiConsoleManager GdbMiParseException GdbMiSession GdbMiVariable GdbProcessException GdbSessionStoppedException GdbTimeoutException MiPendingCommand MiValue
fn buildTestExecutable debuggerAvailable demangleDSymbol escapeMiCString findResult isAsync isResult isStream parseAsyncKind parseDType parseDubProject parseGdbVersion parseInstructions parseMiRecord parseStreamKind quoteMiArg requireResult

Types 42

enumMiStreamKind

MI stream channel kinds.

CONSOLE`~` console stream.
TARGET`@` target stream.
LOG`&` log stream.
enumMiAsyncKind

MI async record kinds.

EXEC`*` exec async record.
STATUS`+` status async record.
NOTIFY`=` notify async record.
structMiToken

A token optionally attached to an MI record.

Fields
bool presentWhether the token is present.
ulong valueToken value when `present` is `true`.
Methods
MiToken none() @safe pure nothrow @nogcCreates an absent token.
MiToken some(ulong value) @safe pure nothrow @nogcCreates a present token.
structMiResult

A single variable=value entry in MI output.

Fields
string variableVariable name.
MiValue valueValue assigned to the variable.
structMiTuple

MI tuple value: { result (, result)* }.

Fields
MiResult[] resultsResults inside the tuple.
enumMiListKind

MI list kind.

VALUESList contains values.
RESULTSList contains results (`name=value`).
structMiList

MI list value: `[ ... ]`.

Fields
MiListKind kindWhether the list contains values or results.
MiValue[] valuesValue items (valid when `kind == MiListKind.VALUES`).
MiResult[] resultsResult items (valid when `kind == MiListKind.RESULTS`).
enumMiValueKind

MI value kind.

STRINGC-string value.
TUPLETuple value.
LISTList value.
classMiValue

MI value.

Note

MI values are recursive (tuples and lists can contain values). To keep the

representation finite-sized, MiValue is a reference type.

Fields
MiValueKind _kind
string _stringValue
MiTuple _tupleValue
MiList _listValue
Methods
MiValueKind kind() const @safe pure nothrow @nogcReturns: Kind of this value.
MiValue fromString(string s) @safeCreates a string value.
MiValue fromTuple(MiTuple t) @safeCreates a tuple value.
MiValue fromList(MiList l) @safeCreates a list value.
string getString() @safeReturns: String value. Throws: `Exception` if `kind != MiValueKind.STRING`.
string getDemangledString() @safeReturns: Demangled string value. Throws: `Exception` if `kind != MiValueKind.STRING`.
bool isDArray() @safeReturns: `true` if this value has the structure of a D dynamic array.
string asDString(GdbMiSession session) @trustedTries to read this value as a D string.
wstring asDWString(GdbMiSession session) @trustedTries to read this value as a D wstring (UTF-16).
bool isDAssociativeArray() @safeReturns: `true` if this value looks like a D associative array.
MiResult[] asDAssociativeArray() @safeTries to fetch and parse a D associative array into key-value pairs.
MiTuple getTuple() @safeReturns: Tuple value. Throws: `Exception` if `kind != MiValueKind.TUPLE`.
MiValue tryAsTuple() @safeTries to interpret this value as a tuple.
private string findInSummary(string summary, string key) @safeTries to find a value in a GDB string summary like "{a = 1, b = 2}".
MiList getList() @safeReturns: List value. Throws: `Exception` if `kind != MiValueKind.LIST`.
long asInt() @safeReturns: String value parsed as integer. Throws: `Exception` if not a string or not an integer.
bool asBool() @safeReturns: String value parsed as boolean. Throws: `Exception` if not a string or not a known boolean representation.
MiValue[] asArray() @safeReturns: List items. Throws: `Exception` if not a list or if it's a list of results.
JSONValue toJson() @safeReturns: JSON representation of this value.
aliasMiVisualizer = Nullable!string delegate(MiValue value, string typeName, GdbMiSession session) @safe

A delegate that takes an MI value and returns a user-friendly string representation. If the visualizer does not handle the value, it should return an empty Nullable.

structMiVisualizerRegistry

Registry for D-language custom visualizers.

Visualizers are tried in registration order (first-match wins). Once a visualizer returns a non-null Nullable!string, no further visualizers are consulted.

Thread safety: The visualizer list is a module-level static array.

Registration (register) and lookup (visualize) are not synchronized. Register all visualizers before starting any GDB session to avoid data races. The built-in visualizers registered by registerBuiltins() are typically called once at program startup.

Registration timing: Visualizers should be registered before any

call to visualize(). Registering a visualizer while a visualize() call is in progress on another thread constitutes a data race.

Fields
MiVisualizer[] _visualizers
Methods
void register(MiVisualizer v) @safeRegisters a new visualizer.
string visualize(MiValue value, string typeName = null, GdbMiSession session = null) @safeTries to visualize an MI value using registered visualizers.
void registerBuiltins() @safeRegisters built-in visualizers for common D types.
Nullable!string visualizeSysTime(MiValue value, string typeName, GdbMiSession session) @safeVisualizer for `std.datetime.SysTime`.
Nullable!string visualizeVariant(MiValue value, string typeName, GdbMiSession session) @safeVisualizer for `std.variant.Variant`.
Nullable!string visualizeRange(MiValue value, string typeName, GdbMiSession session) @safeVisualizer for common D ranges.
structMiPromptRecord

MI prompt record: (gdb).

structMiResultRecord

MI result record: ^done,....

Fields
MiToken tokenOptional token.
string resultClassResult class (`done`, `error`, ...).
MiResult[] resultsResults.
structMiAsyncRecord

MI async record: *stopped,..., =thread-created,..., ...

Fields
MiToken tokenOptional token.
MiAsyncKind kindKind (`*`, `+`, `=`).
string asyncClassAsync class (`stopped`, `running`, `thread-created`, ...).
MiResult[] resultsResults.
structMiStreamRecord

MI stream record: `~"..."`, `@"..."`, `&"..."`.

Fields
MiStreamKind kindStream kind.
string textDecoded stream content.
classGdbMiConsoleManager

Manages GDB console history and state.

Fields
string[] _history
size_t _maxHistory
string _historyFile
void delegate(string, Exception) @safe _errorCallback
Methods
void addHistory(string command) @safeAdds a command to the history.
const(string[]) history() const @safe pure nothrow @nogcReturns: The command history.
void loadHistory() @trustedLoads history from the history file.
void saveHistory() @trustedSaves history to the history file.
Constructors
this(size_t maxHistory = 1000, string historyFile = null, void delegate(string, Exception) @safe errorCallback = null)Creates a console manager.
structMiUnknownRecord

An unrecognized/opaque line produced by GDB.

Fields
string lineRaw line text (without line ending).
aliasMiRecord = Algebraic!(MiPromptRecord, MiResultRecord, MiAsyncRecord, MiStreamRecord, MiUnknownRecord)

Any MI record.

enumGdbMiDisassemblyMode

Disassembly modes.

MIXED_SOURCE_IGNORE_EMPTY = 0Source and assembly, ignore source lines without assembly. GDB mode 0.
MIXED_SOURCE_SHOW_EMPTY = 1Source and assembly, show all source lines. GDB mode 1.
INSTRUCTIONS_ONLY = 2Assembly instructions only. GDB mode 2.
MODE_3 = 3Mixed source and assembly with restricted scope. Corresponds to GDB disassembly mode 3 — instructions for the current function only, with source interleaved where available.
MODE_4 = 4Mixed source and assembly with full scope. Corresponds to GDB disassembly mode 4 — instructions for the entire file or specified range, with source interleaved.
MODE_5 = 5Source-centric view with assembly annotations. Corresponds to GDB disassembly mode 5 — shows source lines with their associated assembly instructions inlined.
enumGdbMiWatchKind

Watchpoint kinds.

WRITEWrite watchpoint.
READRead watchpoint.
ACCESSAccess (read or write) watchpoint.
structGdbMiInstruction

Represents a single disassembled instruction.

Fields
string addressAddress of the instruction.
string funcNameName of the function containing the instruction.
long offsetOffset from the start of the function.
string instThe instruction text.
string opcodesOpcode bytes (if requested).
long lineSource line number (in mixed mode).
string fileSource file name (in mixed mode).
structGdbMiEvent

Event produced by GdbMiSession.

Fields
MiRecord recordParsed record (if any).
string rawLineRaw line as received from GDB (without line ending).
enumGdbMiEngine

Debugger engine kinds.

GDBGNU Debugger.
LLDBLLVM Debugger (via lldb-mi).
enumMiCommandPriority

Priority for MI commands.

LOW = 0Background/low priority tasks.
NORMAL = 1Regular commands.
HIGH = 2UI-driven or urgent commands.
CRITICAL = 3Critical commands that must jump to the front (e.g., interrupt).
structGdbMiLogFilter

Log filtering rules.

Fields
string regexOnly log records matching this regex (on raw line).
string[] asyncClassesOnly log these async record classes (e.g. ["stopped", "running"]).
bool onlyResultsOnly log result records.
bool onlyAsyncOnly log async records.
bool onlyStreamOnly log stream records.
bool delegate(string rawLine, bool isOutgoing) @safe filterCustom filter delegate. Returns true to log.
structGdbMiConfig

Session configuration.

Fields
GdbMiEngine engineDebugger engine.
string debuggerPathPath to the debugger executable (e.g. `gdb`, `lldb-mi`).
string[] extraArgsExtra arguments passed to the debugger.
bool forwardResultRecordsToEventsWhether `^result` records should also be forwarded to the event queue.
void delegate(string, bool) @safe loggerLogger delegate for MI traffic. Params are (rawLine, isOutgoing).
GdbMiLogFilter logFilterLogging filter.
string workingDirectoryWorking directory for the debugger.
string[string] envEnvironment variables for the debugger.
bool autoDispatchEventsWhether events should be automatically dispatched to listeners from the reader thread.
uint commandsPerSecondMaximum commands to send per second. 0 means no limit.
Methods
void validate() @safeValidates this configuration and throws on invalid values.
structGdbMiEngineMetadata

Metadata about the debugger engine.

Fields
string nameEngine name (GNU gdb, LLDB, etc.).
string versionStringFull version string.
int majorMajor version number.
int minorMinor version number.
int patchPatch version number.
string[] featuresSupported features.
structDTypeInfo

D-language type information including qualifiers.

Fields
string baseTypeBase type name without qualifiers.
bool isSharedWhether the type is shared.
bool isImmutableWhether the type is immutable.
bool isConstWhether the type is const.
bool isInoutWhether the type is inout (wildcard).
structDubProjectInfo

Information about a DUB project.

Fields
string targetPathPath to the target executable.
string[] importPathsList of import paths.
classGdbException : Exception

Base exception for all GDB-related errors.

Constructors
this(string msg, string file = __FILE__, size_t line = __LINE__)
classGdbCommandException : GdbException

Exception thrown when a GDB command fails.

Fields
string resultClassMI result class (e.g. "error").
Constructors
this(string msg, string resultClass, string file = __FILE__, size_t line = __LINE__)
classGdbProcessException : GdbException

Exception thrown when the GDB process fails.

Constructors
this(string msg, string file = __FILE__, size_t line = __LINE__)
classGdbTimeoutException : GdbException

Exception thrown when a GDB command times out.

Includes the command text, token, and timeout duration for diagnostics.

Fields
ulong tokenToken of the command that timed out.
string commandCommand string that timed out.
Duration timeoutDuration that was waited.
Constructors
this(string msg, string file = __FILE__, size_t line = __LINE__)
this(ulong token, string command, Duration timeout, string file = __FILE__, size_t line = __LINE__)Constructs a timeout exception with full command context.
classGdbMemoryReadException : GdbException

Thrown when a memory read fails or returns unexpected data.

Constructors
this(string msg, string file = __FILE__, size_t line = __LINE__)
classGdbSessionStoppedException : GdbException

Thrown when an operation is attempted on a stopped session.

Constructors
this(string msg = "Session is stopped", string file = __FILE__, size_t line = __LINE__)
classGdbMiParseException : GdbException

Thrown when MI output parsing fails.

Includes the parser position, a description of what was expected, and a short snippet of the input around the error location to aid diagnostics.

Fields
size_t positionParser position where the error was detected.
string expectedDescription of what was expected (e.g. `"'"`, `"identifier"`, `"value"`).
string snippetShort excerpt of the input around the error position (max 40 chars).
Constructors
this(string msg, size_t position, string expected, string snippet, string file = __FILE__, size_t line = __LINE__)Constructs a parse exception.
classMiPendingCommand

A pending MI command.

Fields
ulong _token
Mutex _mutex
Condition _cond
bool _ready
Nullable!MiResultRecord _result
Throwable _error
MonoTime _startTime
Duration _roundTripTime
int _completedCount
string _command
Methods
ulong token() const @safe pure nothrow @nogcReturns: Token identifying this command.
bool ready() const @trustedReturns: `true` if the result (or error) is available.
MiResultRecord wait(Duration timeout = DEFAULT_COMMAND_TIMEOUT)Waits for the command to complete.
Duration roundTripTime() @trustedReturns: The round-trip time for this command. Throws: `Exception` if not yet ready.
void fulfill(MiResultRecord record) @trustedCompletes this pending command with a parsed MI result record.
void fail(Throwable error) @trustedCompletes this pending command with an error.
Constructors
this(ulong token, string command = "")Creates a pending command.
structMiQueuedCommand

Internal structure for enqueued MI commands.

Fields
string command
ulong token
MiCommandPriority priority
MiPendingCommand pending
Methods
int opCmp(const ref MiQueuedCommand rhs) const @safe pure nothrow @nogcCompares two queued commands for priority.
enumGdbMiSessionState

Session lifecycle states.

Used internally to reject operations on a stopping or stopped session.

ACTIVE — normal operation. STOPPING — stop() has been called; cleanup in progress. STOPPED — cleanup complete; session is fully shut down.

ACTIVE
STOPPING
STOPPED
classGdbMiSession

A running GDB process in MI mode.

You interact with the session by:

  • Sending commands with sendCommand (non-blocking) and optionally waiting via MiPendingCommand
  • Polling tryPopEvent for async and stream output (and optionally result records)
Fields
GdbMiConfig _config
File _stdin
File _stdout
File _stderr
typeof(pipeProcess(["gdb"], Redirect.stdin | Redirect.stdout | Redirect.stderr)) _proc
ulong _nextToken
Mutex _writeMutex
Mutex _commandQueueMutex
Condition _commandQueueCond
MiQueuedCommand[] _commandQueue
Thread _commandSenderThread
Mutex _pendingMutex
MiPendingCommand[ulong] _pending
Mutex _eventMutex
Condition _eventCond
GdbMiEvent[] _events
size_t _eventHead
void delegate(GdbMiEvent)[] _eventListeners
Thread _stdoutThread
Thread _stderrThread
GdbMiSessionState _state
string _currentThreadId
int _currentFrameLevel
Methods
void stop() @trustedStops the GDB session.
MiPendingCommand sendCommand(string command, MiCommandPriority priority = MiCommandPriority.NORMAL) @trustedSends an MI command.
MiPendingCommand cliExecute(string command) @trustedExecutes a raw CLI command using the console interpreter.
MiPendingCommand cliComplete(string partialCommand) @trustedGets completion suggestions for a partial CLI command.
MiPendingCommand maintStatistics() @trustedReturns GDB internal statistics.
MiPendingCommand sourceScript(string file) @trustedExecutes a GDB script from a file.
MiPendingCommand macroExpand(string macroName) @trustedExpands a macro at a specific source location.
MiPendingCommand macroList(string file = null, int line = - 1) @trustedLists macros defined at a specific source location.
MiPendingCommand breakInsert(string location, bool temporary = false) @trustedInserts a breakpoint.
MiPendingCommand breakDelete(int[] numbers) @trustedDeletes breakpoints.
MiPendingCommand breakEnable(int[] numbers) @trustedEnables breakpoints.
MiPendingCommand breakDisable(int[] numbers) @trustedDisables breakpoints.
MiPendingCommand breakList() @trustedLists all breakpoints.
MiPendingCommand breakAfter(int number, int count) @trustedSets the ignore count of a breakpoint.
MiPendingCommand breakCondition(int number, string condition = null) @trustedSets the condition of a breakpoint.
MiPendingCommand breakCommands(int number, string[] commands) @trustedSets the commands to be executed when a breakpoint is hit.
MiPendingCommand breakCatch(string event, bool temporary = false, string[] extraArgs = null) @trustedInserts a catchpoint.
MiPendingCommand breakExceptionAdd(string exception = null, bool unhandled = false, bool temporary = false) @trustedAdds an Ada exception catchpoint.
MiPendingCommand breakExceptionRemove(int number) @trustedRemoves an Ada exception catchpoint.
void autoConfigureFromDub(string projectPath) @trustedAuto-configures the session based on a DUB project. Loads the executable and sets up source search paths.
void autoConfigureDubTests(string projectPath) @trustedAuto-configures the session for running DUB unit tests. It builds the test executable and loads it.
MiPendingCommand execRun() @trustedStarts execution of the debugged program.
MiPendingCommand execContinue() @trustedContinues execution.
MiPendingCommand execNext() @trustedExecutes the next line of source code, stepping over function calls.
MiPendingCommand execStep() @trustedExecutes the next line of source code, stepping into function calls.
MiPendingCommand execFinish() @trustedContinues execution until the current function returns.
MiPendingCommand execArguments(string[] args) @trustedSets the arguments for the next `-exec-run`.
MiPendingCommand inferiorTtySet(string tty) @trustedSets the TTY for the inferior.
MiPendingCommand inferiorTtyShow() @trustedShows the current TTY for the inferior.
MiPendingCommand execJump(string location) @trustedResumes execution at a different address.
MiPendingCommand execNextInstruction() @trustedExecutes the next instruction, stepping over function calls.
MiPendingCommand execStepInstruction() @trustedExecutes the next instruction, stepping into function calls.
MiPendingCommand execUntil(string location) @trustedContinues execution until a location is reached.
MiPendingCommand execSignal(string signal) @trustedResumes execution and sends an OS signal to the inferior.
MiPendingCommand execReturn(string value = null) @trustedMakes the current function return immediately.
GdbMiEngineMetadata getEngineMetadata() @trustedReturns metadata about the current debugger engine.
MiPendingCommand execInterrupt() @trustedInterrupts execution.
MiPendingCommand execReverseContinue() @trustedContinues execution in reverse.
MiPendingCommand execReverseNext() @trustedExecutes the previous line of source code, stepping over function calls.
MiPendingCommand execReverseStep() @trustedExecutes the previous line of source code, stepping into function calls.
MiPendingCommand execReverseFinish() @trustedExecutes in reverse until the current function was called.
MiPendingCommand checkpoint() @trustedCreates a checkpoint of the current state of the debugged program.
MiPendingCommand restart(int id) @trustedRestarts the program from a previously created checkpoint.
MiPendingCommand targetRecordFull() @trustedStarts recording for reverse debugging using the 'full' recording method.
MiPendingCommand targetRecordBTrace() @trustedStarts recording for reverse debugging using the 'btrace' recording method.
MiPendingCommand targetRecordStop() @trustedStops recording.
MiPendingCommand recordListFootprint() @trustedLists the footprint of the recording.
MiPendingCommand traceStart() @trustedStarts a tracing experiment.
MiPendingCommand traceStop() @trustedStops a tracing experiment.
MiPendingCommand traceStatus() @trustedQueries the status of a tracing experiment.
MiPendingCommand traceDefineVariable(string name, string value = null) @trustedDefines a trace variable.
MiPendingCommand traceListVariables() @trustedLists all trace variables and their values.
MiPendingCommand traceSave(string filename, bool remote = false) @trustedSaves trace data to a file.
MiPendingCommand traceFind(string mode, string[] extraArgs = null) @trustedFinds a trace frame.
MiPendingCommand targetListMemoryMap() @trustedLists the memory map of the target.
MiPendingCommand listTargetFeatures() @trustedLists features supported by the current target.
MiPendingCommand targetFlashErase() @trustedErases the flash memory on the target.
MiPendingCommand infoOs(string type = null) @trustedFetches OS-specific information.
string targetGetMemoryProtection(string address) @trustedTries to get memory protection for an address.
bool isReverseSupported() @trustedChecks if the current target supports reverse execution.
MiPendingCommand stackListFrames() @trustedLists stack frames.
MiPendingCommand stackListArguments() @trustedLists arguments for stack frames.
MiPendingCommand stackListLocals() @trustedLists local variables in the current frame.
MiPendingCommand stackListVariables(int printValues = 0) @trustedLists both locals and arguments for the current stack frame.
MiPendingCommand stackSelectFrame(int level) @trustedSelects a stack frame.
MiPendingCommand dataReadMemory(string address, char fmt, int wordSize, int rows, int cols) @trustedReads memory from the debugged process.
MiPendingCommand dataWriteMemory(string address, int wordSize, string value) @trustedWrites memory to the debugged process.
MiPendingCommand dataReadMemoryBytes(string address, size_t count) @trustedReads raw memory bytes.
MiPendingCommand dataWriteMemoryBytes(string address, const(ubyte)[] bytes) @trustedWrites raw memory bytes.
MiPendingCommand dataReadMemoryTag(string address) @trustedReads a memory tag.
MiPendingCommand dataWriteMemoryTag(string address, size_t count, int tagType, string[] tags) @trustedWrites a memory tag.
MiPendingCommand dataSearchMemory(string address, size_t length, string pattern) @trustedSearches memory for a pattern.
ubyte[] readMemory(string address, size_t count) @trustedReads raw memory into a buffer.
void writeMemory(string address, const(ubyte)[] bytes) @trustedWrites raw memory bytes from a buffer.
MiPendingCommand dataEvaluateExpression(string expr, string threadId = null, int frameLevel = - 1) @trustedEvaluates an expression.
MiValue[] dataEvaluateRange(string rangeExpr, int maxElements = 100) @trustedEvaluates a D range and returns its elements.
MiPendingCommand varCreate(string expression, string name = "-", string frame = "*") @trustedCreates a variable object.
MiPendingCommand varDelete(string name) @trustedDeletes a variable object.
MiPendingCommand varSetFormat(string name, string fmt) @trustedSets the output format for a variable object.
MiPendingCommand varShowAttributes(string name) @trustedShows attributes of a variable object.
MiPendingCommand varEvaluateExpression(string name) @trustedEvaluates the expression of a variable object.
MiPendingCommand varListChildren(string name) @trustedLists children of a variable object.
MiPendingCommand varInfoNumChildren(string name) @trustedReturns the number of children of a variable object.
MiPendingCommand varInfoType(string name) @trustedReturns the type of a variable object.
MiPendingCommand varInfoExpression(string name) @trustedReturns the expression used to create a variable object.
MiPendingCommand varInfoPathExpression(string name) @trustedReturns the path expression of a variable object.
MiPendingCommand varAssign(string name, string expression) @trustedAssigns a new value to a variable object.
MiPendingCommand varSetVisualizer(string name, string value) @trustedEnables or disables Python visualizers for a variable object.
MiPendingCommand varUpdate(string name = "*") @trustedUpdates variable objects.
MiPendingCommand fileExecAndSymbols(string file) @trustedLoads the target executable and its symbols.
MiPendingCommand fileListExecSourceFiles() @trustedGets a list of source files used to build the executable.
MiPendingCommand fileListSharedLibraries() @trustedLists shared libraries loaded by the target.
MiPendingCommand symbolListLines(string file) @trustedGets the mapping between source lines and addresses for a file.
MiPendingCommand symbolInfoModuleFunctions(string moduleRegex = null, string nameRegex = null) @trustedLists functions in a module.
MiPendingCommand symbolInfoModuleVariables(string moduleRegex = null, string nameRegex = null) @trustedLists variables in a module.
MiPendingCommand symbolInfoModules(string nameRegex = null) @trustedLists modules in the program.
MiPendingCommand symbolInfoFunctions(string name = null, bool details = false) @trustedSearches for information about functions.
MiPendingCommand symbolInfoVariables(string name = null, bool details = false) @trustedSearches for information about variables.
MiPendingCommand symbolInfoTypes(string name = null, bool details = false) @trustedSearches for information about types.
MiPendingCommand probeListAll() @trustedLists all available static probes.
MiPendingCommand dataListRegisterNames(int[] regnos = null) @trustedLists the names of available registers.
MiPendingCommand dataListRegisterValues(char fmt, int[] regnos = null) @trustedReads current register values.
MiPendingCommand dataWriteRegisterValues(char fmt, Tuple!(int, string)[] regnosValues) @trustedModifies register contents.
MiPendingCommand dataDisassemble(string startAddr, string endAddr, GdbMiDisassemblyMode mode) @trustedDisassembles a range of addresses.
MiPendingCommand dataDisassemble(string file, int line, int numLines, GdbMiDisassemblyMode mode) @trustedDisassembles a range of lines in a file.
MiPendingCommand targetAttach(int pid) @trustedAttaches to a running process.
MiPendingCommand targetDetach() @trustedDetaches from the target.
MiPendingCommand targetSetMemoryAttributes(string startAddress, string endAddress, string attributes) @trustedTries to set memory attributes for a range in GDB. See GDB 'mem' command documentation for details.
MiPendingCommand targetSelectRemote(string address) @trustedConnects to a remote target.
MiPendingCommand loadCoreFile(string exe, string core) @trustedLoads a core file for post-mortem debugging.
MiPendingCommand targetDownload() @trustedDownloads the executable to the remote target.
MiPendingCommand threadInfo(string threadId = null) @trustedLists information about threads.
MiPendingCommand threadListIds() @trustedLists IDs of all threads.
MiPendingCommand threadSelect(string threadId) @trustedSelects a thread as the current one.
MiPendingCommand listThreadGroups(bool available = false, string group = null) @trustedLists thread groups.
MiPendingCommand listOsThreads() @trustedLists OS-level threads for the current process.
MiPendingCommand listOsProcesses() @trustedLists the process tree from the OS perspective.
MiPendingCommand addInferior() @trustedAdds a new inferior process.
MiPendingCommand removeInferior(string inferior) @trustedRemoves an inferior process.
MiPendingCommand stackInfoFrame() @trustedGets information about the current stack frame.
MiPendingCommand stackInfoDepth(int maxDepth = - 1) @trustedGets the depth of the stack.
MiPendingCommand breakWatch(string expression, GdbMiWatchKind kind = GdbMiWatchKind.WRITE) @trustedInserts a watchpoint.
MiPendingCommand breakTrace(string location) @trustedInserts a tracepoint.
MiPendingCommand breakPasscount(int number, int passcount) @trustedSets the passcount for a breakpoint.
MiPendingCommand signalHandle(string signal, string[] actions) @trustedConfigures signal handling.
string currentThreadId() const @safe pure nothrow @nogcReturns: Current thread ID (may be null if unknown).
int currentFrameLevel() const @safe pure nothrow @nogcReturns: Current frame level.
void onEvent(void delegate(GdbMiEvent) listener) @safeRegisters an event listener.
void onStopped(void delegate(MiAsyncRecord) listener) @safeRegisters a listener for 'stopped' events.
void onThreadCreated(void delegate(MiAsyncRecord) listener) @safeRegisters a listener for 'thread-created' events.
MiPendingCommand gdbSet(string name, string value) @trustedSets a GDB setting.
MiPendingCommand gdbShow(string name) @trustedShows a GDB setting.
MiPendingCommand setSolibSearchPath(string path) @trustedSets the shared library search path.
MiPendingCommand environmentDirectory(string[] directories, bool reset = false) @trustedAdds directories to the source file search path.
MiPendingCommand environmentCd(string directory) @trustedChanges the working directory of GDB (and the inferior).
MiPendingCommand setSubstitutePath(string from, string to) @trustedSets a source path substitution rule.
MiPendingCommand setPrintPretty(bool enabled) @trustedEnables or disables pretty printing.
MiPendingCommand enablePrettyPrinting() @trustedEnables MI pretty printing for variable objects.
MiPendingCommand pythonExecute(string command) @trustedExecutes a Python command in GDB.
MiPendingCommand listPrettyPrinters() @trustedLists registered pretty-printers.
bool tryPopEvent(out GdbMiEvent ev) @trustedTries to pop one event without blocking.
auto popEvent(Duration timeout = DEFAULT_EVENT_TIMEOUT) @trustedPops one event, blocking until an event arrives or timeout expires.
void enqueueEvent(GdbMiEvent ev) @trustedEnqueues one parsed/decoded event and wakes any waiter.
void compactEvents() @trustedCompacts the event queue when the consumed head exceeds a threshold.
void logShutdownError(string context, Exception e) @trustedLogs a shutdown/cleanup error through the configured logger if available.
bool shouldLog(string rawLine, bool isOutgoing) @safeChecks if a line should be logged based on configuration.
void commandSenderLoop() @trustedBlocking loop for sending commands with throttling and priority.
void stdoutLoop() @trustedBlocking reader loop for GDB stdout (MI output stream).
void stderrLoop() @trustedBlocking reader loop for GDB stderr.
void handleParsedLine(string raw, MiRecord rec) @trustedRoutes a parsed stdout line to either the pending-command map or the event queue.
void failAllPending(Throwable t) @trustedFails and releases all currently pending commands.
Constructors
this(GdbMiConfig config = GdbMiConfig.init)Spawns GDB in MI mode.
classGdbMiVariable

High-level wrapper for a GDB variable object.

This class manages the lifecycle of a variable object created via -var-create. It provides ergonomic methods for updating and querying the variable state.

Fields
GdbMiSession _session
string _name
string _expression
string _type
int _numChildren
Methods
string name() const @safe pure nothrow @nogcReturns: The variable object name.
string expression() const @safe pure nothrow @nogcReturns: The original expression.
string type() const @safe pure nothrow @nogcReturns: The variable type.
int numChildren() const @safe pure nothrow @nogcReturns: Number of children.
MiPendingCommand update() @trustedUpdates this variable object.
MiPendingCommand listChildren() @trustedLists children of this variable object.
MiPendingCommand evaluate() @trustedEvaluates the expression of this variable object.
MiPendingCommand setFormat(string format) @trustedSets the output format for this variable object.
MiPendingCommand delete_() @trustedDeletes this variable object.
Constructors
this(GdbMiSession session, string name, string expression, string type, int numChildren)Creates a variable object wrapper.
private structMiParser
Fields
const(char)[] _s
size_t _i
Methods
bool eof() const @safe pure nothrow @nogcReturns: `true` if end of input was reached.
char peek() const @safeReturns: Current character. Throws: `GdbMiParseException` on EOF.
char get() @safeConsumes and returns one character. Throws: `GdbMiParseException` on EOF.
void ensureEof() @safeEnsures parser is at EOF.
MiToken parseToken() @safeParses an optional token (leading digits).
const(char)[] parseIdentifier() @safeParses an MI identifier.
MiResult[] parseOptionalResults() @safeParses zero or more results preceded by commas.
MiResult parseResult() @safeParses a single result.
MiValue parseValue() @safeParses any MI value.
MiTuple parseTuple() @safeParses an MI tuple.
MiList parseList() @safeParses an MI list.
string parseCString() @safeParses an MI C-string and returns decoded text.
GdbMiParseException parserError(string expected) @safeBuilds a `GdbMiParseException` at the current parser position.
bool looksLikeResult() @safe pure nothrow @nogcReturns: `true` if the remaining input looks like a `name=value` pair.
bool isIdentStart(char c) @safe pure nothrow @nogcReturns: `true` if `c` can start an MI identifier.
bool isIdentContinue(char c) @safe pure nothrow @nogcReturns: `true` if `c` can continue an MI identifier.
Constructors
this(const(char)[] s)Creates a parser.

Functions 18

fnMiValue findResult(scope MiResult[] results, string variable) @safeFinds the first result with the given variable name.
fnMiValue requireResult(scope MiResult[] results, string variable) @safeReturns the result value for a variable name, throwing if not present.
fnstring demangleDSymbol(string name) @safeDemangles a D symbol if it is mangled.
fnbool isResult(scope MiRecord rec) @trustedReturns: `true` if the record is a result record.
fnbool isAsync(scope MiRecord rec) @trustedReturns: `true` if the record is an async record.
fnbool isStream(scope MiRecord rec) @trustedReturns: `true` if the record is a stream record.
fnGdbMiInstruction[] parseInstructions(MiValue val) @safeParses a list of instructions from an MI value.
fnGdbMiEngineMetadata parseGdbVersion(string output) @safeParses GDB version output.
fnDTypeInfo parseDType(string typeStr)Parses a D type string and extracts qualifiers.
fnDubProjectInfo parseDubProject(string projectPath) @trustedParses DUB project information using 'dub describe'.
fnbool debuggerAvailable(string debuggerPath) @safeReturns: `true` if `debuggerPath` looks runnable.
fnMiRecord parseMiRecord(const(char)[] line) @trustedParses a single MI output line.
private fnMiStreamKind parseStreamKind(char c) @safe pure nothrow @nogcConverts an MI stream-record prefix character to `MiStreamKind`.
private fnMiAsyncKind parseAsyncKind(char c) @safe pure nothrow @nogcConverts an MI async-record prefix character to `MiAsyncKind`.
fnstring escapeMiCString(string text) @safeEscapes a string as an MI C-string literal content (without surrounding quotes).
fnstring quoteMiArg(string text) @safeQuotes a string as an MI argument (C-string with surrounding quotes).
fnstring buildTestExecutable(string[] sourcePaths) @safeCompiles D source files to an executable for use in integration tests.
fnstring buildTestExecutable(string sourcePath) @safeCompiles a single D source file to an executable for use in integration tests.

Variables 3

enumvarDEFAULT_COMMAND_TIMEOUT = dur!"seconds"(10)

Default timeout for MI command completion (MiPendingCommand.wait()).

Ten seconds balances responsiveness against slow debuggee startup and symbol loading on large projects.

enumvarDEFAULT_EVENT_TIMEOUT = dur!"seconds"(1)

Default timeout for event polling (GdbMiSession.popEvent()).

One second is a reasonable upper bound for event polling in an interactive application; callers that need longer waits should pass an explicit timeout.

varstring[string] _debuggerAvailableCache