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