Skip to main content

Debugger

8.13 MAL debugger interface

This module provides access to the functionality offered by the MonetDB debugger and interpreter status. It is primarilly 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 start():void
address MDBstart
comment "Start interactive debugger";
pattern start(clientid:int):void
address MDBstart
comment "Start interactive debugger on a client";
pattern start(mod:str,fcn:str):void
address MDBstartFactory
comment "Start interactive debugger on a running factory";

pattern stop():void
address MDBstop
comment "Stop the interactive debugger.";

pattern inspect(mod:str,fcn:str):void
address MDBinspect
comment "Run the debugger on a specific function";

command modules():bat[:oid,:str]
address CMDmodules
comment "List available modules";

pattern setTrap(mod:str, fcn:str, b:bit):void
address MDBtrapFunction
comment "Suspend upon a call to the MAL function.";

pattern setTrap(idx:int):void
address mdbTrapClient
comment "Call debugger for a specific process.";

pattern setTrace(b:bit):void
address MDBsetTrace
comment "Turn on/off tracing of current routine";

pattern setTrace(b:str):void
address MDBsetVarTrace
comment "Turn on/off tracing of a variable ";

pattern setCatch(b:bit):void
address MDBsetCatch
comment "Turn on/off catching exceptions";

command getDebug():int
address MDBgetDebug
comment "Get the kernel debugging bit-set. See the MonetDB configuration file for details";

command setDebug(flg:str):int
address MDBsetDebugStr
comment "Set the kernel debugging bit-set and return its previous value. The recognized options are: threads, memory, properties,
io, transactions, modules, algorithms, estimates.";
command setDebug(flg:int):int
address MDBsetDebug
comment "Set the kernel debugging bit-set and return its previous value.";

command getException(s:str):str
address MDBgetExceptionVariable
comment "Extract the variable name from the exception message";
command getReason(s:str):str
address MDBgetExceptionReason
comment "Extract the reason from the exception message";
command getContext(s:str):str
address MDBgetExceptionContext
comment "Extract the context string from the exception message";

pattern list():void
address MDBlist
comment "Dump the current routine on standard out.";
pattern listMapi():void
address MDBlistMapi
comment "Dump the current routine on standard out with Mapi prefix.";
pattern list(M:str,F:str):void
address MDBlist3
comment "Dump the routine M.F on standard out.";
pattern List():void
address MDBlistDetail
comment "Dump the current routine on standard out.";
pattern List(M:str,F:str):void
address MDBlist3Detail
comment "Dump the routine M.F on standard out.";
pattern var():void
address MDBvar
comment "Dump the symboltable of current routine on standard out.";
pattern var(M:str,F:str):void
address MDBvar3
comment "Dump the symboltable of routine M.F on standard out.";
pattern lifespan(M:str,F:str):void
address MDBlifespan
comment "Dump the current routine lifespan information on standard out.";

pattern grab():void
address mdbGrab
comment "Call debugger for a suspended process.";
pattern trap():void
address mdbTrap
comment "A suspended process for debugging.";

pattern dot(s:str):void
address MDBshowFlowGraph
comment "Dump the data flow of the current routine in a format recognizable by the command 'dot' to the file s";

pattern dot(M:str,F:str,s:str):void
address MDBshowFlowGraph
comment "Dump the data flow of the function M.F in a format recognizable by the command 'dot' on the file s";

pattern getStackDepth():int
address MDBStkDepth
comment "Return the depth of the calling stack.";

pattern getStackFrame(i:int)(:bat[:oid,:str] ,:bat[:oid,:str])
address MDBgetStackFrameN;
pattern getStackFrame()(:bat[:oid,:str] ,:bat[:oid,:str])
address MDBgetStackFrame
comment "Collect variable binding of current (n-th) stack frame.";
pattern getStackTrace()(:bat[:oid,:str], :bat[:oid,:str])
address MDBStkTrace;

pattern dump()
address MDBdump
comment "Dump instruction, stacktrace, and stack";

pattern getDefinition():bat[:oid,:str]
address MDBgetDefinition
comment "Returns a string representation of the current function with typing information attached";