% Copyright 2005-2017 Cisco Systems, Inc. % % Licensed under the Apache License, Version 2.0 (the "License"); % you may not use this file except in compliance with the License. % You may obtain a copy of the License at % % http://www.apache.org/licenses/LICENSE-2.0 % % Unless required by applicable law or agreed to in writing, software % distributed under the License is distributed on an "AS IS" BASIS, % WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. % See the License for the specific language governing permissions and % limitations under the License. \chapter{Debugging\label{CHPTDEBUG}} {\ChezScheme} has several features that support debugging. In addition to providing error messages when fully type-checked code is run, {\ChezScheme} also permits tracing of procedure calls, interruption of any computation, redefinition of exception and interrupt handlers, and inspection of any object, including the continuations of exceptions and interrupts. Programmers new to Scheme or {\ChezScheme}, and even more experienced Scheme programmers, might want to consult the tutorial ``How to Debug Chez Scheme Programs.'' HTML and PDF versions % of the tutorial are available at \hyperlink{http://www.cs.indiana.edu/chezscheme/debug/}{http://www.cs.indiana.edu/chezscheme/debug/}. \section{Tracing\label{SECTDEBUGTRACING}} Tracing is one of the most useful mechanisms for debugging Scheme programs. {\ChezScheme} permits any primitive or user-defined procedure to be traced. The trace package prints the arguments and return values for each traced procedure with a compact indentation mechanism that shows the nesting depth of calls. The distinction between tail calls and nontail calls is reflected properly by an increase in indentation for nontail calls only. For nesting depths of 10 or greater, a number in brackets is used in place of indentation to signify nesting depth. This section covers the mechanisms for tracing procedures and controlling trace output. %---------------------------------------------------------------------------- \entryheader \formdef{trace-lambda}{\categorysyntax}{(trace-lambda \var{name} \var{formals} \var{body_1} \var{body_2} \dots)} \returns a traced procedure \listlibraries \endentryheader \noindent \index{\scheme{lambda}}A \scheme{trace-lambda} expression is equivalent to a \scheme{lambda} expression with the same formals and body except that trace information is printed to the trace output port whenever the procedure is invoked, using \var{name} to identify the procedure. The trace information shows the value of the arguments passed to the procedure and the values returned by the procedure, with indentation to show the nesting of calls. The traced procedure \index{\scheme{half}}\scheme{half} defined below returns the integer quotient of its argument and 2. \schemedisplay (define half (trace-lambda half (x) (cond [(zero? x) 0] [(odd? x) (half (- x 1))] [(even? x) (+ (half (- x 1)) 1)]))) \endschemedisplay \noindent A trace of the call \scheme{(half 5)}, which returns 2, is shown below. \schemedisplay |(half 5) |(half 4) | (half 3) | (half 2) | |(half 1) | |(half 0) | |0 | 1 |2 \endschemedisplay \noindent This example highlights the proper treatment of tail and nontail calls by the trace package. Since \scheme{half} tail calls itself when its argument is odd, the call \scheme{(half 4)} appears at the same level of indentation as the call \scheme{(half 5)}. Furthermore, since the return values of \scheme{(half 5)} and \scheme{(half 4)} are necessarily the same, only one return value is shown for both calls. %---------------------------------------------------------------------------- \entryheader \formdef{trace-case-lambda}{\categorysyntax}{(trace-case-lambda \var{name} \var{clause} \dots)} \returns a traced procedure \listlibraries \endentryheader \noindent \index{\scheme{case-lambda}}A \scheme{trace-case-lambda} expression is equivalent to a \scheme{case-lambda} expression with the same clauses except that trace information is printed to the trace output port whenever the procedure is invoked, using \var{name} to identify the procedure. The trace information shows the value of the arguments passed to the procedure and the values returned by the procedure, with indentation to show the nesting of calls. %---------------------------------------------------------------------------- \entryheader \formdef{trace-let}{\categorysyntax}{(trace-let \var{name} ((\var{var} \var{expr}) \dots) \var{body_1} \var{body_2} \dots)} \returns the values of the body \scheme{\var{body_1} \var{body_2} \dots} \listlibraries \endentryheader \noindent \index{\scheme{let}}A \scheme{trace-let} expression is equivalent to a named \scheme{let} expression with the same name, bindings, and body except that trace information is printed to the trace output port on entry or reentry (via invocation of the procedure bound to \scheme{name}) into the \scheme{trace-let} expression. A \scheme{trace-let} expression of the form \schemedisplay (trace-let \var{name} ([\var{var} \var{expr}] \dots) \var{body_1} \var{body_2} \dots) \endschemedisplay \noindent can be rewritten in terms of \scheme{trace-lambda} as follows: \schemedisplay ((letrec ([\var{name} (trace-lambda \var{name} (\var{var} \dots) \var{body_1} \var{body_2} \dots)]) \var{name}) \var{expr} \dots) \endschemedisplay \noindent \scheme{trace-let} may be used to trace ordinary \scheme{let} expressions as well as \scheme{let} expressions as long as the name inserted along with the \scheme{trace-let} keyword in place of \scheme{let} does not appear free within the body of the \scheme{let} expression. It is also sometimes useful to insert a \scheme{trace-let} expression into a program simply to display the value of an arbitrary expression at the current trace indentation. For example, a call to the following variant of \scheme{half} \schemedisplay (define half (trace-lambda half (x) (cond [(zero? x) 0] [(odd? x) (half (trace-let decr-value () (- x 1)))] [(even? x) (+ (half (- x 1)) 1)]))) \endschemedisplay \noindent with argument 5 results in the trace: \schemedisplay |(half 5) | (decr-value) | 4 |(half 4) | (half 3) | |(decr-value) | |2 | (half 2) | |(half 1) | | (decr-value) | | 0 | |(half 0) | 1 |2 \endschemedisplay %---------------------------------------------------------------------------- \entryheader \formdef{trace-do}{\categorysyntax}{(trace-do ((\var{var} \var{init} \var{update}) \dots) (\var{test} \var{result} \dots) \var{expr} \dots)} \returns the values of the last \var{result} expression \listlibraries \endentryheader \noindent \index{\scheme{do}}A \scheme{trace-do} expression is equivalent to a \scheme{do} expression with the same subforms, except that trace information is printed to the trace output port, showing the values of \scheme{\var{var} \dots} and each iteration and the final value of the loop on termination. For example, the expression \schemedisplay (trace-do ([old '(a b c) (cdr old)] [new '() (cons (car old) new)]) ((null? old) new)) \endschemedisplay produces the trace \schemedisplay |(do (a b c) ()) |(do (b c) (a)) |(do (c) (b a)) |(do () (c b a)) |(c b a) \endschemedisplay and returns \scheme{(c b a)}. %---------------------------------------------------------------------------- \entryheader \formdef{trace}{\categorysyntax}{(trace \var{var_1} \var{var_2} \dots)} \returns a list of \scheme{\var{var_1} \var{var_2} \dots} \formdef{trace}{\categorysyntax}{(trace)} \returns a list of all currently traced top-level variables \listlibraries \endentryheader \noindent In the first form, \scheme{trace} reassigns the top-level values of \scheme{\var{var_1} \var{var_2} \dots}, whose values must be procedures, to equivalent procedures that display trace information in the manner of \scheme{trace-lambda}. \scheme{trace} works by encapsulating the old value of each var in a traced procedure. It could be defined approximately as follows. (The actual version records and returns information about traced variables.) \schemedisplay (define-syntax trace (syntax-rules () [(_ var ...) (begin (set-top-level-value! 'var (let ([p (top-level-value 'var)]) (trace-lambda var args (apply p args)))) ...)])) \endschemedisplay Tracing for a procedure traced in this manner may be disabled via \scheme{untrace} (see below), an assignment of the corresponding variable to a different, untraced value, or a subsequent use of \scheme{trace} for the same variable. Because the value is traced and not the binding, however, a traced value obtained before tracing is disabled and retained after tracing is disabled will remain traced. \scheme{trace} without subexpressions evaluates to a list of all currently traced variables. A variable is currently traced if it has been traced and not subsequently untraced or assigned to a different value. The following transcript demonstrates the use of \scheme{trace} in an interactive session. \schemedisplay > (define half (lambda (x) (cond [(zero? x) 0] [(odd? x) (half (- x 1))] [(even? x) (+ (half (- x 1)) 1)]))) > (half 5) 2 > (trace half) (half) > (half 5) |(half 5) |(half 4) | (half 3) | (half 2) | |(half 1) | |(half 0) | |0 | 1 |2 2 > (define traced-half half) > (untrace half) (half) > (half 2) 1 > (traced-half 2) |(half 2) |1 1 \endschemedisplay %---------------------------------------------------------------------------- \entryheader \formdef{untrace}{\categorysyntax}{(untrace \var{var_1} \var{var_2} \dots)} \formdef{untrace}{\categorysyntax}{(untrace)} \returns a list of untraced variables \listlibraries \endentryheader \noindent \scheme{untrace} restores the original (pre-\scheme{trace}) top-level values of each currently traced variable in \scheme{\var{var_1} \var{var_2} \dots}, effectively disabling the tracing of the values of these variables. Any variable in \scheme{\var{var_1} \var{var_2} \dots} that is not currently traced is ignored. If \scheme{untrace} is called without arguments, the values of all currently traced variables are restored. The following transcript demonstrates the use of \scheme{trace} and \scheme{untrace} in an interactive session to debug an incorrect procedure definition. \schemedisplay > (define square-minus-one (lambda (x) (- (* x x) 2))) > (square-minus-one 3) 7 > (trace square-minus-one * -) (square-minus-one * -) > (square-minus-one 3) |(square-minus-one 3) | (* 3 3) | 9 |(- 9 2) |7 7 > (define square-minus-one (lambda (x) (- (* x x) 1))) ; change the 2 to 1 > (trace) (- *) > (square-minus-one 3) |(* 3 3) |9 |(- 9 1) |8 8 > (untrace square-minus-one) () > (untrace * -) (- *) > (square-minus-one 3) 8 \endschemedisplay \noindent The first call to \scheme{square-minus-one} indicates there is an error, the second (traced) call indicates the step at which the error occurs, the third call demonstrates that the fix works, and the fourth call demonstrates that \scheme{untrace} does not wipe out the fix. %---------------------------------------------------------------------------- \entryheader \formdef{trace-output-port}{\categorythreadparameter}{trace-output-port} \listlibraries \endentryheader \noindent \scheme{trace-output-port} is a parameter that determines the output port to which tracing information is sent. When called with no arguments, \scheme{trace-output-port} returns the current trace output port. When called with one argument, which must be a textual output port, \scheme{trace-output-port} changes the value of the current trace output port. %---------------------------------------------------------------------------- \entryheader \formdef{trace-print}{\categorythreadparameter}{trace-print} \listlibraries \endentryheader \noindent The value of \scheme{trace-print} must be a procedure of two arguments, an object and an output port. The trace package uses the value of \scheme{trace-print} to print the arguments and return values for each call to a traced procedure. \scheme{trace-print} is set to \scheme{pretty-print} by default. The trace package sets \index{\scheme{pretty-initial-indent}}\scheme{pretty-initial-indent} to an appropriate value for the current nesting level before calling the value of \scheme{trace-print} so that multiline output can be indented properly. %---------------------------------------------------------------------------- \entryheader \formdef{trace-define}{\categorysyntax}{(trace-define \var{var} \var{expr})} \formdef{trace-define}{\categorysyntax}{(trace-define (\var{var} . \var{idspec}) \var{body_1} \var{body_2} \dots)} \returns unspecified \listlibraries \endentryheader \noindent \scheme{trace-define} is a convenient shorthand for defining variables bound to traced procedures of the same name. The first form is equivalent to \schemedisplay (define \var{var} (let ([x \var{expr}]) (trace-lambda \var{var} args (apply x args)))) \endschemedisplay \noindent and the second is equivalent to \schemedisplay (define \var{var} (trace-lambda \var{var} \var{idspec} \var{body_1} \var{body_2} \dots)) \endschemedisplay \noindent In the former case, \var{expr} must evaluate to a procedure. \schemedisplay > (let () (trace-define plus (lambda (x y) (+ x y))) (list (plus 3 4) (+ 5 6))) |(plus 3 4) |7 (7 11) \endschemedisplay %---------------------------------------------------------------------------- \entryheader \formdef{trace-define-syntax}{\categorysyntax}{(trace-define-syntax \var{keyword} \var{expr})} \returns unspecified \listlibraries \endentryheader \noindent \scheme{trace-define-syntax} traces the input and output to the transformer value of \var{expr}, stripped of the contextual information used by the expander to maintain lexical scoping. \schemedisplay > (trace-define-syntax let* (syntax-rules () [(_ () b1 b2 ...) (let () b1 b2 ...)] [(_ ((x e) m ...) b1 b2 ...) (let ((x e)) (let* (m ...) b1 b2 ...))])) > (let* ([x 3] [y (+ x x)]) (list x y)) |(let* (let* [(x 3) (y (+ x x))] [list x y])) |(let ([x 3]) (let* ([y (+ x x)]) (list x y))) |(let* (let* [(y (+ x x))] [list x y])) |(let ([y (+ x x)]) (let* () (list x y))) |(let* (let* () [list x y])) |(let () (list x y)) (3 6) \endschemedisplay \noindent Without contextual information, the displayed forms are more readable but less precise, since different identifiers with the same name are indistinguishable, as shown in the example below. \schemedisplay > (let ([x 0]) (trace-define-syntax a (syntax-rules () [(_ y) (eq? x y)])) (let ([x 1]) (a x))) |(a (a x)) |(eq? x x) #f \endschemedisplay \section{The Interactive Debugger\label{SECTDEBUGINTERACTIVE}} The interactive debugger is entered as a result of a call to the procedure \scheme{debug} after an exception is handled by the default exception handler. It can also be entered directly from the default exception handler, for serious or non-warning conditions, if the parameter \scheme{debug-on-exception} is true. Within the debugger, the command ``?'' lists the debugger command options. These include commands to: \begin{itemize} \item inspect the raise continuation, \item display the condition, \item inspect the condition, and \item exit the debugger. \end{itemize} The raise continuation is the continuation encapsulated within the condition, if any. The standard exception reporting procedures and forms \scheme{assert}, \scheme{assertion-violation}, and \scheme{error} as well as the {\ChezScheme} procedures \scheme{assertion-violationf}, \scheme{errorf}, and \scheme{syntax-error} all raise exceptions with conditions that encapsulate the continuations of their calls, allowing the programmer to inspect the frames of pending calls at the point of a violation, error, or failed assertion. A variant of the interactive debugger, the break handler, is entered as the result of a keyboard interrupt handled by the default keyboard-interrupt handler or an explicit call to the procedure \scheme{break} handled by the default break handler. Again, the command ``?'' lists the command options. These include commands to: \begin{itemize} \item exit the break handler and continue, \item reset to the current caf\'e, \item abort the entire Scheme session, \item enter a new caf\'e, \item inspect the current continuation, and \item display program statistics (run time and memory usage). \end{itemize} \noindent It is also usually possible to exit from the debugger or break handler by typing the end-of-file character (``control-D'' under Unix, ``control-Z'' under Windows). %---------------------------------------------------------------------------- \entryheader \formdef{debug}{\categoryprocedure}{(debug)} \returns does not return \listlibraries \endentryheader \noindent When the default exception handler receives a serious or non-warning condition, it displays the condition and resets to the current caf\'e. Before it resets, it saves the condition in the parameter \scheme{debug-condition}. The \scheme{debug} procedure may be used to inspect the condition. Whenever one of the built-in error-reporting mechanisms is used to raise an exception, the continuation at the point where the exception was raised can be inspected as well. More generally, \scheme{debug} allows the continuation contained within any continuation condition created by \scheme{make-continuation-condition} to be inspected. If the parameter \scheme{debug-on-exception} is set to \scheme{#t}, the default exception handler enters the debugger directly for all serious and non-warning conditions, delaying its reset until after the debugger exits. The \index{\scheme{--debug-on-exception} command-line option}\scheme{--debug-on-exception} command-line option may be used to set \scheme{debug-on-exception} to \scheme{#t} from the command line, which is particularly useful when debugging scripts or top-level programs run via the \index{\scheme{--script} command-line option}\scheme{--script} or \index{\scheme{--program} command-line option}\scheme{--program} command-line options. \section{The Interactive Inspector\label{SECTDEBUGINSPECTOR}} The \index{inspector}inspector may be called directly via the procedure \scheme{inspect} or indirectly from the debugger. It allows the programmer to examine circular objects, objects such as ports and procedures that do not have a reader syntax, and objects such as continuations and variables that are not directly accessible by the programmer, as well as ordinary printable Scheme objects. The primary intent of the inspector is examination, not alteration, of objects. The values of \index{assignable variables}assignable variables may be changed from within the inspector, however. Assignable variables are generally limited to those for which assignments occur in the source program. It is also possible to invoke arbitrary procedures (including mutation procedures such as \scheme{set-car!}) on an object. No mechanism is provided for altering objects that are inherently immutable, e.g., nonassignable variables, procedures, and bignums, since doing so can violate assumptions made by the compiler and run-time system. The user is presented with a prompt line that includes a printed representation of the current object, abbreviated if necessary to fit on the line. Various commands are provided for displaying objects and moving around inside of objects. On-line descriptions of the command options are provided. The command ``?'' displays commands that apply specifically to the current object. The command ``??'' displays commands that are always applicable. The command ``h'' provides a brief description of how to use the inspector. The end-of-file character or the command ``q'' exits the inspector. %---------------------------------------------------------------------------- \entryheader \formdef{inspect}{\categoryprocedure}{(inspect \var{obj})} \returns unspecified \listlibraries \endentryheader \noindent Invokes the inspector on \var{obj}, as described above. The commands recognized by the inspector are listed below, categorized by the type of the current object. \def\Itype#1 {\bigskip\noindent\textbf{#1 commands}\nobreak\medskip\nobreak} \def\Icmd#1{\medskip\noindent #1} \Itype{Generally applicable} \Icmd{\scheme{help} or \scheme{h}} displays a brief description of how to use the inspector. \Icmd{\scheme{?}} displays commands applicable to the current type of object. \Icmd{\scheme{??}} displays the generally applicable commands. \Icmd{\scheme{print} or \scheme{p}} prints the current object (using \scheme{pretty-print}). \Icmd{\scheme{write} or \scheme{w}} writes the current object (using \scheme{write}). \Icmd{\scheme{size}} writes the size in bytes occupied by the current object (determined via \index{\scheme{compute-size}}\scheme{compute-size}), including any objects accessible from the current object except those for which the size was previously requested during the same interactive inspector session. \Icmd{\scheme{find} \var{expr} [ \var{g} ]} evaluates \var{expr}, which should evaluate to a procedure of one argument, and searches (via \index{\scheme{make-object-finder}}\scheme{make-object-finder}) for the first occurrence of an object within the current object for which the predicate returns a true value, treating immediate values (e.g., fixnums), values in generations older than \var{g}, and values already visited during the search as leaves. If \var{g} is not unspecified, it defaults to the current maximum generation, i.e., the value of \scheme{collect-maximum-generation}. If specified, \var{g} must be an exact nonnegative integer less than or equal to the current maximum generation or the symbol \scheme{static} representing the static generation. If such an object is found, the inspector's focus moves to that object as if through a series of steps that lead from the current object to the located object, so that the \scheme{up} command can be used to determine where the object was found relative to the original object. \Icmd{\scheme{find-next}} repeats the last \scheme{find}, locating an occurrence not previously found, if any. \Icmd{\scheme{up} or \scheme{u} \var{n}} returns to the \var{nth} previous level. Used to move outwards in the structure of the inspected object. \var{n} defaults to 1. \Icmd{\scheme{top} or \scheme{t}} returns to the outermost level of the inspected object. \Icmd{\scheme{forward} or \scheme{f}} moves to the \var{nth} next expression. Used to move from one element to another of an object containing a sequence of elements, such as a list, vector, record, frame, or closure. \var{n} defaults to 1. \Icmd{\scheme{back} or \scheme{b}} moves to the \var{nth} previous expression. Used to move from one element to another of an object containing a sequence of elements, such as a list, vector, record, frame, or closure. \var{n} defaults to 1. \Icmd{\scheme{=>} \var{expr}} sends the current object to the procedure value of \var{expr}. \var{expr} may begin on the current or following line and may span multiple lines. \Icmd{\scheme{file} \var{path}} opens the source file at the specified path for listing. The parameter \scheme{source-directories} (Section~\ref{SECTSYSTEMSOURCE}) determines the set of directories searched for source files. \Icmd{\scheme{list} \var{line} \var{count}} lists \var{count} lines of the current source file (see \scheme{file}) starting at \var{line}. \var{line} defaults to the end of the previous set of lines listed and \var{count} defaults to ten or the number of lines previously listed. If \var{line} is negative, listing begins \var{line} lines before the previous set of lines listed. \Icmd{\scheme{files}} shows the currently open source files. \Icmd{\scheme{mark} or \scheme{m} \var{m}} marks the current location with the symbolic mark \var{m}. If \var{m} is not specified, the current location is marked with a unique default mark. \Icmd{\scheme{goto} or \scheme{g} \var{m}} returns to the location marked \var{m}. If \var{m} is not specified, the inspector returns to the location marked with the default mark. \Icmd{\scheme{new-cafe} or \scheme{n}} enters a new read-eval-print loop (caf\'e), giving access to the normal top-level environment. \Icmd{\scheme{quit} or \scheme{q}} exits from the inspector. \Icmd{\scheme{reset} or \scheme{r}} resets to the current caf\'e. \Icmd{\scheme{abort} or \scheme{a} \var{x}} aborts from Scheme with exit status \var{x}, which defaults to -1. \Itype{Continuation} \Icmd{\scheme{show-frames} or \scheme{sf}} shows the next \var{n} frames. If \var{n} is not specified, all frames are displayed. \Icmd{\scheme{depth}} displays the number of frames in the continuation. \Icmd{\scheme{down} or \scheme{d} \var{n}} move to the \var{nth} frame down in the continuation. \var{n} defaults to 1. \Icmd{\scheme{show} or \scheme{s}} shows the continuation (next frame) and, if available, the calling procedure source, the pending call source, the closure, and the frame and free-variable values. Source is available only if generation of inspector information was enabled during compilation of the corresponding lambda expression. \Icmd{\scheme{show-local} or \scheme{sl}} is like \scheme{show} or~\scheme{s} except that free variable values are not shown. (If present, free variable values can be found by inspecting the closure.) \Icmd{\scheme{length} or \scheme{l}} displays the number of elements in the topmost frame of the continuation. \Icmd{\scheme{ref} or \scheme{r}} moves to the \var{nth} or named frame element. \var{n} defaults to 0. If multiple elements have the same name, only one is accessible by name, and the others must be accessed by number. \Icmd{\scheme{code} or \scheme{c}} moves to the source for the calling procedure. \Icmd{\scheme{call}} moves to the source for the pending call. \Icmd{\scheme{file}} opens the source file containing the pending call, if known. The parameter \scheme{source-directories} (Section~\ref{SECTSYSTEMSOURCE}) determines the list of source directories searched for source files identified by relative path names. For absolute pathnames starting with a \scheme{/} (or \scheme{\} or a directory specifier under Windows), the inspector tries the absolute pathname first, then looks for the last (filename) component of the path in the list of source directories. For pathnames starting with \scheme{./} (or \scheme{.\} under Windows) or \scheme{../} (or \scheme{..\} under Windows), the inspector looks in \scheme{"."} or \scheme{".."} first, as appropriate, then for the entire \scheme{.}- or \scheme{..}-prefixed pathname in the source directories, then for the last (filename) component in the source directories. For other (relative) pathnames, the inspector looks for the entire relative pathname in the list of source directories, then the last (filename) component in the list of source directories. If a file by the same name as but different contents from the original source file is found during this process, it will be skipped over. This typically happens because the file has been modified since it was compiled. Pass an explicit filename argument to force opening of a particular file (see the generally applicable commands above). \Icmd{\scheme{eval} or \scheme{e} \var{expr}} evaluates the expression \var{expr} in an environment containing bindings for the elements of the frame. Within the evaluated expression, the value of each frame element \var{n} is accessible via the variable \scheme{%\var{n}}. Named elements are accessible via their names as well. Names are available only if generation of inspector information was enabled during compilation of the corresponding lambda expression. \Icmd{\scheme{set!} or \scheme{!} \var{n} \var{e}} sets the value of the \var{nth} frame element to \var{e}, if the frame element corresponds to an assignable variable. \var{n} defaults to 0. \Itype{Procedure} \Icmd{\scheme{show} or \scheme{s}} shows the source and free variables of the procedure. Source is available only if generation of inspector information was enabled during compilation of the corresponding lambda expression. \Icmd{\scheme{code} or \scheme{c}} moves to the source for the procedure. \Icmd{\scheme{file}} opens the file containing the procedure's source code, if known. See the description of the continuation \scheme{file} entry above for more information. \Icmd{\scheme{length} or \scheme{l}} displays the number of free variables whose values are recorded in the procedure object. \Icmd{\scheme{ref} or \scheme{r}} moves to the \var{nth} or named free variable. \var{n} defaults to 0. If multiple free variables have the same name, only one is accessible by name, and the others must be accessed by number. \Icmd{\scheme{set!} or \scheme{!} \var{n} \var{e}} sets the value of the \var{nth} free variable to \var{e}, if the variable is assignable. \var{n} defaults to 0. \Icmd{\scheme{eval} or \scheme{e} \var{expr}} evaluates the expression \var{expr} in an environment containing bindings for the free variables of the procedure. Within the evaluated expression, the value of each free variable \var{n} is accessible via the variable \scheme{%\var{n}}. Named free variables are accessible via their names as well. Names are available only if generation of inspector information was enabled during compilation of the corresponding lambda expression. \Itype{Pair (list)} \Icmd{\scheme{show} or \scheme{s} \var{n}} shows the first \var{n} elements of the list. If \var{n} is not specified, all elements are displayed. \Icmd{\scheme{length} or \scheme{l}} displays the list length. \Icmd{\scheme{car}} moves to the object in the car of the current object. \Icmd{\scheme{cdr}} moves to the object in the cdr. \Icmd{\scheme{ref} or \scheme{r} \var{n}} moves to the \var{nth} element of the list. \var{n} defaults to 0. \Icmd{\scheme{tail} \var{n}} moves to the \var{nth} cdr of the list. \var{n} defaults to 1. \Itype{Vector, Bytevector, and Fxvector} \Icmd{\scheme{show} or \scheme{s} \var{n}} shows the first \var{n} elements of the vector. If \var{n} is not specified, all elements are displayed. \Icmd{\scheme{length} or \scheme{l}} displays the vector length. \Icmd{\scheme{ref} or \scheme{r} \var{n}} moves to the \var{nth} element of the vector. \var{n} defaults to 0. \Itype{String} \Icmd{\scheme{show} or \scheme{s} \var{n}} shows the first \var{n} elements of the string. If \var{n} is not specified, all elements are displayed. \Icmd{\scheme{length} or \scheme{l}} displays the string length. \Icmd{\scheme{ref} or \scheme{r} \var{n}} moves to the \var{nth} element of the string. \var{n} defaults to 0. \Icmd{\scheme{unicode} \var{n}} displays the first \var{n} elements of the string as hexadecimal Unicode scalar values. \Icmd{\scheme{ascii} \var{n}} displays the first \var{n} elements of the string as hexadecimal ASCII values, using \scheme{--} to denote characters whose Unicode scalar values are not in the ASCII range. \Itype{Symbol} \Icmd{\scheme{show} or \scheme{s}} shows the fields of the symbol. \Icmd{\scheme{value} or \scheme{v}} moves to the top-level value of the symbol. \Icmd{\scheme{name} or \scheme{n}} moves to the name of the symbol. \Icmd{\scheme{property-list} or \scheme{pl}} moves to the property list of the symbol. \Icmd{\scheme{ref} or \scheme{r} \var{n}} moves to the \var{nth} field of the symbol. Field 0 is the top-level value of the symbol, field 1 is the symbol's name, and field 2 is its property list. \var{n} defaults to 0. % in subset-mode system also value-slot, system-property-list, and symbol-hash \Itype{Character} \Icmd{\scheme{unicode}} displays the hexadecimal Unicode scalar value for the character. \Icmd{\scheme{ascii}} displays the hexadecimal ASCII code for the character, using \scheme{--} to denote characters whose Unicode scalar values are not in the ASCII range. \Itype{Box} \Icmd{\scheme{show} or \scheme{s}} shows the contents of the box. \Icmd{\scheme{unbox} or \scheme{ref} or \scheme{r}} moves to the boxed object. \Itype{Port} \Icmd{\scheme{show} or \scheme{s}} shows the fields of the port, including the input and output size, index, and buffer fields. \Icmd{\scheme{name}} moves to the port's name. \Icmd{\scheme{handler}} moves to the port's handler. \Icmd{\scheme{output-buffer} or \scheme{ob}} moves to the port's output buffer. \Icmd{\scheme{input-buffer} or \scheme{ib}} moves to the port's input buffer. % \Icmd{\scheme{info}} moves to the port's info. \Itype{Record} \Icmd{\scheme{show} or \scheme{s}} shows the contents of the record. \Icmd{\scheme{fields}} moves to the list of field names of the record. \Icmd{\scheme{name}} moves to the name of the record. \Icmd{\scheme{rtd}} moves to the record-type descriptor of the record. \Icmd{\scheme{ref} or \scheme{r} \var{name}} moves to the named field of the record, if accessible. \Icmd{\scheme{set!} or \scheme{!} \var{name} \var{value}} sets the value of the named field of the record, if mutable. \Itype{Transport Link Cell (TLC)} \Icmd{\scheme{show} or \scheme{s}} shows the fields of the TLC. \Icmd{\scheme{keyval}} moves to the keyval of the TLC. \Icmd{\scheme{tconc}} moves to the tconc of the TLC. \Icmd{\scheme{next}} moves to the next link of the TLC. \Icmd{\scheme{ref} or \scheme{r} \var{n}} moves to the \var{nth} field of the symbol. Field 0 is the keyval, field 1 the tconc, and field 2 the next link. \var{n} defaults to 0. \section{The Object Inspector\label{SECTDEBUGOBJECTINSPECTOR}} A facility for noninteractive inspection is also provided to allow construction of different inspection interfaces. Like the interactive facility, it allows objects to be examined in ways not ordinarily possible. The noninteractive system follows a simple, object-oriented protocol. Ordinary Scheme objects are encapsulated in procedures, or inspector objects, that take symbolic messages and return either information about the encapsulated object or new inspector objects that encapsulate pieces of the object. %---------------------------------------------------------------------------- \entryheader \formdef{inspect/object}{\categoryprocedure}{(inspect/object \var{object})} \returns an inspector object procedure \listlibraries \endentryheader \noindent \scheme{inspect/object} is used to turn an ordinary Scheme object into an inspector object. All inspector objects accept the messages \scheme{type}, \scheme{print}, \scheme{write}, and \scheme{size}. The \scheme{type} message returns a symbolic representation of the type of the object. The \scheme{print} and \scheme{write} messages must be accompanied by a port parameter. They cause a representation of the object to be written to the port, using the Scheme procedures \scheme{pretty-print} and \scheme{write}. The \scheme{size} message returns a fixnum representing the size in bytes occupied by the object, including any objects accessible from the current object except those for which the size was already requested via an inspector object derived from the argument of the same \scheme{inspect/object} call. All inspector objects except for variable inspector objects accept the message \scheme{value}, which returns the actual object encapsulated in the inspector object. \schemedisplay (define x (inspect/object '(1 2 3))) (x 'type) ;=> pair (define p (open-output-string)) (x 'write p) (get-output-string p) ;=> "(1 2 3)" (x 'length) ;=> (proper 3) (define y (x 'car)) (y 'type) ;=> simple (y 'value) ;=> 1 \endschemedisplay \def\instype#1{\bigskip\noindent\textbf{#1 inspector objects.}} \def\insmsg#1#2{\medskip\noindent\scheme{(}\emph{#1-object} #2\scheme{)}} \instype{Pair} Pair inspector objects contain Scheme pairs. \insmsg{pair}{\scheme{'type}} returns the symbol \scheme{pair}. \insmsg{pair}{\scheme{'car}} returns an inspector object containing the ``car'' field of the pair. \insmsg{pair}{\scheme{'cdr}} returns an inspector object containing the ``cdr'' field of the pair. \insmsg{pair}{\scheme{'length}} returns a list of the form (\var{type} \var{count}). The type field contains the symbol \scheme{proper}, the symbol \scheme{improper}, or the symbol \scheme{circular}, depending on the structure of the list. The count field contains the number of distinct pairs in the list. \instype{Box} Box inspector objects contain {\ChezScheme} boxes. \insmsg{box}{\scheme{'type}} returns the symbol \scheme{box}. \insmsg{box}{\scheme{'unbox}} returns an inspector object containing the contents of the box. \instype{TLC} Box inspector objects contain {\ChezScheme} boxes. \insmsg{tlc}{\scheme{'type}} returns the symbol \scheme{tlc}. \insmsg{tlc}{\scheme{'keyval}} returns an inspector object containing the TLC's keyval. \insmsg{tlc}{\scheme{'tconc}} returns an inspector object containing the TLC's tconc. \insmsg{tlc}{\scheme{'next}} returns an inspector object containing the TLC's next link. \instype{Vector, String, Bytevector, and Fxvector} Vector (bytevector, string, fxvector) inspector objects contain Scheme vectors (bytevectors, strings, fxvectors). \insmsg{vector}{\scheme{'type}} returns the symbol \scheme{vector} (\scheme{string}, \scheme{bytevector}, \scheme{fxvector}). \insmsg{vector}{\scheme{'length}} returns the number of elements in the vector or string. \insmsg{vector}{\scheme{'ref} \var{n}} returns an inspector object containing the \var{nth} element of the vector or string. \instype{Simple} Simple inspector objects contain unstructured, unmodifiable objects. These include numbers, booleans, the empty list, the end-of-file object, and the void object. They may be examined directly by asking for the \scheme{value} of the object. \insmsg{simple}{\scheme{'type}} returns the symbol \scheme{simple}. \instype{Unbound} Although unbound objects are not normally accessible to Scheme programs, they may be encountered when inspecting variables. \insmsg{unbound}{\scheme{'type}} returns the symbol \scheme{unbound}. \instype{Procedure} Procedure inspector objects contain Scheme procedures. \insmsg{procedure}{\scheme{'type}} returns the symbol \scheme{procedure}. \insmsg{procedure}{\scheme{'length}} returns the number of free variables. \insmsg{procedure}{\scheme{'ref} \var{n}} returns an inspector object containing the \var{nth} free variable of the procedure. See the description below of variable inspector objects. \var{n} must be nonnegative and less than the length of the procedure. \insmsg{procedure}{\scheme{'eval} \var{expr}} evaluates \var{expr} and returns its value. The values of the procedure's free variables are bound within the evaluated expression to identifiers of the form \%$n$, where $n$ is the location number displayed by the inspector. The values of named variables are also bound to their names. \insmsg{procedure}{\scheme{'code}} returns an inspector object containing the procedure's code object. See the description below of code inspector objects. \instype{Continuation} Continuations created by \scheme{call/cc} are actually procedures. However, when inspecting such a procedure the underlying data structure that embodies the continuation may be exposed. A continuation structure contains the location at which computation is to resume, the variable values necessary to perform the computation, and a link to the next continuation. \insmsg{continuation}{\scheme{'type}} returns the symbol \scheme{continuation}. \insmsg{continuation}{\scheme{'length}} returns the number of free variables. \insmsg{continuation}{\scheme{'ref} \var{n}} returns an inspector object containing the \var{nth} free variable of the continuation. See the description below of variable inspector objects. \var{n} must be nonnegative and less than the length of the continuation. \insmsg{continuation}{\scheme{'eval} \var{expr}} evaluates \var{expr} and returns its value. The values of frame locations are bound within the evaluated expression to identifiers of the form \%$n$, where $n$ is the location number displayed by the inspector. The values of named locations are also bound to their names. \insmsg{continuation}{\scheme{'code}} returns an inspector object containing the code object for the procedure that was active when the current continuation frame was created. See the description below of code inspector objects. \insmsg{continuation}{\scheme{'depth}} returns the number of frames in the continuation. \insmsg{continuation}{\scheme{'link}} returns an inspector object containing the next continuation frame. The depth must be greater than 1. \insmsg{continuation}{\scheme{'link*} \var{n}} returns an inspector object containing the \var{nth} continuation link. \var{n} must be less than the depth. \insmsg{continuation}{\scheme{'source}} returns an inspector object containing the source information attached to the continuation (representing the source for the application that resulted in the formation of the continuation) or \scheme{#f} if no source information is attached. \insmsg{continuation}{\scheme{'source-object}} returns an inspector object containing the source object for the procedure application that resulted in the formation of the continuation or \scheme{#f} if no source object is attached. \insmsg{continuation}{\scheme{'source-path}} attempts to find the pathname of the file containing the source for the procedure application that resulted in the formation of the continuation. If successful, three values are returned to identify the file and position of the application within the file: \var{path}, \var{line}, and \var{char}. Two values, a file name and an absolute character position, are returned if the file name is known but the named file cannot be found. The search may be unsuccessful even if a file by the expected name is found in the path if the file has been modified since the source code was compiled. If no file name is known, no values are returned. The parameter \scheme{source-directories} (Section~\ref{SECTSYSTEMSOURCE}) determines the set of directories searched for source files identified by relative path names. \instype{Code} Code inspector objects contain {\ChezScheme} code objects. \insmsg{code}{\scheme{'type}} returns the symbol \scheme{code}. \insmsg{code}{\scheme{'name}} returns a string or \scheme{#f}. The name associated with a code inspector object is the name of the variable to which the procedure was originally bound or assigned. Since the binding of a variable can be changed, this name association may not always be accurate. \scheme{#f} is returned if the inspector cannot determine a name for the procedure. \insmsg{code}{\scheme{'source}} returns an inspector object containing the source information attached to the code object or \scheme{#f} if no source information is attached. \insmsg{continuation}{\scheme{'source-object}} returns an inspector object containing the source object for the code object or \scheme{#f} if no source object is attached. \insmsg{code}{\scheme{'source-path}} attempts to find the pathname of the file containing the source for the lambda expression that produced the code object. If successful, three values are returned to identify the file and position of the application within the file: \var{path}, \var{line}, and \var{char}. Two values, a file name and an absolute character position, are returned if the file name is known but the named file cannot be found. The search may be unsuccessful even if a file by the expected name is found in the path if the file has been modified since the source code was compiled. If no file name is known, no values are returned. The parameter \scheme{source-directories} (Section~\ref{SECTSYSTEMSOURCE}) determines the set of directories searched for source files identified by relative path names. \insmsg{code}{\scheme{'free-count}} returns the number of free variables in any procedure for which this is the corresponding code. \instype{Variable} Variable inspector objects encapsulate variable bindings. Although the actual underlying representation varies, the variable inspector object provides a uniform interface. \insmsg{variable}{\scheme{'type}} returns the symbol \scheme{variable}. \insmsg{variable}{\scheme{'name}} returns a symbol or \scheme{#f}. \scheme{#f} is returned if the name is not available or if the variable is a compiler-generated temporary variable. Variable names are not retained when the parameter \scheme{generate-inspector-information} (page~\ref{desc:generate-inspector-information}) is false during compilation. \insmsg{variable}{\scheme{'ref}} returns an inspector object containing the current value of the variable. \insmsg{variable}{\scheme{'set!} \var{e}} returns unspecified, after setting the current value of the variable to \var{e}. An exception is raised with condition type \scheme{&assertion} if the variable is not assignable. % \insmsg{variable}{\scheme{id}} returns compiler's internal data structure % representing the variable, if available. \instype{Port} Port inspector objects contain ports. \insmsg{port}{\scheme{'type}} returns the symbol \scheme{port}. \insmsg{port}{\scheme{'input?}} returns \scheme{#t} if the port is an input port, \scheme{#f} otherwise. \insmsg{port}{\scheme{'output?}} returns \scheme{#t} if the port is an output port, \scheme{#f} otherwise. \insmsg{port}{\scheme{'binary?}} returns \scheme{#t} if the port is a binary port, \scheme{#f} otherwise. \insmsg{port}{\scheme{'closed?}} returns \scheme{#t} if the port is closed, \scheme{#f} if the port is open. \insmsg{port}{\scheme{'name}} returns an inspector object containing the port's name. \insmsg{port}{\scheme{'handler}} returns a procedure inspector object encapsulating the port handler, such as would be returned by \scheme{port-handler}. \insmsg{port}{\scheme{'output-size}} returns the output buffer size as a fixnum if the port is an output port (otherwise the value is unspecified). \insmsg{port}{\scheme{'output-index}} returns the output buffer index as a fixnum if the port is an output port (otherwise the value is unspecified). \insmsg{port}{\scheme{'output-buffer}} returns an inspector object containing the string used for buffered output. \insmsg{port}{\scheme{'input-size}} returns the input buffer size as a fixnum if the port is an input port (otherwise the value is unspecified). \insmsg{port}{\scheme{'input-index}} returns the input buffer index as a fixnum if the port is an input port (otherwise the value is unspecified). \insmsg{port}{\scheme{'input-buffer}} returns an inspector object containing the string used for buffered input. % \insmsg{port}{\scheme{'info}} % returns an inspector object containing the port's info. \instype{Symbol} Symbol inspector objects contain symbols. These include gensyms. \insmsg{symbol}{\scheme{'type}} returns the symbol \scheme{symbol}. \insmsg{symbol}{\scheme{'name}} returns a string inspector object. The string name associated with a symbol inspector object is the print representation of a symbol, such as would be returned by the procedure \scheme{symbol->string}. \insmsg{symbol}{\scheme{'gensym?}} returns \scheme{#t} if the symbol is a gensym, \scheme{#f} otherwise. Gensyms are created by \scheme{gensym}. \insmsg{symbol}{\scheme{'top-level-value}} returns an inspector object containing the global value of the symbol. \insmsg{symbol}{\scheme{'property-list}} returns an inspector object containing the property list for the symbol. % also $top-level-value, system-property-list, and symbol-hash \instype{Record} Record inspector objects contain records. \insmsg{record}{\scheme{'type}} returns the symbol \scheme{record}. \insmsg{record}{\scheme{'name}} returns a string inspector object corresponding to the name of the record type. \insmsg{record}{\scheme{'fields}} returns an inspector object containing a list of the field names of the record type. \insmsg{record}{\scheme{'length}} returns the number of fields. \insmsg{record}{\scheme{'rtd}} returns an inspector object containing the record-type descriptor of the record type. \insmsg{record}{\scheme{'accessible?} \var{name}} returns \scheme{#t} if the named field is accessible, \scheme{#f} otherwise. A field may be inaccessible if optimized away by the compiler. \insmsg{record}{\scheme{'ref} \var{name}} returns an inspector object containing the value of the named field. An exception is raised with condition type \scheme{&assertion} if the named field is not accessible. \insmsg{record}{\scheme{'mutable?} \var{name}} returns \scheme{#t} if the named field is mutable, \scheme{#f} otherwise. A field is immutable if it is not declared mutable or if the compiler optimizes away all assignments to the field. \insmsg{record}{\scheme{'set!} \var{name} \var{value}} sets the value of the named field to \var{value}. An exception is raised with condition type \scheme{&assertion} if the named field is not assignable. \section{Locating objects\label{SECTDEBUGLOCATINGOBJECTS}} \noskipentryheader \formdef{make-object-finder}{\categoryprocedure}{(make-object-finder \var{pred})} \formdef{make-object-finder}{\categoryprocedure}{(make-object-finder \var{pred} \var{g})} \formdef{make-object-finder}{\categoryprocedure}{(make-object-finder \var{pred} \var{x} \var{g})} \returns see below \listlibraries \endentryheader The procedure \scheme{make-object-finder} takes a predicate \var{pred} and two optional arguments: a starting point \var{x} and a maximum generation \var{g}. The starting point defaults to the value of the procedure \scheme{oblist}, and the maximum generation defaults to the value of the parameter \scheme{collect-maximum-generation}. \scheme{make-object-finder} returns an object finder \var{p} that can be used to search for objects satisfying \var{pred} within the starting-point object \var{x}. Immediate objects and objects in generations older than \var{g} are treated as leaves. \var{p} is a procedure accepting no arguments. If an object \var{y} satisfying \var{pred} can be found starting with \var{x}, \var{p} returns a list whose first element is \var{y} and whose remaining elements represent the path of objects from \var{x} to \var{y}, listed in reverse order. \var{p} can be invoked multiple times to find additional objects satisfying the predicate, if any. \var{p} returns \scheme{#f} if no more objects matching the predicate can be found. \var{p} maintains internal state recording where it has been so it can restart at the point of the last found object and not return the same object twice. The state can be several times the size of the starting-point object \var{x} and all that is reachable from \var{x}. The interactive inspector provides a convenient interface to the object finder in the form of \scheme{find} and \scheme{find-next} commands. Relocation tables for static code objects are discarded by default, which prevents object finders from providing accurate results when static code objects are involved. That is, they will not find any objects pointed to directly from a code object that has been promoted to the static generation. If this is a problem, the command-line argument \index{\scheme{--retain-static-relocation} command-line option}\scheme{--retain-static-relocation} can be used to prevent the relocation tables from being discarded. \section{Nested object size and composition\label{SECTDEBUGOBJECTSIZES}} The procedures \scheme{compute-size} and \scheme{compute-composition} can be used to determine the size or composition of an object, including anything reachable via pointers from the object. Depending on the number of objects reachable from the object, the procedures potentially allocate a large amount of memory. In an application for which knowing the number, size, generation, and types of all objects in the heap is sufficient, \index{\scheme{object-counts}}\scheme{object-counts} is potentially much more efficient. These procedures treat immediate objects such as fixnums, booleans, and characters as zero-count, zero-byte leaves. By default, these procedures also treat static objects (those in the initial heap) as zero-count, zero-byte leaves. Both procedures accept an optional second argument that specifies the maximum generation of interest, with the symbol \scheme{static} being used to represent the static generation. Objects sometimes point to a great deal more than one might expect. For example, if static data is included, the procedure value of \scheme{(lambda (x) x)} points indirectly to the exception handling subsystem (because of the argument-count check) and many other things as a result of that. Relocation tables for static code objects are discarded by default, which prevents these procedures from providing accurate results when static code objects are involved. That is, they will not find any objects pointed to directly from a code object that has been promoted to the static generation. If accurate sizes and compositions for static code objects are required, the command-line argument \index{\scheme{--retain-static-relocation} command-line option}\scheme{--retain-static-relocation} can be used to prevent the relocation tables from being discarded. \entryheader \formdef{compute-size}{\categoryprocedure}{(compute-size \var{object})} \formdef{compute-size}{\categoryprocedure}{(compute-size \var{object} \var{generation})} \returns see below \listlibraries \endentryheader \var{object} can be any object. \var{generation} must be a fixnum between 0 and the value of \scheme{collect-maximum-generation}, inclusive, or the symbol \scheme{static}. If \var{generation} is not supplied, it defaults to the value of \scheme{collect-maximum-generation}. \scheme{compute-size} returns the amount of memory, in bytes, occupied by \var{object} and anything reachable from \var{object} in any generation less than or equal to \var{generation}. Immediate values such as fixnums, booleans, and characters have zero size. The following examples are valid for machines with 32-bit pointers. \schemedisplay (compute-size 0) ;=> 0 (compute-size (cons 0 0)) ;=> 8 (compute-size (cons (vector #t #f) 0)) ;=> 24 (compute-size (let ([x (cons 0 0)]) (set-car! x x) (set-cdr! x x) x)) ;=> 8 (define-record-type frob (fields x)) (collect 1 1) ; force rtd into generation 1 (compute-size (let ([x (make-frob 0)]) (cons x x)) 0) ;=> 16 \endschemedisplay \entryheader \formdef{compute-composition}{\categoryprocedure}{(compute-composition \var{object})} \formdef{compute-composition}{\categoryprocedure}{(compute-composition \var{object} \var{generation})} \returns see below \listlibraries \endentryheader \var{object} can be any object. \var{generation} must be a fixnum between 0 and the value of \scheme{collect-maximum-generation}, inclusive, or the symbol \scheme{static}. If \var{generation} is not supplied, it defaults to the value of \scheme{collect-maximum-generation}. \scheme{compute-composition} returns an association list representing the composition of \var{object}, including anything reachable from it in any generation less than or equal to \var{generation}. The association list has the following structure: \schemedisplay ((\var{type} \var{count} . \var{bytes}) \dots) \endschemedisplay \var{type} is either the name of a primitive type, represented as a symbol, e.g., \scheme{pair}, or a record-type descriptor (rtd). \var{count} and \var{bytes} are nonnegative fixnums. Immediate values such as fixnums, booleans, and characters are not included in the composition. The following examples are valid for machines with 32-bit pointers. \schemedisplay (compute-composition 0) ;=> () (compute-composition (cons 0 0)) ;=> ((pair 1 . 8)) (compute-composition (cons (vector #t #f) 0)) ;=> ((pair 1 . 8) (vector 1 . 16)) (compute-composition (let ([x (cons 0 0)]) (set-car! x x) (set-cdr! x x) x)) ;=> ((pair 1 . 8) (define-record-type frob (fields x)) (collect 1 1) ; force rtd into generation 1 (compute-composition (let ([x (make-frob 0)]) (cons x x)) 0) ;=> ((pair 1 . 8) (# 1 . 8)) \endschemedisplay