Commit | Line | Data |
---|---|---|
07d83abe MV |
1 | @c -*-texinfo-*- |
2 | @c This is part of the GNU Guile Reference Manual. | |
994d87be | 3 | @c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2007, 2010, 2011, 2012, 2013 |
07d83abe MV |
4 | @c Free Software Foundation, Inc. |
5 | @c See the file guile.texi for copying conditions. | |
6 | ||
07d83abe MV |
7 | @node Debugging |
8 | @section Debugging Infrastructure | |
9 | ||
b20ef3a6 | 10 | @cindex Debugging |
5af872e1 | 11 | In order to understand Guile's debugging facilities, you first need to |
42cb9b03 | 12 | understand a little about how Guile represent the Scheme control stack. |
a1652dec AW |
13 | With that in place we explain the low level trap calls that the virtual |
14 | machine can be configured to make, and the trap and breakpoint | |
5af872e1 NJ |
15 | infrastructure that builds on top of those calls. |
16 | ||
07d83abe | 17 | @menu |
5af872e1 | 18 | * Evaluation Model:: Evaluation and the Scheme stack. |
5db7c0bf | 19 | * Source Properties:: From expressions to source locations. |
659c1e29 | 20 | * Programmatic Error Handling:: Debugging when an error occurs. |
3b541ca2 | 21 | * Traps:: Breakpoints, tracepoints, oh my! |
5af872e1 NJ |
22 | @end menu |
23 | ||
24 | @node Evaluation Model | |
25 | @subsection Evaluation and the Scheme Stack | |
26 | ||
42cb9b03 AW |
27 | The idea of the Scheme stack is central to a lot of debugging. The |
28 | Scheme stack is a reified representation of the pending function returns | |
a1652dec | 29 | in an expression's continuation. As Guile implements function calls |
42cb9b03 | 30 | using a stack, this reification takes the form of a number of nested |
a1652dec AW |
31 | stack frames, each of which corresponds to the application of a |
32 | procedure to a set of arguments. | |
42cb9b03 AW |
33 | |
34 | A Scheme stack always exists implicitly, and can be summoned into | |
35 | concrete existence as a first-class Scheme value by the | |
36 | @code{make-stack} call, so that an introspective Scheme program -- such | |
37 | as a debugger -- can present it in some way and allow the user to query | |
38 | its details. The first thing to understand, therefore, is how Guile's | |
39 | function call convention creates the stack. | |
40 | ||
41 | Broadly speaking, Guile represents all control flow on a stack. Calling | |
42 | a function involves pushing an empty frame on the stack, then evaluating | |
43 | the procedure and its arguments, then fixing up the new frame so that it | |
44 | points to the old one. Frames on the stack are thus linked together. A | |
45 | tail call is the same, except it reuses the existing frame instead of | |
46 | pushing on a new one. | |
47 | ||
48 | In this way, the only frames that are on the stack are ``active'' | |
49 | frames, frames which need to do some work before the computation is | |
50 | complete. On the other hand, a function that has tail-called another | |
51 | function will not be on the stack, as it has no work left to do. | |
5af872e1 NJ |
52 | |
53 | Therefore, when an error occurs in a running program, or the program | |
54 | hits a breakpoint, or in fact at any point that the programmer chooses, | |
55 | its state at that point can be represented by a @dfn{stack} of all the | |
a1652dec AW |
56 | procedure applications that are logically in progress at that time, each |
57 | of which is known as a @dfn{frame}. The programmer can learn more about | |
58 | the program's state at that point by inspecting the stack and its | |
59 | frames. | |
5af872e1 NJ |
60 | |
61 | @menu | |
5db7c0bf AW |
62 | * Stack Capture:: Reifying a continuation. |
63 | * Stacks:: Accessors for the stack data type. | |
64 | * Frames:: Likewise, accessors for stack frames. | |
07d83abe MV |
65 | @end menu |
66 | ||
5db7c0bf AW |
67 | @node Stack Capture |
68 | @subsubsection Stack Capture | |
07d83abe | 69 | |
5af872e1 NJ |
70 | A Scheme program can use the @code{make-stack} primitive anywhere in its |
71 | code, with first arg @code{#t}, to construct a Scheme value that | |
72 | describes the Scheme stack at that point. | |
73 | ||
74 | @lisp | |
75 | (make-stack #t) | |
76 | @result{} | |
a1652dec | 77 | #<stack 25205a0> |
5af872e1 | 78 | @end lisp |
07d83abe | 79 | |
5db7c0bf AW |
80 | Use @code{start-stack} to limit the stack extent captured by future |
81 | @code{make-stack} calls. | |
82 | ||
df0a1002 | 83 | @deffn {Scheme Procedure} make-stack obj arg @dots{} |
07d83abe MV |
84 | @deffnx {C Function} scm_make_stack (obj, args) |
85 | Create a new stack. If @var{obj} is @code{#t}, the current | |
86 | evaluation stack is used for creating the stack frames, | |
87 | otherwise the frames are taken from @var{obj} (which must be | |
42cb9b03 | 88 | a continuation or a frame object). |
07d83abe | 89 | |
df0a1002 BT |
90 | @var{arg} @dots{} can be any combination of integer, procedure, prompt |
91 | tag and @code{#t} values. | |
07d83abe MV |
92 | |
93 | These values specify various ways of cutting away uninteresting | |
94 | stack frames from the top and bottom of the stack that | |
95 | @code{make-stack} returns. They come in pairs like this: | |
96 | @code{(@var{inner_cut_1} @var{outer_cut_1} @var{inner_cut_2} | |
97 | @var{outer_cut_2} @dots{})}. | |
98 | ||
64de6db5 | 99 | Each @var{inner_cut_i} can be @code{#t}, an integer, a prompt |
42cb9b03 AW |
100 | tag, or a procedure. @code{#t} means to cut away all frames up |
101 | to but excluding the first user module frame. An integer means | |
102 | to cut away exactly that number of frames. A prompt tag means | |
103 | to cut away all frames that are inside a prompt with the given | |
104 | tag. A procedure means to cut away all frames up to but | |
105 | excluding the application frame whose procedure matches the | |
106 | specified one. | |
107 | ||
64de6db5 | 108 | Each @var{outer_cut_i} can be an integer, a prompt tag, or a |
42cb9b03 AW |
109 | procedure. An integer means to cut away that number of frames. |
110 | A prompt tag means to cut away all frames that are outside a | |
111 | prompt with the given tag. A procedure means to cut away | |
112 | frames down to but excluding the application frame whose | |
07d83abe MV |
113 | procedure matches the specified one. |
114 | ||
64de6db5 | 115 | If the @var{outer_cut_i} of the last pair is missing, it is |
07d83abe MV |
116 | taken as 0. |
117 | @end deffn | |
118 | ||
5db7c0bf AW |
119 | @deffn {Scheme Syntax} start-stack id exp |
120 | Evaluate @var{exp} on a new calling stack with identity @var{id}. If | |
121 | @var{exp} is interrupted during evaluation, backtraces will not display | |
122 | frames farther back than @var{exp}'s top-level form. This macro is a | |
123 | way of artificially limiting backtraces and stack procedures, largely as | |
124 | a convenience to the user. | |
125 | @end deffn | |
126 | ||
07d83abe | 127 | |
6e069bbf AW |
128 | @node Stacks |
129 | @subsubsection Stacks | |
07d83abe MV |
130 | |
131 | @deffn {Scheme Procedure} stack? obj | |
132 | @deffnx {C Function} scm_stack_p (obj) | |
133 | Return @code{#t} if @var{obj} is a calling stack. | |
134 | @end deffn | |
135 | ||
136 | @deffn {Scheme Procedure} stack-id stack | |
137 | @deffnx {C Function} scm_stack_id (stack) | |
138 | Return the identifier given to @var{stack} by @code{start-stack}. | |
139 | @end deffn | |
140 | ||
141 | @deffn {Scheme Procedure} stack-length stack | |
142 | @deffnx {C Function} scm_stack_length (stack) | |
143 | Return the length of @var{stack}. | |
144 | @end deffn | |
145 | ||
146 | @deffn {Scheme Procedure} stack-ref stack index | |
147 | @deffnx {C Function} scm_stack_ref (stack, index) | |
148 | Return the @var{index}'th frame from @var{stack}. | |
149 | @end deffn | |
150 | ||
7cd44c6d MV |
151 | @deffn {Scheme Procedure} display-backtrace stack port [first [depth [highlights]]] |
152 | @deffnx {C Function} scm_display_backtrace_with_highlights (stack, port, first, depth, highlights) | |
07d83abe | 153 | @deffnx {C Function} scm_display_backtrace (stack, port, first, depth) |
fc3d5c43 | 154 | Display a backtrace to the output port @var{port}. @var{stack} |
07d83abe | 155 | is the stack to take the backtrace from, @var{first} specifies |
fc3d5c43 NJ |
156 | where in the stack to start and @var{depth} how many frames |
157 | to display. @var{first} and @var{depth} can be @code{#f}, | |
07d83abe | 158 | which means that default values will be used. |
fc3d5c43 NJ |
159 | If @var{highlights} is given it should be a list; the elements |
160 | of this list will be highlighted wherever they appear in the | |
161 | backtrace. | |
07d83abe MV |
162 | @end deffn |
163 | ||
164 | ||
6e069bbf AW |
165 | @node Frames |
166 | @subsubsection Frames | |
07d83abe MV |
167 | |
168 | @deffn {Scheme Procedure} frame? obj | |
169 | @deffnx {C Function} scm_frame_p (obj) | |
170 | Return @code{#t} if @var{obj} is a stack frame. | |
171 | @end deffn | |
172 | ||
07d83abe MV |
173 | @deffn {Scheme Procedure} frame-previous frame |
174 | @deffnx {C Function} scm_frame_previous (frame) | |
175 | Return the previous frame of @var{frame}, or @code{#f} if | |
176 | @var{frame} is the first frame in its stack. | |
177 | @end deffn | |
178 | ||
07d83abe MV |
179 | @deffn {Scheme Procedure} frame-procedure frame |
180 | @deffnx {C Function} scm_frame_procedure (frame) | |
181 | Return the procedure for @var{frame}, or @code{#f} if no | |
182 | procedure is associated with @var{frame}. | |
183 | @end deffn | |
184 | ||
185 | @deffn {Scheme Procedure} frame-arguments frame | |
186 | @deffnx {C Function} scm_frame_arguments (frame) | |
187 | Return the arguments of @var{frame}. | |
188 | @end deffn | |
189 | ||
5db7c0bf AW |
190 | @deffn {Scheme Procedure} frame-address frame |
191 | @deffnx {Scheme Procedure} frame-instruction-pointer frame | |
192 | @deffnx {Scheme Procedure} frame-stack-pointer frame | |
193 | Accessors for the three VM registers associated with this frame: the | |
194 | frame pointer (fp), instruction pointer (ip), and stack pointer (sp), | |
195 | respectively. @xref{VM Concepts}, for more information. | |
196 | @end deffn | |
197 | ||
198 | @deffn {Scheme Procedure} frame-dynamic-link frame | |
199 | @deffnx {Scheme Procedure} frame-return-address frame | |
200 | @deffnx {Scheme Procedure} frame-mv-return-address frame | |
201 | Accessors for the three saved VM registers in a frame: the previous | |
202 | frame pointer, the single-value return address, and the multiple-value | |
203 | return address. @xref{Stack Layout}, for more information. | |
204 | @end deffn | |
205 | ||
206 | @deffn {Scheme Procedure} frame-num-locals frame | |
207 | @deffnx {Scheme Procedure} frame-local-ref frame i | |
208 | @deffnx {Scheme Procedure} frame-local-set! frame i val | |
209 | Accessors for the temporary values corresponding to @var{frame}'s | |
210 | procedure application. The first local is the first argument given to | |
211 | the procedure. After the arguments, there are the local variables, and | |
212 | after that temporary values. @xref{Stack Layout}, for more information. | |
213 | @end deffn | |
214 | ||
07d83abe MV |
215 | @deffn {Scheme Procedure} display-application frame [port [indent]] |
216 | @deffnx {C Function} scm_display_application (frame, port, indent) | |
217 | Display a procedure application @var{frame} to the output port | |
218 | @var{port}. @var{indent} specifies the indentation of the | |
219 | output. | |
220 | @end deffn | |
221 | ||
5db7c0bf AW |
222 | Additionally, the @code{(system vm frame)} module defines a number of |
223 | higher-level introspective procedures, for example to retrieve the names | |
224 | of local variables, and the source location to correspond to a | |
225 | frame. See its source code for more details. | |
226 | ||
07d83abe | 227 | |
5af872e1 | 228 | @node Source Properties |
5db7c0bf | 229 | @subsection Source Properties |
5af872e1 NJ |
230 | |
231 | @cindex source properties | |
232 | As Guile reads in Scheme code from file or from standard input, it | |
233 | remembers the file name, line number and column number where each | |
42cb9b03 AW |
234 | expression begins. These pieces of information are known as the |
235 | @dfn{source properties} of the expression. Syntax expanders and the | |
236 | compiler propagate these source properties to compiled procedures, so | |
237 | that, if an error occurs when evaluating the transformed expression, | |
238 | Guile's debugger can point back to the file and location where the | |
239 | expression originated. | |
5af872e1 | 240 | |
b131b233 | 241 | The way that source properties are stored means that Guile cannot |
38f19074 MW |
242 | associate source properties with individual symbols, keywords, |
243 | characters, booleans, or small integers. This can be seen by typing | |
b131b233 MW |
244 | @code{(xxx)} and @code{xxx} at the Guile prompt (where the variable |
245 | @code{xxx} has not been defined): | |
5af872e1 NJ |
246 | |
247 | @example | |
a1652dec AW |
248 | scheme@@(guile-user)> (xxx) |
249 | <unnamed port>:4:1: In procedure module-lookup: | |
250 | <unnamed port>:4:1: Unbound variable: xxx | |
251 | ||
252 | scheme@@(guile-user)> xxx | |
253 | ERROR: In procedure module-lookup: | |
254 | ERROR: Unbound variable: xxx | |
5af872e1 NJ |
255 | @end example |
256 | ||
257 | @noindent | |
a1652dec AW |
258 | In the latter case, no source properties were stored, so the error |
259 | doesn't have any source information. | |
5af872e1 | 260 | |
76b9bac5 MW |
261 | @deffn {Scheme Procedure} supports-source-properties? obj |
262 | @deffnx {C Function} scm_supports_source_properties_p (obj) | |
263 | Return #t if source properties can be associated with @var{obj}, | |
264 | otherwise return #f. | |
265 | @end deffn | |
266 | ||
5af872e1 | 267 | The recording of source properties is controlled by the read option |
1518f649 | 268 | named ``positions'' (@pxref{Scheme Read}). This option is switched |
42cb9b03 | 269 | @emph{on} by default. |
5af872e1 NJ |
270 | |
271 | The following procedures can be used to access and set the source | |
272 | properties of read expressions. | |
273 | ||
916f175f NJ |
274 | @deffn {Scheme Procedure} set-source-properties! obj alist |
275 | @deffnx {C Function} scm_set_source_properties_x (obj, alist) | |
276 | Install the association list @var{alist} as the source property | |
5af872e1 NJ |
277 | list for @var{obj}. |
278 | @end deffn | |
279 | ||
280 | @deffn {Scheme Procedure} set-source-property! obj key datum | |
281 | @deffnx {C Function} scm_set_source_property_x (obj, key, datum) | |
282 | Set the source property of object @var{obj}, which is specified by | |
283 | @var{key} to @var{datum}. Normally, the key will be a symbol. | |
284 | @end deffn | |
285 | ||
286 | @deffn {Scheme Procedure} source-properties obj | |
287 | @deffnx {C Function} scm_source_properties (obj) | |
288 | Return the source property association list of @var{obj}. | |
289 | @end deffn | |
290 | ||
291 | @deffn {Scheme Procedure} source-property obj key | |
292 | @deffnx {C Function} scm_source_property (obj, key) | |
916f175f NJ |
293 | Return the property specified by @var{key} from @var{obj}'s source |
294 | properties. | |
5af872e1 NJ |
295 | @end deffn |
296 | ||
b131b233 MW |
297 | If the @code{positions} reader option is enabled, supported expressions |
298 | will have values set for the @code{filename}, @code{line} and | |
42cb9b03 | 299 | @code{column} properties. |
5af872e1 | 300 | |
925172cf AW |
301 | Source properties are also associated with syntax objects. Procedural |
302 | macros can get at the source location of their input using the | |
303 | @code{syntax-source} accessor. @xref{Syntax Transformer Helpers}, for | |
304 | more. | |
305 | ||
306 | Guile also defines a couple of convenience macros built on | |
307 | @code{syntax-source}: | |
308 | ||
309 | @deffn {Scheme Syntax} current-source-location | |
310 | Expands to the source properties corresponding to the location of the | |
311 | @code{(current-source-location)} form. | |
312 | @end deffn | |
313 | ||
314 | @deffn {Scheme Syntax} current-filename | |
315 | Expands to the current filename: the filename that the | |
316 | @code{(current-filename)} form appears in. Expands to @code{#f} if this | |
317 | information is unavailable. | |
318 | @end deffn | |
319 | ||
1fc8dcc7 AW |
320 | If you're stuck with defmacros (@pxref{Defmacros}), and want to preserve |
321 | source information, the following helper function might be useful to | |
322 | you: | |
07d83abe | 323 | |
1fc8dcc7 AW |
324 | @deffn {Scheme Procedure} cons-source xorig x y |
325 | @deffnx {C Function} scm_cons_source (xorig, x, y) | |
326 | Create and return a new pair whose car and cdr are @var{x} and @var{y}. | |
327 | Any source properties associated with @var{xorig} are also associated | |
328 | with the new pair. | |
07d83abe MV |
329 | @end deffn |
330 | ||
331 | ||
659c1e29 AW |
332 | @node Programmatic Error Handling |
333 | @subsection Programmatic Error Handling | |
334 | ||
335 | For better or for worse, all programs have bugs, and dealing with bugs | |
336 | is part of programming. This section deals with that class of bugs that | |
337 | causes an exception to be raised -- from your own code, from within a | |
338 | library, or from Guile itself. | |
339 | ||
340 | @menu | |
341 | * Catching Exceptions:: Handling errors after the stack is unwound. | |
342 | * Capturing Stacks:: Capturing the stack at the time of error. | |
343 | * Pre-Unwind Debugging:: Debugging before the exception is thrown. | |
344 | * Debug Options:: A historical interface to debugging. | |
345 | @end menu | |
346 | ||
347 | @node Catching Exceptions | |
348 | @subsubsection Catching Exceptions | |
5af872e1 | 349 | |
2202fd6c NJ |
350 | A common requirement is to be able to show as much useful context as |
351 | possible when a Scheme program hits an error. The most immediate | |
352 | information about an error is the kind of error that it is -- such as | |
353 | ``division by zero'' -- and any parameters that the code which signalled | |
354 | the error chose explicitly to provide. This information originates with | |
355 | the @code{error} or @code{throw} call (or their C code equivalents, if | |
356 | the error is detected by C code) that signals the error, and is passed | |
357 | automatically to the handler procedure of the innermost applicable | |
42cb9b03 | 358 | @code{catch} or @code{with-throw-handler} expression. |
2202fd6c | 359 | |
2202fd6c NJ |
360 | Therefore, to catch errors that occur within a chunk of Scheme code, and |
361 | to intercept basic information about those errors, you need to execute | |
42cb9b03 AW |
362 | that code inside the dynamic context of a @code{catch} or |
363 | @code{with-throw-handler} expression, or the equivalent in C. In Scheme, | |
364 | this means you need something like this: | |
2202fd6c NJ |
365 | |
366 | @lisp | |
367 | (catch #t | |
368 | (lambda () | |
369 | ;; Execute the code in which | |
370 | ;; you want to catch errors here. | |
371 | ...) | |
372 | (lambda (key . parameters) | |
373 | ;; Put the code which you want | |
374 | ;; to handle an error here. | |
375 | ...)) | |
376 | @end lisp | |
377 | ||
378 | @noindent | |
659c1e29 AW |
379 | The @code{catch} here can also be @code{with-throw-handler}; see |
380 | @ref{Throw Handlers} for information on the when you might want to use | |
381 | @code{with-throw-handler} instead of @code{catch}. | |
382 | ||
383 | For example, to print out a message and return #f when an error occurs, | |
384 | you might use: | |
385 | ||
386 | @smalllisp | |
387 | (define (catch-all thunk) | |
388 | (catch #t | |
389 | thunk | |
390 | (lambda (key . parameters) | |
391 | (format (current-error-port) | |
392 | "Uncaught throw to '~a: ~a\n" key parameters) | |
393 | #f))) | |
394 | ||
395 | (catch-all | |
396 | (lambda () (error "Not a vegetable: tomato"))) | |
3b3518e7 | 397 | @print{} Uncaught throw to 'misc-error: (#f ~A (Not a vegetable: tomato) #f) |
659c1e29 AW |
398 | @result{} #f |
399 | @end smalllisp | |
400 | ||
401 | The @code{#t} means that the catch is applicable to all kinds of error. | |
402 | If you want to restrict your catch to just one kind of error, you can | |
403 | put the symbol for that kind of error instead of @code{#t}. The | |
404 | equivalent to this in C would be something like this: | |
2202fd6c NJ |
405 | |
406 | @lisp | |
407 | SCM my_body_proc (void *body_data) | |
408 | @{ | |
409 | /* Execute the code in which | |
410 | you want to catch errors here. */ | |
411 | ... | |
412 | @} | |
413 | ||
fc3d5c43 NJ |
414 | SCM my_handler_proc (void *handler_data, |
415 | SCM key, | |
416 | SCM parameters) | |
2202fd6c NJ |
417 | @{ |
418 | /* Put the code which you want | |
419 | to handle an error here. */ | |
420 | ... | |
421 | @} | |
422 | ||
423 | @{ | |
424 | ... | |
425 | scm_c_catch (SCM_BOOL_T, | |
426 | my_body_proc, body_data, | |
427 | my_handler_proc, handler_data, | |
428 | NULL, NULL); | |
429 | ... | |
430 | @} | |
431 | @end lisp | |
432 | ||
433 | @noindent | |
434 | Again, as with the Scheme version, @code{scm_c_catch} could be replaced | |
42cb9b03 AW |
435 | by @code{scm_c_with_throw_handler}, and @code{SCM_BOOL_T} could instead |
436 | be the symbol for a particular kind of error. | |
2202fd6c | 437 | |
659c1e29 | 438 | @node Capturing Stacks |
2202fd6c NJ |
439 | @subsubsection Capturing the full error stack |
440 | ||
441 | The other interesting information about an error is the full Scheme | |
442 | stack at the point where the error occurred; in other words what | |
443 | innermost expression was being evaluated, what was the expression that | |
444 | called that one, and so on. If you want to write your code so that it | |
42cb9b03 | 445 | captures and can display this information as well, there are a couple |
2202fd6c NJ |
446 | important things to understand. |
447 | ||
42cb9b03 | 448 | Firstly, the stack at the point of the error needs to be explicitly |
2202fd6c | 449 | captured by a @code{make-stack} call (or the C equivalent |
fc3d5c43 | 450 | @code{scm_make_stack}). The Guile library does not do this |
2202fd6c NJ |
451 | ``automatically'' for you, so you will need to write code with a |
452 | @code{make-stack} or @code{scm_make_stack} call yourself. (We emphasise | |
453 | this point because some people are misled by the fact that the Guile | |
454 | interactive REPL code @emph{does} capture and display the stack | |
455 | automatically. But the Guile interactive REPL is itself a Scheme | |
456 | program@footnote{In effect, it is the default program which is run when | |
457 | no commands or script file are specified on the Guile command line.} | |
458 | running on top of the Guile library, and which uses @code{catch} and | |
459 | @code{make-stack} in the way we are about to describe to capture the | |
460 | stack when an error occurs.) | |
461 | ||
42cb9b03 AW |
462 | And secondly, in order to capture the stack effectively at the point |
463 | where the error occurred, the @code{make-stack} call must be made before | |
464 | Guile unwinds the stack back to the location of the prevailing catch | |
465 | expression. This means that the @code{make-stack} call must be made | |
466 | within the handler of a @code{with-throw-handler} expression, or the | |
467 | optional "pre-unwind" handler of a @code{catch}. (For the full story of | |
468 | how these alternatives differ from each other, see @ref{Exceptions}. The | |
469 | main difference is that @code{catch} terminates the error, whereas | |
470 | @code{with-throw-handler} only intercepts it temporarily and then allow | |
fc3d5c43 NJ |
471 | it to continue propagating up to the next innermost handler.) |
472 | ||
473 | So, here are some examples of how to do all this in Scheme and in C. | |
474 | For the purpose of these examples we assume that the captured stack | |
475 | should be stored in a variable, so that it can be displayed or | |
476 | arbitrarily processed later on. In Scheme: | |
477 | ||
478 | @lisp | |
479 | (let ((captured-stack #f)) | |
480 | (catch #t | |
481 | (lambda () | |
482 | ;; Execute the code in which | |
483 | ;; you want to catch errors here. | |
484 | ...) | |
485 | (lambda (key . parameters) | |
486 | ;; Put the code which you want | |
487 | ;; to handle an error after the | |
488 | ;; stack has been unwound here. | |
489 | ...) | |
490 | (lambda (key . parameters) | |
491 | ;; Capture the stack here: | |
492 | (set! captured-stack (make-stack #t)))) | |
493 | ... | |
494 | (if captured-stack | |
495 | (begin | |
496 | ;; Display or process the captured stack. | |
497 | ...)) | |
498 | ...) | |
499 | @end lisp | |
500 | ||
501 | @noindent | |
502 | And in C: | |
503 | ||
504 | @lisp | |
505 | SCM my_body_proc (void *body_data) | |
506 | @{ | |
507 | /* Execute the code in which | |
508 | you want to catch errors here. */ | |
509 | ... | |
510 | @} | |
511 | ||
512 | SCM my_handler_proc (void *handler_data, | |
513 | SCM key, | |
514 | SCM parameters) | |
515 | @{ | |
516 | /* Put the code which you want | |
517 | to handle an error after the | |
518 | stack has been unwound here. */ | |
519 | ... | |
520 | @} | |
521 | ||
522 | SCM my_preunwind_proc (void *handler_data, | |
523 | SCM key, | |
524 | SCM parameters) | |
525 | @{ | |
526 | /* Capture the stack here: */ | |
527 | *(SCM *)handler_data = scm_make_stack (SCM_BOOL_T, SCM_EOL); | |
528 | @} | |
529 | ||
530 | @{ | |
531 | SCM captured_stack = SCM_BOOL_F; | |
532 | ... | |
533 | scm_c_catch (SCM_BOOL_T, | |
534 | my_body_proc, body_data, | |
535 | my_handler_proc, handler_data, | |
536 | my_preunwind_proc, &captured_stack); | |
537 | ... | |
538 | if (captured_stack != SCM_BOOL_F) | |
539 | @{ | |
540 | /* Display or process the captured stack. */ | |
541 | ... | |
542 | @} | |
543 | ... | |
544 | @} | |
545 | @end lisp | |
546 | ||
fc3d5c43 NJ |
547 | Once you have a captured stack, you can interrogate and display its |
548 | details in any way that you want, using the @code{stack-@dots{}} and | |
6e069bbf AW |
549 | @code{frame-@dots{}} API described in @ref{Stacks} and |
550 | @ref{Frames}. | |
fc3d5c43 NJ |
551 | |
552 | If you want to print out a backtrace in the same format that the Guile | |
553 | REPL does, you can use the @code{display-backtrace} procedure to do so. | |
554 | You can also use @code{display-application} to display an individual | |
659c1e29 | 555 | frame in the Guile REPL format. |
fc3d5c43 | 556 | |
659c1e29 AW |
557 | @node Pre-Unwind Debugging |
558 | @subsubsection Pre-Unwind Debugging | |
fc3d5c43 | 559 | |
659c1e29 AW |
560 | Instead of saving a stack away and waiting for the @code{catch} to |
561 | return, you can handle errors directly, from within the pre-unwind | |
562 | handler. | |
563 | ||
564 | For example, to show a backtrace when an error is thrown, you might want | |
565 | to use a procedure like this: | |
566 | ||
567 | @lisp | |
568 | (define (with-backtrace thunk) | |
569 | (with-throw-handler #t | |
570 | thunk | |
571 | (lambda args (backtrace)))) | |
572 | (with-backtrace (lambda () (error "Not a vegetable: tomato"))) | |
573 | @end lisp | |
574 | ||
575 | Since we used @code{with-throw-handler} here, we didn't actually catch | |
576 | the error. @xref{Throw Handlers}, for more information. However, we did | |
577 | print out a context at the time of the error, using the built-in | |
578 | procedure, @code{backtrace}. | |
fc3d5c43 | 579 | |
5af872e1 NJ |
580 | @deffn {Scheme Procedure} backtrace [highlights] |
581 | @deffnx {C Function} scm_backtrace_with_highlights (highlights) | |
582 | @deffnx {C Function} scm_backtrace () | |
659c1e29 AW |
583 | Display a backtrace of the current stack to the current output port. If |
584 | @var{highlights} is given it should be a list; the elements of this list | |
585 | will be highlighted wherever they appear in the backtrace. | |
5af872e1 NJ |
586 | @end deffn |
587 | ||
659c1e29 AW |
588 | The Guile REPL code (in @file{system/repl/repl.scm} and related files) |
589 | uses a @code{catch} with a pre-unwind handler to capture the stack when | |
590 | an error occurs in an expression that was typed into the REPL, and debug | |
591 | that stack interactively in the context of the error. | |
592 | ||
593 | These procedures are available for use by user programs, in the | |
594 | @code{(system repl error-handling)} module. | |
595 | ||
596 | @lisp | |
597 | (use-modules (system repl error-handling)) | |
598 | @end lisp | |
5b2da4cc | 599 | |
1f603ae2 AW |
600 | @deffn {Scheme Procedure} call-with-error-handling thunk @ |
601 | [#:on-error on-error='debug] [#:post-error post-error='catch] @ | |
602 | [#:pass-keys pass-keys='(quit)] [#:trap-handler trap-handler='debug] | |
603 | Call a thunk in a context in which errors are handled. | |
604 | ||
605 | There are four keyword arguments: | |
606 | ||
607 | @table @var | |
608 | @item on-error | |
609 | Specifies what to do before the stack is unwound. | |
610 | ||
611 | Valid options are @code{debug} (the default), which will enter a | |
612 | debugger; @code{pass}, in which case nothing is done, and the exception | |
613 | is rethrown; or a procedure, which will be the pre-unwind handler. | |
614 | ||
615 | @item post-error | |
616 | Specifies what to do after the stack is unwound. | |
617 | ||
618 | Valid options are @code{catch} (the default), which will silently catch | |
619 | errors, returning the unspecified value; @code{report}, which prints out | |
620 | a description of the error (via @code{display-error}), and then returns | |
621 | the unspecified value; or a procedure, which will be the catch handler. | |
622 | ||
623 | @item trap-handler | |
624 | Specifies a trap handler: what to do when a breakpoint is hit. | |
625 | ||
626 | Valid options are @code{debug}, which will enter the debugger; | |
627 | @code{pass}, which does nothing; or @code{disabled}, which disables | |
628 | traps entirely. @xref{Traps}, for more information. | |
629 | ||
630 | @item pass-keys | |
631 | A set of keys to ignore, as a list. | |
632 | @end table | |
5af872e1 NJ |
633 | @end deffn |
634 | ||
659c1e29 | 635 | @node Debug Options |
1cfdb1bb AW |
636 | @subsubsection Debug options |
637 | ||
c005daf9 AW |
638 | The behavior of the @code{backtrace} procedure and of the default error |
639 | handler can be parameterized via the debug options. | |
1cfdb1bb AW |
640 | |
641 | @cindex options - debug | |
642 | @cindex debug options | |
643 | @deffn {Scheme Procedure} debug-options [setting] | |
644 | Display the current settings of the debug options. If @var{setting} is | |
645 | omitted, only a short form of the current read options is printed. | |
646 | Otherwise if @var{setting} is the symbol @code{help}, a complete options | |
647 | description is displayed. | |
648 | @end deffn | |
649 | ||
650 | The set of available options, and their default values, may be had by | |
651 | invoking @code{debug-options} at the prompt. | |
652 | ||
653 | @smallexample | |
654 | scheme@@(guile-user)> | |
655 | backwards no Display backtrace in anti-chronological order. | |
656 | width 79 Maximal width of backtrace. | |
657 | depth 20 Maximal length of printed backtrace. | |
658 | backtrace yes Show backtrace on error. | |
659 | stack 1048576 Stack size limit (measured in words; | |
660 | 0 = no check). | |
661 | show-file-name #t Show file names and line numbers in backtraces | |
662 | when not `#f'. A value of `base' displays only | |
663 | base names, while `#t' displays full names. | |
664 | warn-deprecated no Warn when deprecated features are used. | |
665 | @end smallexample | |
666 | ||
667 | The boolean options may be toggled with @code{debug-enable} and | |
668 | @code{debug-disable}. The non-boolean @code{keywords} option must be set | |
669 | using @code{debug-set!}. | |
670 | ||
671 | @deffn {Scheme Procedure} debug-enable option-name | |
672 | @deffnx {Scheme Procedure} debug-disable option-name | |
1233b383 | 673 | @deffnx {Scheme Syntax} debug-set! option-name value |
1cfdb1bb AW |
674 | Modify the debug options. @code{debug-enable} should be used with boolean |
675 | options and switches them on, @code{debug-disable} switches them off. | |
1233b383 AW |
676 | |
677 | @code{debug-set!} can be used to set an option to a specific value. Due | |
678 | to historical oddities, it is a macro that expects an unquoted option | |
679 | name. | |
1cfdb1bb AW |
680 | @end deffn |
681 | ||
682 | @subsubheading Stack overflow | |
683 | ||
684 | @cindex overflow, stack | |
685 | @cindex stack overflow | |
686 | Stack overflow errors are caused by a computation trying to use more | |
3b3518e7 AW |
687 | stack space than has been enabled by the @code{stack} option. There are |
688 | actually two kinds of stack that can overflow, the C stack and the | |
689 | Scheme stack. | |
690 | ||
691 | Scheme stack overflows can occur if Scheme procedures recurse too far | |
692 | deeply. An example would be the following recursive loop: | |
693 | ||
694 | @lisp | |
695 | scheme@@(guile-user)> (let lp () (+ 1 (lp))) | |
696 | <unnamed port>:8:17: In procedure vm-run: | |
697 | <unnamed port>:8:17: VM: Stack overflow | |
698 | @end lisp | |
699 | ||
700 | The default stack size should allow for about 10000 frames or so, so one | |
701 | usually doesn't hit this level of recursion. Unfortunately there is no | |
702 | way currently to make a VM with a bigger stack. If you are in this | |
703 | unfortunate situation, please file a bug, and in the meantime, rewrite | |
704 | your code to be tail-recursive (@pxref{Tail Calls}). | |
705 | ||
706 | The other limit you might hit would be C stack overflows. If you call a | |
707 | primitive procedure which then calls a Scheme procedure in a loop, you | |
708 | will consume C stack space. Guile tries to detect excessive consumption | |
709 | of C stack space, throwing an error when you have hit 80% of the | |
710 | process' available stack (as allocated by the operating system), or 160 | |
711 | kilowords in the absence of a strict limit. | |
712 | ||
713 | For example, looping through @code{call-with-vm}, a primitive that calls | |
714 | a thunk, gives us the following: | |
1cfdb1bb AW |
715 | |
716 | @lisp | |
3b3518e7 AW |
717 | scheme@@(guile-user)> (use-modules (system vm vm)) |
718 | scheme@@(guile-user)> (debug-set! stack 10000) | |
a222cbc9 | 719 | scheme@@(guile-user)> (let lp () (call-with-vm lp)) |
3b3518e7 | 720 | ERROR: In procedure call-with-vm: |
1cfdb1bb | 721 | ERROR: Stack overflow |
1cfdb1bb AW |
722 | @end lisp |
723 | ||
724 | If you get an error like this, you can either try rewriting your code to | |
725 | use less stack space, or increase the maximum stack size. To increase | |
726 | the maximum stack size, use @code{debug-set!}, for example: | |
727 | ||
728 | @lisp | |
729 | (debug-set! stack 200000) | |
1cfdb1bb AW |
730 | @end lisp |
731 | ||
3b3518e7 AW |
732 | But of course it's better to have your code operate without so much |
733 | resource consumption, avoiding loops through C trampolines. | |
1cfdb1bb | 734 | |
62ae9557 | 735 | |
24dbb5ed NJ |
736 | @node Traps |
737 | @subsection Traps | |
62ae9557 NJ |
738 | |
739 | @cindex Traps | |
6e069bbf | 740 | @cindex VM hooks |
62ae9557 NJ |
741 | @cindex Breakpoints |
742 | @cindex Trace | |
743 | @cindex Tracing | |
744 | @cindex Code coverage | |
745 | @cindex Profiling | |
42cb9b03 | 746 | Guile's virtual machine can be configured to call out at key points to |
6e069bbf AW |
747 | arbitrary user-specified procedures. |
748 | ||
749 | In principle, these @dfn{hooks} allow Scheme code to implement any model | |
750 | it chooses for examining the evaluation stack as program execution | |
751 | proceeds, and for suspending execution to be resumed later. | |
752 | ||
753 | VM hooks are very low-level, though, and so Guile also has a library of | |
754 | higher-level @dfn{traps} on top of the VM hooks. A trap is an execution | |
755 | condition that, when fulfilled, will fire a handler. For example, Guile | |
756 | defines a trap that fires when control reaches a certain source | |
757 | location. | |
758 | ||
759 | Finally, Guile also defines a third level of abstractions: per-thread | |
760 | @dfn{trap states}. A trap state exists to give names to traps, and to | |
761 | hold on to the set of traps so that they can be enabled, disabled, or | |
762 | removed. The trap state infrastructure defines the most useful | |
763 | abstractions for most cases. For example, Guile's REPL uses trap state | |
764 | functions to set breakpoints and tracepoints. | |
24dbb5ed NJ |
765 | |
766 | The following subsections describe all this in detail, for both the | |
767 | user wanting to use traps, and the developer interested in | |
62ae9557 NJ |
768 | understanding how the interface hangs together. |
769 | ||
770 | ||
6e069bbf AW |
771 | @menu |
772 | * VM Hooks:: Modifying Guile's virtual machine. | |
773 | * Trap Interface:: Traps are on or off. | |
774 | * Low-Level Traps:: The various kinds of low-level traps. | |
775 | * Tracing Traps:: Traps to trace procedure calls and returns. | |
776 | * Trap States:: One state (per thread) to bind them. | |
63e36ea6 | 777 | * High-Level Traps:: The highest-level trap interface. Use this. |
6e069bbf | 778 | @end menu |
42cb9b03 | 779 | |
42cb9b03 | 780 | |
6e069bbf AW |
781 | @node VM Hooks |
782 | @subsubsection VM Hooks | |
42cb9b03 | 783 | |
6e069bbf AW |
784 | Everything that runs in Guile runs on its virtual machine, a C program |
785 | that defines a number of operations that Scheme programs can | |
786 | perform. | |
62ae9557 | 787 | |
6e069bbf AW |
788 | Note that there are multiple VM ``engines'' for Guile. Only some of them |
789 | have support for hooks compiled in. Normally the deal is that you get | |
790 | hooks if you are running interactively, and otherwise they are disabled, | |
791 | as they do have some overhead (about 10 or 20 percent). | |
62ae9557 | 792 | |
6e069bbf AW |
793 | To ensure that you are running with hooks, pass @code{--debug} to Guile |
794 | when running your program, or otherwise use the @code{call-with-vm} and | |
795 | @code{set-vm-engine!} procedures to ensure that you are running in a VM | |
796 | with the @code{debug} engine. | |
62ae9557 | 797 | |
6e069bbf AW |
798 | To digress, Guile's VM has 6 different hooks (@pxref{Hooks}) that can be |
799 | fired at different times, which may be accessed with the following | |
800 | procedures. | |
62ae9557 | 801 | |
c850a0ff AW |
802 | The first argument of calls to these hooks is the frame in question. |
803 | @xref{Frames}. Some hooks may call their procedures with more | |
804 | arguments. Since these hooks may be fired very frequently, Guile does a | |
805 | terrible thing: it allocates the frames on the C stack instead of the | |
806 | garbage-collected heap. | |
62ae9557 | 807 | |
6e069bbf AW |
808 | The upshot here is that the frames are only valid within the dynamic |
809 | extent of the call to the hook. If a hook procedure keeps a reference to | |
810 | the frame outside the extent of the hook, bad things will happen. | |
62ae9557 | 811 | |
6e069bbf | 812 | The interface to hooks is provided by the @code{(system vm vm)} module: |
62ae9557 | 813 | |
6e069bbf AW |
814 | @example |
815 | (use-modules (system vm vm)) | |
816 | @end example | |
62ae9557 | 817 | |
6e069bbf | 818 | @noindent |
972275ee AW |
819 | All of these functions implicitly act on the VM for the current thread |
820 | only. | |
62ae9557 | 821 | |
972275ee | 822 | @deffn {Scheme Procedure} vm-next-hook |
6e069bbf AW |
823 | The hook that will be fired before an instruction is retired (and |
824 | executed). | |
825 | @end deffn | |
62ae9557 | 826 | |
972275ee | 827 | @deffn {Scheme Procedure} vm-push-continuation-hook |
6e069bbf AW |
828 | The hook that will be fired after preparing a new frame. Fires just |
829 | before applying a procedure in a non-tail context, just before the | |
830 | corresponding apply-hook. | |
831 | @end deffn | |
62ae9557 | 832 | |
972275ee | 833 | @deffn {Scheme Procedure} vm-pop-continuation-hook |
6e069bbf | 834 | The hook that will be fired before returning from a frame. |
62ae9557 | 835 | |
c850a0ff AW |
836 | This hook fires with a variable number of arguments, corresponding to |
837 | the values that the frame returns to its continuation. | |
6e069bbf | 838 | @end deffn |
62ae9557 | 839 | |
972275ee | 840 | @deffn {Scheme Procedure} vm-apply-hook |
6e069bbf AW |
841 | The hook that will be fired before a procedure is applied. The frame's |
842 | procedure will have already been set to the new procedure. | |
62ae9557 | 843 | |
6e069bbf AW |
844 | Note that procedure application is somewhat orthogonal to continuation |
845 | pushes and pops. A non-tail call to a procedure will result first in a | |
846 | firing of the push-continuation hook, then this application hook, | |
847 | whereas a tail call will run without having fired a push-continuation | |
848 | hook. | |
849 | @end deffn | |
62ae9557 | 850 | |
972275ee | 851 | @deffn {Scheme Procedure} vm-abort-continuation-hook |
6e069bbf | 852 | The hook that will be called after aborting to a |
c850a0ff AW |
853 | prompt. @xref{Prompts}. |
854 | ||
855 | Like the pop-continuation hook, this hook fires with a variable number | |
856 | of arguments, corresponding to the values that returned to the | |
857 | continuation. | |
6e069bbf | 858 | @end deffn |
62ae9557 | 859 | |
972275ee | 860 | @deffn {Scheme Procedure} vm-restore-continuation-hook |
6e069bbf AW |
861 | The hook that will be called after restoring an undelimited |
862 | continuation. Unfortunately it's not currently possible to introspect on | |
863 | the values that were given to the continuation. | |
864 | @end deffn | |
62ae9557 | 865 | |
6e069bbf AW |
866 | @cindex VM trace level |
867 | These hooks do impose a performance penalty, if they are on. Obviously, | |
868 | the @code{vm-next-hook} has quite an impact, performance-wise. Therefore | |
869 | Guile exposes a single, heavy-handed knob to turn hooks on or off, the | |
870 | @dfn{VM trace level}. If the trace level is positive, hooks run; | |
871 | otherwise they don't. | |
62ae9557 | 872 | |
5db7c0bf AW |
873 | For convenience, when the VM fires a hook, it does so with the trap |
874 | level temporarily set to 0. That way the hooks don't fire while you're | |
875 | handling a hook. The trace level is restored to whatever it was once the hook | |
876 | procedure finishes. | |
877 | ||
972275ee | 878 | @deffn {Scheme Procedure} vm-trace-level |
6e069bbf AW |
879 | Retrieve the ``trace level'' of the VM. If positive, the trace hooks |
880 | associated with @var{vm} will be run. The initial trace level is 0. | |
881 | @end deffn | |
62ae9557 | 882 | |
972275ee | 883 | @deffn {Scheme Procedure} set-vm-trace-level! level |
6e069bbf AW |
884 | Set the ``trace level'' of the VM. |
885 | @end deffn | |
886 | ||
887 | @xref{A Virtual Machine for Guile}, for more information on Guile's | |
888 | virtual machine. | |
889 | ||
890 | @node Trap Interface | |
891 | @subsubsection Trap Interface | |
892 | ||
893 | The capabilities provided by hooks are great, but hooks alone rarely | |
894 | correspond to what users want to do. | |
895 | ||
896 | For example, if a user wants to break when and if control reaches a | |
897 | certain source location, how do you do it? If you install a ``next'' | |
898 | hook, you get unacceptable overhead for the execution of the entire | |
899 | program. It would be possible to install an ``apply'' hook, then if the | |
900 | procedure encompasses those source locations, install a ``next'' hook, | |
901 | but already you're talking about one concept that might be implemented | |
902 | by a varying number of lower-level concepts. | |
903 | ||
904 | It's best to be clear about things and define one abstraction for all | |
905 | such conditions: the @dfn{trap}. | |
906 | ||
907 | Considering the myriad capabilities offered by the hooks though, there | |
908 | is only a minimum of functionality shared by all traps. Guile's current | |
909 | take is to reduce this to the absolute minimum, and have the only | |
910 | standard interface of a trap be ``turn yourself on'' or ``turn yourself | |
911 | off''. | |
912 | ||
913 | This interface sounds a bit strange, but it is useful to procedurally | |
914 | compose higher-level traps from lower-level building blocks. For | |
915 | example, Guile defines a trap that calls one handler when control enters | |
916 | a procedure, and another when control leaves the procedure. Given that | |
917 | trap, one can define a trap that adds to the next-hook only when within | |
918 | a given procedure. Building further, one can define a trap that fires | |
919 | when control reaches particular instructions within a procedure. | |
920 | ||
921 | Or of course you can stop at any of these intermediate levels. For | |
922 | example, one might only be interested in calls to a given procedure. But | |
923 | the point is that a simple enable/disable interface is all the | |
924 | commonality that exists between the various kinds of traps, and | |
925 | furthermore that such an interface serves to allow ``higher-level'' | |
926 | traps to be composed from more primitive ones. | |
927 | ||
928 | Specifically, a trap, in Guile, is a procedure. When a trap is created, | |
929 | by convention the trap is enabled; therefore, the procedure that is the | |
930 | trap will, when called, disable the trap, and return a procedure that | |
931 | will enable the trap, and so on. | |
932 | ||
933 | Trap procedures take one optional argument: the current frame. (A trap | |
934 | may want to add to different sets of hooks depending on the frame that | |
935 | is current at enable-time.) | |
936 | ||
937 | If this all sounds very complicated, it's because it is. Some of it is | |
938 | essential, but probably most of it is not. The advantage of using this | |
939 | minimal interface is that composability is more lexically apparent than | |
940 | when, for example, using a stateful interface based on GOOPS. But | |
941 | perhaps this reflects the cognitive limitations of the programmer who | |
942 | made the current interface more than anything else. | |
943 | ||
944 | @node Low-Level Traps | |
945 | @subsubsection Low-Level Traps | |
946 | ||
5db7c0bf AW |
947 | To summarize the last sections, traps are enabled or disabled, and when |
948 | they are enabled, they add to various VM hooks. | |
949 | ||
950 | Note, however, that @emph{traps do not increase the VM trace level}. So | |
951 | if you create a trap, it will be enabled, but unless something else | |
952 | increases the VM's trace level (@pxref{VM Hooks}), the trap will not | |
953 | fire. It turns out that getting the VM trace level right is tricky | |
954 | without a global view of what traps are enabled. @xref{Trap States}, | |
955 | for Guile's answer to this problem. | |
956 | ||
957 | Traps are created by calling procedures. Most of these procedures share | |
958 | a set of common keyword arguments, so rather than document them | |
959 | separately, we discuss them all together here: | |
960 | ||
961 | @table @code | |
962 | @item #:vm | |
963 | The VM to instrument. Defaults to the current thread's VM. | |
964 | @item #:closure? | |
965 | For traps that depend on the current frame's procedure, this argument | |
966 | specifies whether to trap on the only the specific procedure given, or | |
967 | on any closure that has the given procedure's code. Defaults to | |
968 | @code{#f}. | |
969 | @item #:current-frame | |
970 | For traps that enable more hooks depending on their dynamic context, | |
971 | this argument gives the current frame that the trap is running in. | |
972 | Defaults to @code{#f}. | |
973 | @end table | |
974 | ||
63e36ea6 AW |
975 | To have access to these procedures, you'll need to have imported the |
976 | @code{(system vm traps)} module: | |
977 | ||
978 | @lisp | |
979 | (use-modules (system vm traps)) | |
980 | @end lisp | |
981 | ||
6e069bbf | 982 | @deffn {Scheme Procedure} trap-at-procedure-call proc handler @ |
5db7c0bf AW |
983 | [#:vm] [#:closure?] |
984 | A trap that calls @var{handler} when @var{proc} is applied. | |
6e069bbf | 985 | @end deffn |
62ae9557 | 986 | |
6e069bbf | 987 | @deffn {Scheme Procedure} trap-in-procedure proc @ |
5db7c0bf AW |
988 | enter-handler exit-handler [#:current-frame] [#:vm] [#:closure?] |
989 | A trap that calls @var{enter-handler} when control enters @var{proc}, | |
990 | and @var{exit-handler} when control leaves @var{proc}. | |
6e069bbf AW |
991 | |
992 | Control can enter a procedure via: | |
5db7c0bf AW |
993 | @itemize |
994 | @item | |
995 | A procedure call. | |
996 | @item | |
997 | A return to a procedure's frame on the stack. | |
998 | @item | |
999 | A continuation returning directly to an application of this procedure. | |
1000 | @end itemize | |
6e069bbf AW |
1001 | |
1002 | Control can leave a procedure via: | |
5db7c0bf AW |
1003 | @itemize |
1004 | @item | |
1005 | A normal return from the procedure. | |
1006 | @item | |
1007 | An application of another procedure. | |
1008 | @item | |
1009 | An invocation of a continuation. | |
1010 | @item | |
1011 | An abort. | |
1012 | @end itemize | |
62ae9557 NJ |
1013 | @end deffn |
1014 | ||
6e069bbf | 1015 | @deffn {Scheme Procedure} trap-instructions-in-procedure proc @ |
5db7c0bf AW |
1016 | next-handler exit-handler [#:current-frame] [#:vm] [#:closure?] |
1017 | A trap that calls @var{next-handler} for every instruction executed in | |
1018 | @var{proc}, and @var{exit-handler} when execution leaves @var{proc}. | |
62ae9557 NJ |
1019 | @end deffn |
1020 | ||
6e069bbf | 1021 | @deffn {Scheme Procedure} trap-at-procedure-ip-in-range proc range @ |
5db7c0bf AW |
1022 | handler [#:current-frame] [#:vm] [#:closure?] |
1023 | A trap that calls @var{handler} when execution enters a range of | |
1024 | instructions in @var{proc}. @var{range} is a simple of pairs, | |
1025 | @code{((@var{start} . @var{end}) ...)}. The @var{start} addresses are | |
1026 | inclusive, and @var{end} addresses are exclusive. | |
6e069bbf | 1027 | @end deffn |
62ae9557 | 1028 | |
6e069bbf | 1029 | @deffn {Scheme Procedure} trap-at-source-location file user-line handler @ |
5db7c0bf AW |
1030 | [#:current-frame] [#:vm] |
1031 | A trap that fires when control reaches a given source location. The | |
1032 | @var{user-line} parameter is one-indexed, as a user counts lines, | |
1033 | instead of zero-indexed, as Guile counts lines. | |
6e069bbf | 1034 | @end deffn |
62ae9557 | 1035 | |
5db7c0bf AW |
1036 | @deffn {Scheme Procedure} trap-frame-finish frame @ |
1037 | return-handler abort-handler [#:vm] | |
1038 | A trap that fires when control leaves the given frame. @var{frame} | |
1039 | should be a live frame in the current continuation. @var{return-handler} | |
1040 | will be called on a normal return, and @var{abort-handler} on a nonlocal | |
1041 | exit. | |
6e069bbf | 1042 | @end deffn |
62ae9557 | 1043 | |
6e069bbf | 1044 | @deffn {Scheme Procedure} trap-in-dynamic-extent proc @ |
5db7c0bf AW |
1045 | enter-handler return-handler abort-handler [#:vm] [#:closure?] |
1046 | A more traditional dynamic-wind trap, which fires @var{enter-handler} | |
1047 | when control enters @var{proc}, @var{return-handler} on a normal return, | |
1048 | and @var{abort-handler} on a nonlocal exit. | |
1049 | ||
1050 | Note that rewinds are not handled, so there is no rewind handler. | |
62ae9557 NJ |
1051 | @end deffn |
1052 | ||
6e069bbf | 1053 | @deffn {Scheme Procedure} trap-calls-in-dynamic-extent proc @ |
5db7c0bf AW |
1054 | apply-handler return-handler [#:current-frame] [#:vm] [#:closure?] |
1055 | A trap that calls @var{apply-handler} every time a procedure is applied, | |
1056 | and @var{return-handler} for returns, but only during the dynamic extent | |
1057 | of an application of @var{proc}. | |
62ae9557 NJ |
1058 | @end deffn |
1059 | ||
6e069bbf | 1060 | @deffn {Scheme Procedure} trap-instructions-in-dynamic-extent proc @ |
5db7c0bf | 1061 | next-handler [#:current-frame] [#:vm] [#:closure?] |
ecb87335 | 1062 | A trap that calls @var{next-handler} for all retired instructions within |
5db7c0bf | 1063 | the dynamic extent of a call to @var{proc}. |
62ae9557 NJ |
1064 | @end deffn |
1065 | ||
6e069bbf | 1066 | @deffn {Scheme Procedure} trap-calls-to-procedure proc @ |
5db7c0bf AW |
1067 | apply-handler return-handler [#:vm] |
1068 | A trap that calls @var{apply-handler} whenever @var{proc} is applied, | |
1069 | and @var{return-handler} when it returns, but with an additional | |
1070 | argument, the call depth. | |
1071 | ||
1072 | That is to say, the handlers will get two arguments: the frame in | |
1073 | question, and the call depth (a non-negative integer). | |
62ae9557 NJ |
1074 | @end deffn |
1075 | ||
5db7c0bf AW |
1076 | @deffn {Scheme Procedure} trap-matching-instructions frame-pred handler [#:vm] |
1077 | A trap that calls @var{frame-pred} at every instruction, and if | |
1078 | @var{frame-pred} returns a true value, calls @var{handler} on the | |
1079 | frame. | |
62ae9557 NJ |
1080 | @end deffn |
1081 | ||
6e069bbf AW |
1082 | @node Tracing Traps |
1083 | @subsubsection Tracing Traps | |
62ae9557 | 1084 | |
6e069bbf AW |
1085 | The @code{(system vm trace)} module defines a number of traps for |
1086 | tracing of procedure applications. When a procedure is @dfn{traced}, it | |
1087 | means that every call to that procedure is reported to the user during a | |
1088 | program run. The idea is that you can mark a collection of procedures | |
1089 | for tracing, and Guile will subsequently print out a line of the form | |
62ae9557 NJ |
1090 | |
1091 | @lisp | |
6e069bbf | 1092 | | | (@var{procedure} @var{args} @dots{}) |
62ae9557 NJ |
1093 | @end lisp |
1094 | ||
6e069bbf AW |
1095 | whenever a marked procedure is about to be applied to its arguments. |
1096 | This can help a programmer determine whether a function is being called | |
1097 | at the wrong time or with the wrong set of arguments. | |
1098 | ||
1099 | In addition, the indentation of the output is useful for demonstrating | |
1100 | how the traced applications are or are not tail recursive with respect | |
1101 | to each other. Thus, a trace of a non-tail recursive factorial | |
1102 | implementation looks like this: | |
1103 | ||
1104 | @lisp | |
1105 | scheme@@(guile-user)> (define (fact1 n) | |
1106 | (if (zero? n) 1 | |
1107 | (* n (fact1 (1- n))))) | |
1108 | scheme@@(guile-user)> ,trace (fact1 4) | |
1109 | trace: (fact1 4) | |
1110 | trace: | (fact1 3) | |
1111 | trace: | | (fact1 2) | |
1112 | trace: | | | (fact1 1) | |
1113 | trace: | | | | (fact1 0) | |
1114 | trace: | | | | 1 | |
1115 | trace: | | | 1 | |
1116 | trace: | | 2 | |
1117 | trace: | 6 | |
1118 | trace: 24 | |
1119 | @end lisp | |
1120 | ||
1121 | While a typical tail recursive implementation would look more like this: | |
1122 | ||
1123 | @lisp | |
1124 | scheme@@(guile-user)> (define (facti acc n) | |
1125 | (if (zero? n) acc | |
1126 | (facti (* n acc) (1- n)))) | |
1127 | scheme@@(guile-user)> (define (fact2 n) (facti 1 n)) | |
1128 | scheme@@(guile-user)> ,trace (fact2 4) | |
1129 | trace: (fact2 4) | |
1130 | trace: (facti 1 4) | |
1131 | trace: (facti 4 3) | |
1132 | trace: (facti 12 2) | |
1133 | trace: (facti 24 1) | |
1134 | trace: (facti 24 0) | |
1135 | trace: 24 | |
1136 | @end lisp | |
1137 | ||
90729e71 AW |
1138 | The low-level traps below (@pxref{Low-Level Traps}) share some common |
1139 | options: | |
1140 | ||
1141 | @table @code | |
1142 | @item #:width | |
1143 | The maximum width of trace output. Trace printouts will try not to | |
1144 | exceed this column, but for highly nested procedure calls, it may be | |
1145 | unavoidable. Defaults to 80. | |
1146 | @item #:vm | |
1147 | The VM on which to add the traps. Defaults to the current thread's VM. | |
1148 | @item #:prefix | |
1149 | A string to print out before each trace line. As seen above in the | |
1150 | examples, defaults to @code{"trace: "}. | |
1151 | @end table | |
1152 | ||
63e36ea6 AW |
1153 | To have access to these procedures, you'll need to have imported the |
1154 | @code{(system vm trace)} module: | |
1155 | ||
1156 | @lisp | |
1157 | (use-modules (system vm trace)) | |
1158 | @end lisp | |
1159 | ||
90729e71 AW |
1160 | @deffn {Scheme Procedure} trace-calls-to-procedure proc @ |
1161 | [#:width] [#:vm] [#:prefix] | |
1162 | Print a trace at applications of and returns from @var{proc}. | |
6e069bbf AW |
1163 | @end deffn |
1164 | ||
90729e71 AW |
1165 | @deffn {Scheme Procedure} trace-calls-in-procedure proc @ |
1166 | [#:width] [#:vm] [#:prefix] | |
1167 | Print a trace at all applications and returns within the dynamic extent | |
1168 | of calls to @var{proc}. | |
6e069bbf AW |
1169 | @end deffn |
1170 | ||
90729e71 AW |
1171 | @deffn {Scheme Procedure} trace-instructions-in-procedure proc [#:width] [#:vm] |
1172 | Print a trace at all instructions executed in the dynamic extent of | |
1173 | calls to @var{proc}. | |
6e069bbf AW |
1174 | @end deffn |
1175 | ||
1176 | In addition, Guile defines a procedure to call a thunk, tracing all | |
1177 | procedure calls and returns within the thunk. | |
1178 | ||
994d87be BT |
1179 | @deffn {Scheme Procedure} call-with-trace thunk [#:calls?=#t] @ |
1180 | [#:instructions?=#f] @ | |
a222cbc9 | 1181 | [#:width=80] |
6e069bbf AW |
1182 | Call @var{thunk}, tracing all execution within its dynamic extent. |
1183 | ||
1184 | If @var{calls?} is true, Guile will print a brief report at each | |
1185 | procedure call and return, as given above. | |
1186 | ||
1187 | If @var{instructions?} is true, Guile will also print a message each | |
1188 | time an instruction is executed. This is a lot of output, but it is | |
1189 | sometimes useful when doing low-level optimization. | |
1190 | ||
1191 | Note that because this procedure manipulates the VM trace level | |
1192 | directly, it doesn't compose well with traps at the REPL. | |
1193 | @end deffn | |
1194 | ||
1195 | @xref{Profile Commands}, for more information on tracing at the REPL. | |
1196 | ||
1197 | @node Trap States | |
1198 | @subsubsection Trap States | |
1199 | ||
de03880a AW |
1200 | When multiple traps are present in a system, we begin to have a |
1201 | bookkeeping problem. How are they named? How does one disable, enable, | |
1202 | or delete them? | |
1203 | ||
1204 | Guile's answer to this is to keep an implicit per-thread @dfn{trap | |
1205 | state}. The trap state object is not exposed to the user; rather, API | |
1206 | that works on trap states fetches the current trap state from the | |
1207 | dynamic environment. | |
1208 | ||
6b1d1af7 | 1209 | Traps are identified by integers. A trap can be enabled, disabled, or |
de03880a AW |
1210 | removed, and can have an associated user-visible name. |
1211 | ||
63e36ea6 AW |
1212 | These procedures have their own module: |
1213 | ||
1214 | @lisp | |
1215 | (use-modules (system vm trap-state)) | |
1216 | @end lisp | |
1217 | ||
de03880a AW |
1218 | @deffn {Scheme Procedure} add-trap! trap name |
1219 | Add a trap to the current trap state, associating the given @var{name} | |
1220 | with it. Returns a fresh trap identifier (an integer). | |
1221 | ||
63e36ea6 AW |
1222 | Note that usually the more specific functions detailed in |
1223 | @ref{High-Level Traps} are used in preference to this one. | |
de03880a AW |
1224 | @end deffn |
1225 | ||
6e069bbf | 1226 | @deffn {Scheme Procedure} list-traps |
de03880a AW |
1227 | List the current set of traps, both enabled and disabled. Returns a list |
1228 | of integers. | |
6e069bbf AW |
1229 | @end deffn |
1230 | ||
1231 | @deffn {Scheme Procedure} trap-name idx | |
de03880a AW |
1232 | Returns the name associated with trap @var{idx}, or @code{#f} if there |
1233 | is no such trap. | |
6e069bbf AW |
1234 | @end deffn |
1235 | ||
1236 | @deffn {Scheme Procedure} trap-enabled? idx | |
de03880a AW |
1237 | Returns @code{#t} if trap @var{idx} is present and enabled, or @code{#f} |
1238 | otherwise. | |
6e069bbf AW |
1239 | @end deffn |
1240 | ||
1241 | @deffn {Scheme Procedure} enable-trap! idx | |
de03880a | 1242 | Enables trap @var{idx}. |
6e069bbf AW |
1243 | @end deffn |
1244 | ||
1245 | @deffn {Scheme Procedure} disable-trap! idx | |
de03880a | 1246 | Disables trap @var{idx}. |
6e069bbf AW |
1247 | @end deffn |
1248 | ||
1249 | @deffn {Scheme Procedure} delete-trap! idx | |
de03880a | 1250 | Removes trap @var{idx}, disabling it first, if necessary. |
6e069bbf | 1251 | @end deffn |
62ae9557 | 1252 | |
63e36ea6 AW |
1253 | @node High-Level Traps |
1254 | @subsubsection High-Level Traps | |
1255 | ||
1256 | The low-level trap API allows one to make traps that call procedures, | |
1257 | and the trap state API allows one to keep track of what traps are | |
1258 | there. But neither of these APIs directly helps you when you want to | |
1259 | set a breakpoint, because it's unclear what to do when the trap fires. | |
1260 | Do you enter a debugger, or mail a summary of the situation to your | |
1261 | great-aunt, or what? | |
1262 | ||
1263 | So for the common case in which you just want to install breakpoints, | |
6b1d1af7 AW |
1264 | and then have them all result in calls to one parameterizable procedure, |
1265 | we have the high-level trap interface. | |
63e36ea6 AW |
1266 | |
1267 | Perhaps we should have started this section with this interface, as it's | |
1268 | clearly the one most people should use. But as its capabilities and | |
1269 | limitations proceed from the lower layers, we felt that the | |
6b1d1af7 | 1270 | character-building exercise of building a mental model might be helpful. |
62ae9557 | 1271 | |
63e36ea6 AW |
1272 | These procedures share a module with trap states: |
1273 | ||
1274 | @lisp | |
1275 | (use-modules (system vm trap-state)) | |
1276 | @end lisp | |
62ae9557 | 1277 | |
6e069bbf | 1278 | @deffn {Scheme Procedure} with-default-trap-handler handler thunk |
63e36ea6 AW |
1279 | Call @var{thunk} in a dynamic context in which @var{handler} is the |
1280 | current trap handler. | |
1281 | ||
1282 | Additionally, during the execution of @var{thunk}, the VM trace level | |
1283 | (@pxref{VM Hooks}) is set to the number of enabled traps. This ensures | |
1284 | that traps will in fact fire. | |
1285 | ||
1286 | @var{handler} may be @code{#f}, in which case VM hooks are not enabled | |
1287 | as they otherwise would be, as there is nothing to handle the traps. | |
62ae9557 NJ |
1288 | @end deffn |
1289 | ||
63e36ea6 AW |
1290 | The trace-level-setting behavior of @code{with-default-trap-handler} is |
1291 | one of its more useful aspects, but if you are willing to forgo that, | |
1292 | and just want to install a global trap handler, there's a function for | |
1293 | that too: | |
1294 | ||
6e069bbf | 1295 | @deffn {Scheme Procedure} install-trap-handler! handler |
63e36ea6 | 1296 | Set the current thread's trap handler to @var{handler}. |
6e069bbf AW |
1297 | @end deffn |
1298 | ||
63e36ea6 AW |
1299 | Trap handlers are called when traps installed by procedures from this |
1300 | module fire. The current ``consumer'' of this API is Guile's REPL, but | |
1301 | one might easily imagine other trap handlers being used to integrate | |
1302 | with other debugging tools. | |
6e069bbf | 1303 | |
63e36ea6 AW |
1304 | @cindex Breakpoints |
1305 | @cindex Setting breakpoints | |
6e069bbf | 1306 | @deffn {Scheme Procedure} add-trap-at-procedure-call! proc |
63e36ea6 AW |
1307 | Install a trap that will fire when @var{proc} is called. |
1308 | ||
1309 | This is a breakpoint. | |
62ae9557 NJ |
1310 | @end deffn |
1311 | ||
63e36ea6 AW |
1312 | @cindex Tracepoints |
1313 | @cindex Setting tracepoints | |
6e069bbf | 1314 | @deffn {Scheme Procedure} add-trace-at-procedure-call! proc |
63e36ea6 AW |
1315 | Install a trap that will print a tracing message when @var{proc} is |
1316 | called. @xref{Tracing Traps}, for more information. | |
1317 | ||
1318 | This is a tracepoint. | |
62ae9557 NJ |
1319 | @end deffn |
1320 | ||
6e069bbf | 1321 | @deffn {Scheme Procedure} add-trap-at-source-location! file user-line |
63e36ea6 AW |
1322 | Install a trap that will fire when control reaches the given source |
1323 | location. @var{user-line} is one-indexed, as users count lines, instead | |
1324 | of zero-indexed, as Guile counts lines. | |
1325 | ||
1326 | This is a source breakpoint. | |
62ae9557 NJ |
1327 | @end deffn |
1328 | ||
6e069bbf | 1329 | @deffn {Scheme Procedure} add-ephemeral-trap-at-frame-finish! frame handler |
63e36ea6 AW |
1330 | Install a trap that will call @var{handler} when @var{frame} finishes |
1331 | executing. The trap will be removed from the trap state after firing, or | |
1332 | on nonlocal exit. | |
1333 | ||
1334 | This is a finish trap, used to implement the ``finish'' REPL command. | |
62ae9557 NJ |
1335 | @end deffn |
1336 | ||
63e36ea6 AW |
1337 | @deffn {Scheme Procedure} add-ephemeral-stepping-trap! frame handler [#:into?] [#:instruction?] |
1338 | Install a trap that will call @var{handler} after stepping to a | |
1339 | different source line or instruction. The trap will be removed from the | |
1340 | trap state after firing, or on nonlocal exit. | |
1341 | ||
1342 | If @var{instruction?} is false (the default), the trap will fire when | |
1343 | control reaches a new source line. Otherwise it will fire when control | |
1344 | reaches a new instruction. | |
1345 | ||
1346 | Additionally, if @var{into?} is false (not the default), the trap will | |
1347 | only fire for frames at or prior to the given frame. If @var{into?} is | |
1348 | true (the default), the trap may step into nested procedure | |
1349 | invocations. | |
1350 | ||
1351 | This is a stepping trap, used to implement the ``step'', ``next'', | |
1352 | ``step-instruction'', and ``next-instruction'' REPL commands. | |
62ae9557 NJ |
1353 | @end deffn |
1354 | ||
1355 | ||
07d83abe MV |
1356 | @c Local Variables: |
1357 | @c TeX-master: "guile.texi" | |
1358 | @c End: |