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 -&gt; NameSpace.Values.value
34     <strong>val</strong> debugLocation: debugState -> location
35     <strong>val</strong> debugNameSpace: debugState -> NameSpace.nameSpace
36     <strong>val</strong> debugLocalNameSpace: debugState -&gt; 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