Debugger

This module provides access to the functionality offered by the MonetDB debugger and interpreter status. It is primarily used in interactive sessions to activate the debugger at a given point. Furthermore, the instructions provide the necessary handle to generate information for post-mortum analysis.

To enable ease of debugging and performance monitoring, the MAL interpreter comes with a hardwired gdb-like text-based debugger. A limited set of instructions can be included in the programs themselves, but beware that debugging has a global effect. Any concurrent user will be affected by breakpoints being set.

The prime scheme to inspect the MAL interpreter status is to use the MAL debugger directly. However, in case of automatic exception handling it helps to be able to obtain BAT versions of the critical information, such as stack frame table, stack trace, and the instruction(s) where an exception occurred. The inspection typically occurs in the exception handling part of the MAL block.

Beware, a large class of internal errors can not easily captured this way. For example, bus-errors and segmentation faults lead to premature termination of the process. Similar, creation of the post-mortum information may fail due to an inconsistent state or insufficient resources.

MODULE mdb;

PATTERN mdb.List(X_0:str, X_1:str):void;
COMMENT "Dump the routine M.F on standard out.";

PATTERN mdb.List():void;
COMMENT "Dump the current routine on standard out.";

PATTERN mdb.dump():void;
COMMENT "Dump instruction, stacktrace, and stack";

COMMAND mdb.getContext(X_0:str):str;
COMMENT "Extract the context string from the exception message";

PATTERN mdb.getDebug():int;
COMMENT "Get the kernel debugging bit-set.\nSee the MonetDB configuration file for details";

PATTERN mdb.getDebugFlags() (X_0:bat[:str], X_1:bat[:bit]);
COMMENT "Get the kernel debugging flags bit-set";

PATTERN mdb.getDefinition():bat[:str];
COMMENT "Returns a string representation of the current function \nwith typing information attached";

COMMAND mdb.getException(X_0:str):str;
COMMENT "Extract the variable name from the exception message";

COMMAND mdb.getReason(X_0:str):str;
COMMENT "Extract the reason from the exception message";

PATTERN mdb.getStackDepth():int;
COMMENT "Return the depth of the calling stack.";

PATTERN mdb.getStackFrame() (X_0:bat[:str], X_1:bat[:str]);
COMMENT "Collect variable binding of current (n-th) stack frame.";

PATTERN mdb.getStackFrame(X_0:int) (X_1:bat[:str], X_2:bat[:str]);
COMMENT "";

PATTERN mdb.getStackTrace() (X_0:bat[:int], X_1:bat[:str]);
COMMENT "";

PATTERN mdb.getVMsize():lng;
COMMENT "Retrieve the max VM size";

PATTERN mdb.inspect(X_0:str, X_1:str):void;
COMMENT "Run the debugger on a specific function";

PATTERN mdb.list(X_0:str, X_1:str):void;
COMMENT "Dump the routine M.F on standard out.";

PATTERN mdb.list():void;
COMMENT "Dump the current routine on standard out.";

PATTERN mdb.listMapi():void;
COMMENT "Dump the current routine on standard out with Mapi prefix.";

COMMAND mdb.modules():bat[:str];
COMMENT "List available modules";

PATTERN mdb.setCatch(X_0:bit):void;
COMMENT "Turn on/off catching exceptions";

PATTERN mdb.setDebug(X_0:int):int;
COMMENT "Set the kernel debugging bit-set and return its previous value.";

PATTERN mdb.setDebug(X_0:str):int;
COMMENT "Set the kernel debugging bit-set and return its previous value.\nThe recognized options are: threads, memory, properties,\nio, transactions, modules, algorithms, estimates.";

PATTERN mdb.setTrace(X_0:bit):void;
COMMENT "Turn on/off tracing of current routine";

PATTERN mdb.setTrace(X_0:str):void;
COMMENT "Turn on/off tracing of a variable";

PATTERN mdb.setVMsize(X_0:lng):lng;
COMMENT "Manipulate the VM max size in MBs";

PATTERN mdb.start():void;
COMMENT "Start interactive debugger";

PATTERN mdb.start(X_0:int):void;
COMMENT "Start interactive debugger on a client";

PATTERN mdb.start(X_0:str, X_1:str):void;
COMMENT "Start interactive debugger on a running factory";

PATTERN mdb.stop():void;
COMMENT "Stop the interactive debugger";

PATTERN mdb.var(X_0:str, X_1:str):void;
COMMENT "Dump the symboltable of routine M.F on standard out.";

PATTERN mdb.var():void;
COMMENT "Dump the symboltable of current routine on standard out.";