Changeset: 8acd8078b552 for MonetDB
URL: http://dev.monetdb.org/hg/MonetDB?cmd=changeset;node=8acd8078b552
Modified Files:
monetdb5/mal/mal_debugger.mx
Branch: default
Log Message:
Remove documentation text
diffs (truncated from 592 to 300 lines):
diff --git a/monetdb5/mal/mal_debugger.mx b/monetdb5/mal/mal_debugger.mx
--- a/monetdb5/mal/mal_debugger.mx
+++ b/monetdb5/mal/mal_debugger.mx
@@ -20,436 +20,7 @@ All Rights Reserved.
@c
/*
* @a M.L. Kersten
- * @* The MAL Debugger
- *
- * In practice it is hard to write a correct MAL program the
- * first time around. Instead, it is more often constructed by
- * trial-and-error. As long as there are syntax and semantic errors
- * the MAL compiler provides a sufficient handle to proceed. Once
- * it passes the compiler we have to resort to a debugger to
- * assess its behavior.
- *
- * Note, the MAL debugger described here can be used in conjunction
- * with the textual interface client @emph{mclient} only.
- * The JDBC protocol does not permit passing through information that
- * 'violates' the protocol.
- * @menu
- * * Program Debugging ::
- * * Handling Breakpoints::
- * * Profile Switches::
- * * Program Inspection::
- * * Runtime Inspection::
- * * Debugger Attachment::
- * @end menu
- * @node Program Debugging, Handling Breakpoints, The MAL Debugger, The MAL
Debugger
- * @+ Program Debugging
- * To ease debugging and performance monitoring, the MAL interpreter
- * comes with a gdb-like debugger.
- * An illustrative session elicits the functionality offered.
- *
- * @example
- * mal>function test(i:int):str;
- * mal> io.print(i);
- * mal> i:= i*2;
- * mal> b:= bat.new(:int,:int);
- * mal> bat.insert(b,1,i);
- * mal> io.print(b);
- * mal> return test:= "ok";
- * mal>end test;
- * mal>user.test(1);
- * [ 1 ]
- * #-----------------#
- * # h t # name
- * # int int # type
- * #-----------------#
- * [ 1, 2 ]
- * @end example
- *
- * The debugger can be entered at any time using the call mdb.start().
- * An overview of the available commands is readily available.
- * @example
- * mal>mdb.start();
- * #mdb !end main;
- * mdb>help
- * next -- Advance to next statement
- * continue -- Continue program being debugged
- * catch -- Catch the next exception
- * break [<var>] -- set breakpoint on instruction <var>
- * break [#] -- set breakpoint on instruction #
- * delete [<var>] -- remove break/trace point # or <var>
- * debug <int> -- set kernel debugging mask
- * dot <obj> [<file>] -- generate the dependency graph
- * step -- advance to next MAL instruction
- * module -- display a module signatures
- * atom -- show atom list
- * finish -- finish current call
- * exit -- terminate executionr
- * quit -- turn off debugging
- * list <obj> -- list current program block
- * list # [+#, -#] -- list current program slice
- * List <obj> [#] -- list with type information (slice)
- * List # [+#, -#] -- list current program slice
- * span -- list the life span of variables
- * var <obj> -- print symbol table for module
- * optimizer <obj> -- display optimizer steps
- * print <var> -- display value of a variable
- * print <var> <cnt>[<first>] -- display BAT chunk
- * info <var> -- display bat variable properties
- * run -- restart current procedure
- * where -- print stack trace
- * down -- go down the stack
- * up -- go up the stack
- * trace <var> -- trace assignment to variables
- * trap <mod>.<fcn> -- catch MAL function call in console
- * set @verb{ { },timer,thread,flow,io,memory,bbp,bigfoot@verb{ } } -- set
trace switches
- * unset -- turn off switches
- * help -- this message
- * mdb>
- * @end example
- *
- * The term @sc{<obj>} is an abbreviation for a
- * MAL operation @sc{<mod>.<fcn>}, optionally extended with
- * a version number, i.e. @sc{[<nr>]}.
- * The @sc{var} denotes a variable in the current stack frame.
- * Debugger commands may be abbreviated.
- *
- * We walk our way through a debugging session, highlighting the
- * effects of the debugger commands.
- * The call to mdb.start() has been encapsulated in a complete
- * MAL function, as shown by issuing the list command.
- * A more detailed listing shows the binding to the C-routine
- * and the result of type resolution.
- * @example
- * mal>mdb.start();
- * #end main;
- * mdb>l 0
- * # 0 function user.main():int;
- * # 1 mdb.start();
- * # 2 end main;
- * mdb>L 0
- * # 0 function user.main():int; # 0 (main:int)
- * # 1 mdb.start(); # 1 MDBstart (_1:void)
- * # 2 end main; # 2
- * @end example
- * The list command has an optional instruction counter argument,
- * followed by optional +# or -# arguments.
- * The user module is the default place for function defined at
- * the console. The modules loaded can be shown typeing the
- * command 'module' (or 'm' for short).
- * The function signatures become visible using the module and optionally
- * the function name.
- * @example
- * mdb>m alarm
- * #command alarm.alarm(secs:int,action:str):void address ALARMsetalarm;
- * #command alarm.ctime():str address ALARMctime;
- * #command alarm.epilogue():void address ALARMepilogue;
- * #command alarm.epoch():int address ALARMepoch;
- * #command alarm.prelude():void address ALARMprelude;
- * #command alarm.sleep(secs:int):void address ALARMsleep;
- * #command alarm.time():int address ALARMtime;
- * #command alarm.timers():bat[:str,:str] address ALARMtimers;
- * #command alarm.usec():lng address ALARMusec;
- * mdb>m alarm.sleep
- * #command alarm.sleep(secs:int):void address ALARMsleep;
- * mdb>
- * @end example
- * The debugger mode is left with a <return>.
- * Any subsequent MAL instruction re-activates the debugger to
- * await for commands. The default operation is to step through
- * the execution using the 'next' ('n') or 'step' ('s) commands,
- * as shown below.
- * @example
- * mal>user.test(1);
- * # user.test(1);
- * mdb>n
- * # io.print(i);
- * mdb>
- * [ 1 ]
- * # i := calc.*(i,2);
- * mdb>
- * # b := bat.new(:int,:int);
- * mdb>
- * @end example
- * The last instruction shown is next to be executed. The result can be
- * shown using a print statement, which contains the location of
- * the variable on the stack frame, its name, its value and type.
- * The complete stack frame becomes visible with 'values' ('v')
- * command:
- * @example
- * # bat.insert(b,1,i);
- * mdb>
- * # io.print(b);
- * mdb>v
- * #Stack for 'test' size=32 top=11
- * #[0] test = nil:str
- * #[1] i = 4:int
- * #[2] _2 = 0:int unused
- * #[3] _3 = 2:int constant
- * #[4] b = <tmp_1226>:bat[:int,:int] count=1 lrefs=1 refs=0
- * #[5] _5 = 0:int type variable
- * #[6] _6 = nil:bat[:int,:int] unused
- * #[7] _7 = 1:int constant
- * #[8] _8 = 0:int unused
- * #[9] _9 = "ok":str constant
- * @end example
- * The variables marked 'unused' have been introduced as temporary variables,
- * but which are not referenced in the remainder of the program.
- * It also illustrates basic BAT properties, a complete description of which
- * can be obtained using the 'info' ('i') command.
- * A sample of the BAT content can be printed passing tuple indices, e.g.
- * 'print b 10 10' prints the second batch of ten tuples.
- *
- * @node Handling Breakpoints, Profile Switches, Program Debugging, The MAL
Debugger
- * @+ Handling Breakpoints
- * A powerful mechanism for debugging a program is to set breakpoints
- * during the debugging session.
- * The breakpoints are designated by a target variable name,
- * a [module.]function name, or a MAL line number (#<number>).
- *
- * The snippet below illustrates the reaction to set a break point
- * on assignment to variable 'i'.
- * @example
- * mal>mdb.start();
- * #end main;
- * mdb>
- * mal>user.test(1);
- * # user.test(1);
- * mdb>break i
- * breakpoint on 'i' not set
- * mdb>n
- * # io.print(i);
- * mdb>break i
- * mdb>c
- * [ 1 ]
- * # i := calc.*(i,2);
- * mdb>
- * @end example
- *
- * The breakpoints remain in effect over multiple function calls.
- * They can be removed with the @sc{delete} statement.
- * A list of all remaining breakpoints is obtained with @sc{breakpoints}.
- *
- * The interpreter can be instructed to call the debugger as soon as an
exception
- * is raised. Simply add the instruction @sc{mdb.setCatch(true)}.
- *
- * @node Profile Switches, Program Inspection, Handling Breakpoints, The MAL
Debugger
- * @+ Profile Switches
- * Switches control the level of detail output shown while debugging
- * or tracing program execution.
- * They are toggled with the @sc{set} and @sc{unset} command.
- * The following switches are currently supported:
- * @table @sc
- * @item timer
- * activates a listing of all instructions being executed.
- * It is measured in wall-clock time.
- * @item flow
- * shows the total byte size of all BAT target results and input arguments.
- * It is a good indicator on the amount of data being processed.
- * @item memory
- * keeps track on growing memory needs.
- * @item io
- * keeps track on the amount of physical IO
- * and is used to detect operators consuming excessive amounts of space.
- * @item bigfoot
- * keeps track of the current and maximum virtual memory footprint
- * of the BATs.[incomplete]
- * @end table
- *
- * The snippet below shows setting the @sc{memory} and @sc{timer}
- * switch. The switches take effect at the next instruction.
- * @example
- * mdb>set timer
- * mdb>set flow
- * mdb>c
- * [ 3 ]
- * # 26 usec# 0 0# io.print(i=3)
- * # 6 usec# 0 0# i := calc.*(i=6, _3=2)
- * # 10 usec# 0 0# b := bat.new(_5=0, _6=0)
- * # 7 usec# 0 8# bat.insert(b=<tmp_167>bat[:int,:int]@verb{ {
}1@verb{ } }, _8=1, i=6)
- * #-----------------#
- * # h t # name
- * # int int # type
- * #-----------------#
- * [ 1, 6 ]
- * # 41 usec# 0 8# io.print(b=<tmp_167>bat[:int,:int]@verb{ {
}1@verb{ } })
- * # 7 usec# 0 0# return test := "ok";
- * # 211 usec# 0 0# user.test(_2=3)
- *
- * @end example
- * @node Program Inspection, Runtime Inspection, Profile Switches, The MAL
Debugger
- * @+ Program Inspection
- * The debugger commands available for inspection of the program and
- * symbol tables are:
- * @table @sc
- * @item list (List) [<mod>.<fcn>['['<nr>']']]
- * A listing of the current MAL block, or one designated
- * by the <mod>.<fcn> is produced.
- * The @sc{[<nr>]} extension provides access to an element
- * in the MAL block history.
- * The alternative name 'List' also produces the type information.
- * @item optimizer [<mod>.<fcn>['['<nr>']']]
- * Gives an overview of the optimizer actions in the history of the MAL block.
- * Intermediate results can be accessed using the list command.
- * @item atoms
- * Lists the atoms currently known
- * @item modules [<mod>]
- * Lists the modules currently known. An optional <mod> argument
- * produces a list of all signatures within the module identified.
- * @item dot <mod>.<fcn>['['<nr>']'] [<file>]
- * A dataflow diagram can be produced using the @sc{dot} command.
- * It expects a function identifier with an optional history index
- * and produces a file for the Linux program @sc{dot},
- * which can produce a nice, multi-page graph to illustrate plan
- * complexity.
- * @end table
- *
- * @example
- * mdb>dot user.main
- * @end example
- * This example produces the @sc{user.main.dot} in the current
- * working directory. The program call
- * @example
- * dot -Tpdf user-tst-0.dot -o user-tst-0.pdf
- * @end example
- * creates a PDF file with the graphs. The Linux pdfposter utility can be used
to
- * produce a proper printing. Alternatively, the Adobe reader professional
_______________________________________________
Checkin-list mailing list
[email protected]
http://mail.monetdb.org/mailman/listinfo/checkin-list
