1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> 2<html> 3<head> 4<title>The PolyML.DebuggerInterface structure</title> 5<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> 6<link href="docstyle.css" rel="stylesheet" type="text/css"> 7</head> 8 9<body> 10<ul class="nav"> 11 <li><a href="PolyMLDebug.html">Previous</a></li> 12 <li><a href="PolyMLStructure.html">Up</a></li> 13 <li><a href="PolyMLException.html">Next</a></li> 14</ul> 15<H2><STRONG><font face="Arial, Helvetica, sans-serif">The PolyML.DebuggerInterface 16 structure</font></STRONG></H2> 17<p>The PolyML.DebuggerInterface structure provides a programmatic interface to 18 assist with debugging programs. It is intended for use by applications that 19 replace the default Poly/ML top-level. Most users will not need to use this 20 and for most purposes the functions in <a href="../Tutorials/Debugging.html">PolyML.Debug</a> 21 will be more appropriate.</p> 22<PRE class="mainsig"><STRONG>structure</STRONG> DebuggerInterface: 23 <strong>sig</strong> 24 <strong>val</strong> setOnEntry: (string * location -> unit) option -> unit 25 <strong>val</strong> setOnExit: (string * location -> unit) option -> unit 26 <strong>val</strong> setOnExitException: (string * location -> exn -> unit) option -> unit 27 <strong>val</strong> setOnBreakPoint: (location * bool ref -> unit) option -> unit 28 29 <strong>type</strong> debugState 30 <strong>val</strong> debugState: Thread.Thread.thread -> debugState list 31 <strong>val</strong> debugFunction: debugState -> string 32 <strong>val</strong> debugFunctionArg: debugState -> NameSpace.Values.value 33 <strong>val</strong> debugFunctionResult: debugState -> NameSpace.Values.value 34 <strong>val</strong> debugLocation: debugState -> location 35 <strong>val</strong> debugNameSpace: debugState -> NameSpace.nameSpace 36 <strong>val</strong> debugLocalNameSpace: debugState -> NameSpace.nameSpace 37 <strong>end</strong></PRE> 38<p>The Poly/ML compiler will add debugging information to a program if <span class="identifier">PolyML.Compiler.debug</span> 39 is set to <span class="identifier">true</span> or <span class="identifier">CPDebug</span> 40 <span class="identifier">true</span> is included among the options. By default, 41 these options are turned off because using them greatly reduces the speed of 42 the code and in particular optimisations such as tail-recursion are disabled. 43 When debugging is enabled the compiler adds code to allow the debugger to be 44 entered at various points and for the debugger then to extract information about 45 the state of the program being debugged, the <em>debuggee</em>. </p> 46<p>There are four global references that can be set by the debugger. Each of them 47 holds an optional function and the code being debugged tests these references 48 at various points in the program and calls the function if it is set.</p> 49<div class="entryblock"><pre class="entrycode"><strong>val</strong> setOnEntry: (string * location -> unit) option -> unit</pre> 50<div class="entrytext"> 51 <p>The function set with <span class="identifier">setOnEntry</span> is called 52 at the start of every function. This function is called with the name of 53 the function and its location. It is called after the argument information 54 has been added to the debug state but before anything else.</p> 55</div> 56</div><div class="entryblock"><pre class="entrycode"><strong>val</strong> setOnExit: (string * location -> unit) option -> unit</pre> 57<div class="entrytext"> 58 <p>The function set with <span class="identifier">setOnExit</span> is called 59 at the end of every function if it returns a result. This function is called 60 with the name of the function and its location. It is called after the function 61 result has been added to the debug state.</p> 62</div></div> 63<div class="entryblock"><pre class="entrycode"><strong>val</strong> setOnExitException: (string * location -> exn -> unit) option -> unit</pre> 64<div class="entrytext"> 65 <p>The function set with <span class="identifier">setOnExitException</span> 66 is called at the end of every function if it is returning by raising an 67 exception. This function is called with the name of the function and its 68 location and with the exception packet being returned.</p> 69</div> 70</div> 71<div class="entryblock"><pre class="entrycode"><strong>val</strong> setOnBreakPoint: (location * bool ref -> unit) option -> unit</pre> 72<div class="entrytext"> 73 <p>The function set with <span class="identifier">setOnBreakPoint</span> is 74 called at various <em>break-points</em> within the function. Currently the 75 compiler inserts break-points at the beginning of the expression in a <em>match</em>, 76 i.e. after the pattern has been discriminated and any variable bindings 77 have been made; after each value declaration; after each expression separated 78 by semicolons in let-expressions or parenthesised sequence of expressions; 79 at the beginning of the then- and else-parts of an if-then-else and at the 80 start of the body of a while-expression.</p> 81 <p>The function is called with two arguments: the location of the break-point 82 and a <em>break-point identifier</em>, a boolean reference. Break-point 83 identifiers are intended for use with an IDE that is capable of examining 84 the parse-tree. A node in the parse-tree with a break-point associated with 85 it will contain a <span class="identifier"><a href="PolyMLStructure.html#PTbreakPoint">PTbreakPoint</a></span> 86 property. All break-point identifiers are initially false. To set a break-point 87 at a particular node the IDE should set the reference to true and install 88 a break-point function that calls the debugger when it is passed a reference 89 that is true.</p> 90 <p>All functions are called by the thread that is running the program being 91 debugged. All the functions return unit and if they return normally the 92 program will continue as before. It is possible for the function to raise 93 an exception in which case this exception will be raised in place of any 94 existing exception. This can sometimes be useful to terminate the program. 95 Installing any function will add an overhead to the running program. It 96 is better to set a function option to <span class="identifier">NONE</span> 97 if it is not actually required.</p> 98<p>When debugging is enabled the running program maintains information about local 99 variables that can be examined when the program has stopped by calling in to 100 the debugger.</p> 101</div> 102</div> 103<div class="entryblock"><pre class="entrycode"><strong>type</strong> debugState 104<strong>val</strong> debugState: Thread.Thread.thread -> debugState list 105</pre> 106<div class="entrytext"> 107 <p>The stack of a debuggable thread can be extracted using the <span class="identifier">debugState</span> 108 function. This should either be called by the thread itself or by the debugger 109 after the thread has been paused with a condition variable. Extracting the 110 debugging state of another thread while the thread is running will lead 111 to unpredictable results. </p> 112</div> 113</div> 114<div class="entryblock"><pre class="entrycode"><strong>val</strong> debugFunction: debugState -> string 115<strong>val</strong> debugFunctionArg: debugState -> PolyML.NameSpace.valueVal 116<strong>val</strong> debugFunctionResult: debugState -> PolyML.NameSpace.valueVal 117</pre> 118<div class="entrytext"> 119 <p>Each node in the state list normally represents a function. These return 120 the name of the function, its argument and its result. The result is only 121 available in an exit function.</p> 122</div> 123 <pre class="entrycode"><strong><a name="debugLocation"></a>val</strong> debugLocation: debugState -> location</pre> 124 <div class="entrytext"> 125 <p>This function returns the location associated with a node in the list. This 126 will either be the location of the break-point or where the function has called 127 the next function in the list.</p> 128</div> 129</div> 130<div class="entryblock"><pre class="entrycode"> 131<strong>val</strong> debugNameSpace: debugState -> nameSpace</pre> 132<div class="entrytext"> 133 <p>Access to the local variables can be obtained through the name-space. A name-space 134 is a record of functions that can be used to look up variables and list the 135 variables. In the general case it can also be used to add variables to the 136 name space but that is not appropriate here and the enter functions all raise 137 an exception. The name space can be used directly to print the values of variables 138 using functions from PolyML.NameSpace. Alternatively the name-space can be 139 used with the Poly/ML compiler to provide an interactive top-level in which 140 the user can enter expressions to be evaluated with local variables as though 141 they had been declared at the top-level. When paused at a break-point it is 142 possible to evaluate local functions as though they were global. Any changes 143 to local reference values will affect the program state when the program resumes.</p> 144 <p>Currently, the name space contains all the variables that were in scope at 145 the break-point, both those local to the function itself and free variables 146 declared in outer scopes. It excludes any variables that were declared in 147 the outer top-level scope.</p> 148</div> 149</div> 150<ul class="nav"> 151 <li><a href="PolyMLDebug.html">Previous</a></li> 152 <li><a href="PolyMLStructure.html">Up</a></li> 153 <li><a href="PolyMLException.html">Next</a></li> 154</ul> 155</body> 156</html> 157