% 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 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 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)
                                (#<record type frob> 1 . 8))
\endschemedisplay