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