(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
Chez Scheme has several features that support debugging. In addition to providing error messages when fully type-checked code is run, Chez Scheme 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 Chez Scheme, and even more experienced Scheme programmers, might want to consult the tutorial "How to Debug Chez Scheme Programs." HTML and PDF versions are available at https://scheme.com/debug/debug.html.
Tracing is one of the most useful mechanisms for debugging Scheme programs. Chez Scheme 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.
syntax: (trace-lambda name formals body1 body2 ...)
returns: a traced procedure
libraries: (chezscheme)
A trace-lambda expression is equivalent to a 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 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 half defined below returns the integer quotient of its argument and 2.
(define half
(trace-lambda half (x)
(cond
[(zero? x) 0]
[(odd? x) (half (- x 1))]
[(even? x) (+ (half (- x 1)) 1)])))
A trace of the call (half 5), which returns 2, is shown below.
|(half 5)
|(half 4)
| (half 3)
| (half 2)
| |(half 1)
| |(half 0)
| |0
| 1
|2
This example highlights the proper treatment of tail and nontail calls by the trace package. Since half tail calls itself when its argument is odd, the call (half 4) appears at the same level of indentation as the call (half 5). Furthermore, since the return values of (half 5) and (half 4) are necessarily the same, only one return value is shown for both calls.
syntax: (trace-case-lambda name clause ...)
returns: a traced procedure
libraries: (chezscheme)
A trace-case-lambda expression is equivalent to a case-lambda expression with the same clauses except that trace information is printed to the trace output port whenever the procedure is invoked, using 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.
syntax: (trace-let name ((var expr) ...) body1 body2 ...)
returns: the values of the body body1 body2 ...
libraries: (chezscheme)
A trace-let expression is equivalent to a named 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 name) into the trace-let expression.
A trace-let expression of the form
(trace-let name ([var expr] ...)
body1 body2 ...)
can be rewritten in terms of trace-lambda as follows:
((letrec ([name
(trace-lambda name (var ...)
body1 body2 ...)])
name)
expr ...)
trace-let may be used to trace ordinary let expressions as well as let expressions as long as the name inserted along with the trace-let keyword in place of let does not appear free within the body of the let expression. It is also sometimes useful to insert a 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 half
(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)])))
with argument 5 results in the trace:
|(half 5)
| (decr-value)
| 4
|(half 4)
| (half 3)
| |(decr-value)
| |2
| (half 2)
| |(half 1)
| | (decr-value)
| | 0
| |(half 0)
| 1
|2
syntax: (trace-do ((var init update) ...) (test result ...) expr ...)
returns: the values of the last result expression
libraries: (chezscheme)
A trace-do expression is equivalent to a do expression with the same subforms, except that trace information is printed to the trace output port, showing the values of var ... and each iteration and the final value of the loop on termination. For example, the expression
(trace-do ([old '(a b c) (cdr old)]
[new '() (cons (car old) new)])
((null? old) new))
produces the trace
|(do (a b c) ())
|(do (b c) (a))
|(do (c) (b a))
|(do () (c b a))
|(c b a)
and returns (c b a).
syntax: (trace var1 var2 ...)
returns: a list of var1 var2 ...
syntax: (trace)
returns: a list of all currently traced top-level variables
libraries: (chezscheme)
In the first form, trace reassigns the top-level values of var1 var2 ..., whose values must be procedures, to equivalent procedures that display trace information in the manner of trace-lambda.
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.)
(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))))
...)]))
Tracing for a procedure traced in this manner may be disabled via untrace (see below), an assignment of the corresponding variable to a different, untraced value, or a subsequent use of 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.
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 trace in an interactive session.
> (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
syntax: (untrace var1 var2 ...)
syntax: (untrace)
returns: a list of untraced variables
libraries: (chezscheme)
untrace restores the original (pre-trace) top-level values of each currently traced variable in var1 var2 ..., effectively disabling the tracing of the values of these variables. Any variable in var1 var2 ... that is not currently traced is ignored. If untrace is called without arguments, the values of all currently traced variables are restored.
The following transcript demonstrates the use of trace and untrace in an interactive session to debug an incorrect procedure definition.
> (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
The first call to 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 untrace does not wipe out the fix.
thread parameter: trace-output-port
libraries: (chezscheme)
trace-output-port is a parameter that determines the output port to which tracing information is sent. When called with no arguments, trace-output-port returns the current trace output port. When called with one argument, which must be a textual output port, trace-output-port changes the value of the current trace output port.
thread parameter: trace-print
libraries: (chezscheme)
The value of trace-print must be a procedure of two arguments, an object and an output port. The trace package uses the value of trace-print to print the arguments and return values for each call to a traced procedure. trace-print is set to pretty-print by default.
The trace package sets pretty-initial-indent to an appropriate value for the current nesting level before calling the value of trace-print so that multiline output can be indented properly.
syntax: (trace-define var expr)
syntax: (trace-define (var . idspec) body1 body2 ...)
returns: unspecified
libraries: (chezscheme)
trace-define is a convenient shorthand for defining variables bound to traced procedures of the same name. The first form is equivalent to
(define var
(let ([x expr])
(trace-lambda var args
(apply x args))))
and the second is equivalent to
(define var
(trace-lambda var idspec
body1 body2 ...))
In the former case, expr must evaluate to a procedure.
> (let ()
(trace-define plus
(lambda (x y)
(+ x y)))
(list (plus 3 4) (+ 5 6)))
|(plus 3 4)
|7
(7 11)
syntax: (trace-define-syntax keyword expr)
returns: unspecified
libraries: (chezscheme)
trace-define-syntax traces the input and output to the transformer value of expr, stripped of the contextual information used by the expander to maintain lexical scoping.
> (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)
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.
> (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
The interactive debugger is entered as a result of a call to the procedure 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 debug-on-exception is true.
Within the debugger, the command "?" lists the debugger command options. These include commands to:
The raise continuation is the continuation encapsulated within the condition, if any. The standard exception reporting procedures and forms assert, assertion-violation, and error as well as the Chez Scheme procedures assertion-violationf, errorf, and 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 break handled by the default break handler. Again, the command "?" lists the command options. These include commands to:
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).
procedure: (debug)
returns: does not return
libraries: (chezscheme)
When the default exception handler receives a serious or non-warning condition, it displays the condition and resets to the current café. Before it resets, it saves the condition in the parameter debug-condition. The 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, debug allows the continuation contained within any continuation condition created by make-continuation-condition to be inspected.
If the parameter debug-on-exception is set to #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 --debug-on-exception command-line option may be used to set debug-on-exception to #t from the command line, which is particularly useful when debugging scripts or top-level programs run via the --script or --program command-line options.
The inspector may be called directly via the procedure 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 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 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.
procedure: (inspect obj)
returns: unspecified
libraries: (chezscheme)
Invokes the inspector on obj, as described above. The commands recognized by the inspector are listed below, categorized by the type of the current object.
Generally applicable commands
help or h displays a brief description of how to use the inspector.
? displays commands applicable to the current type of object.
?? displays the generally applicable commands.
print or p prints the current object (using pretty-print).
write or w writes the current object (using write).
size writes the size in bytes occupied by the current object (determined via 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.
find expr [ g ] evaluates expr, which should evaluate to a procedure of one argument, and searches (via 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 g, and values already visited during the search as leaves. If g is not unspecified, it defaults to the current maximum generation, i.e., the value of collect-maximum-generation. If specified, g must be an exact nonnegative integer less than or equal to the current maximum generation or the symbol 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 up command can be used to determine where the object was found relative to the original object.
find-next repeats the last find, locating an occurrence not previously found, if any.
up or u n returns to the nth previous level. Used to move outwards in the structure of the inspected object. n defaults to 1.
top or t returns to the outermost level of the inspected object.
forward or f moves to the 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. n defaults to 1.
back or b moves to the 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. n defaults to 1.
=> expr sends the current object to the procedure value of expr. expr may begin on the current or following line and may span multiple lines.
file path opens the source file at the specified path for listing. The parameter source-directories (Section 12.5) determines the set of directories searched for source files.
list line count lists count lines of the current source file (see file) starting at line. line defaults to the end of the previous set of lines listed and count defaults to ten or the number of lines previously listed. If line is negative, listing begins line lines before the previous set of lines listed.
files shows the currently open source files.
mark or m m marks the current location with the symbolic mark m. If m is not specified, the current location is marked with a unique default mark.
goto or g m returns to the location marked m. If m is not specified, the inspector returns to the location marked with the default mark.
new-cafe or n enters a new read-eval-print loop (café), giving access to the normal top-level environment.
quit or q exits from the inspector.
reset or r resets to the current café.
abort or a x aborts from Scheme with exit status x, which defaults to -1.
Continuation commands
show-frames or sf shows the next n frames. If n is not specified, all frames are displayed.
depth displays the number of frames in the continuation.
down or d n move to the nth frame down in the continuation. n defaults to 1.
show or 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.
show-local or sl is like show or s except that free variable values are not shown. (If present, free variable values can be found by inspecting the closure.)
length or l displays the number of elements in the topmost frame of the continuation.
ref or r moves to the nth or named frame element. 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.
code or c moves to the source for the calling procedure.
call moves to the source for the pending call.
file opens the source file containing the pending call, if known. The parameter source-directories (Section 12.5) determines the list of source directories searched for source files identified by relative path names.
For absolute pathnames starting with a / (or \ 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 ./ (or .\ under Windows) or ../ (or ..\ under Windows), the inspector looks in "." or ".." first, as appropriate, then for the entire .- or ..-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).
eval or e expr evaluates the expression expr in an environment containing bindings for the elements of the frame. Within the evaluated expression, the value of each frame element n is accessible via the variable %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.
set! or ! n e sets the value of the nth frame element to e, if the frame element corresponds to an assignable variable. n defaults to 0.
Procedure commands
show or 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.
code or c moves to the source for the procedure.
file opens the file containing the procedure's source code, if known. See the description of the continuation file entry above for more information.
length or l displays the number of free variables whose values are recorded in the procedure object.
ref or r moves to the nth or named free variable. 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.
set! or ! n e sets the value of the nth free variable to e, if the variable is assignable. n defaults to 0.
eval or e expr evaluates the expression expr in an environment containing bindings for the free variables of the procedure. Within the evaluated expression, the value of each free variable n is accessible via the variable %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.
Pair (list) commands
show or s n shows the first n elements of the list. If n is not specified, all elements are displayed.
length or l displays the list length.
car moves to the object in the car of the current object.
cdr moves to the object in the cdr.
ref or r n moves to the nth element of the list. n defaults to 0.
tail n moves to the nth cdr of the list. n defaults to 1.
Vector, Bytevector, and Fxvector commands
show or s n shows the first n elements of the vector. If n is not specified, all elements are displayed.
length or l displays the vector length.
ref or r n moves to the nth element of the vector. n defaults to 0.
String commands
show or s n shows the first n elements of the string. If n is not specified, all elements are displayed.
length or l displays the string length.
ref or r n moves to the nth element of the string. n defaults to 0.
unicode n displays the first n elements of the string as hexadecimal Unicode scalar values.
ascii n displays the first n elements of the string as hexadecimal ASCII values, using -- to denote characters whose Unicode scalar values are not in the ASCII range.
Symbol commands
show or s shows the fields of the symbol.
value or v moves to the top-level value of the symbol.
name or n moves to the name of the symbol.
property-list or pl moves to the property list of the symbol.
ref or r n moves to the 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. n defaults to 0.
Character commands
unicode displays the hexadecimal Unicode scalar value for the character.
ascii displays the hexadecimal ASCII code for the character, using -- to denote characters whose Unicode scalar values are not in the ASCII range.
Box commands
show or s shows the contents of the box.
unbox or ref or r moves to the boxed object.
Port commands
show or s shows the fields of the port, including the input and output size, index, and buffer fields.
name moves to the port's name.
handler moves to the port's handler.
output-buffer or ob moves to the port's output buffer.
input-buffer or ib moves to the port's input buffer.
Record commands
show or s shows the contents of the record.
fields moves to the list of field names of the record.
name moves to the name of the record.
rtd moves to the record-type descriptor of the record.
ref or r name moves to the named field of the record, if accessible.
set! or ! name value sets the value of the named field of the record, if mutable.
Transport Link Cell (TLC) commands
show or s shows the fields of the TLC.
keyval moves to the keyval of the TLC.
tconc moves to the tconc of the TLC.
next moves to the next link of the TLC.
ref or r n moves to the nth field of the symbol. Field 0 is the keyval, field 1 the tconc, and field 2 the next link. n defaults to 0.
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.
procedure: (inspect/object object)
returns: an inspector object procedure
libraries: (chezscheme)
inspect/object is used to turn an ordinary Scheme object into an inspector object. All inspector objects accept the messages type, print, write, and size. The type message returns a symbolic representation of the type of the object. The print and 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 pretty-print and write. The 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 inspect/object call.
All inspector objects except for variable inspector objects accept the message value, which returns the actual object encapsulated in the inspector object.
(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
Pair inspector objects. Pair inspector objects contain Scheme pairs.
(pair-object 'type) returns the symbol pair.
(pair-object 'car) returns an inspector object containing the "car" field of the pair.
(pair-object 'cdr) returns an inspector object containing the "cdr" field of the pair.
(pair-object 'length) returns a list of the form (type count). The type field contains the symbol proper, the symbol improper, or the symbol circular, depending on the structure of the list. The count field contains the number of distinct pairs in the list.
Box inspector objects. Box inspector objects contain Chez Scheme boxes.
(box-object 'type) returns the symbol box.
(box-object 'unbox) returns an inspector object containing the contents of the box.
TLC inspector objects. TLC inspector objects contain Chez Scheme transport link cells.
(tlc-object 'type) returns the symbol tlc.
(tlc-object 'keyval) returns an inspector object containing the TLC's keyval.
(tlc-object 'tconc) returns an inspector object containing the TLC's tconc.
(tlc-object 'next) returns an inspector object containing the TLC's next link.
Vector, String, Bytevector, and Fxvector inspector objects. Vector (bytevector, string, fxvector) inspector objects contain Scheme vectors (bytevectors, strings, fxvectors).
(vector-object 'type) returns the symbol vector (string, bytevector, fxvector).
(vector-object 'length) returns the number of elements in the vector or string.
(vector-object 'ref n) returns an inspector object containing the nth element of the vector or string.
Simple inspector objects. 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 value of the object.
(simple-object 'type) returns the symbol simple.
Unbound inspector objects. Although unbound objects are not normally accessible to Scheme programs, they may be encountered when inspecting variables.
(unbound-object 'type) returns the symbol unbound.
Procedure inspector objects. Procedure inspector objects contain Scheme procedures.
(procedure-object 'type) returns the symbol procedure.
(procedure-object 'length) returns the number of free variables.
(procedure-object 'ref n) returns an inspector object containing the nth free variable of the procedure. See the description below of variable inspector objects. n must be nonnegative and less than the length of the procedure.
(procedure-object 'eval 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.
(procedure-object 'code) returns an inspector object containing the procedure's code object. See the description below of code inspector objects.
Continuation inspector objects. Continuations created by 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.
(continuation-object 'type) returns the symbol continuation.
(continuation-object 'length) returns the number of free variables.
(continuation-object 'ref n) returns an inspector object containing the nth free variable of the continuation. See the description below of variable inspector objects. n must be nonnegative and less than the length of the continuation.
(continuation-object 'eval 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.
(continuation-object '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.
(continuation-object 'depth) returns the number of frames in the continuation.
(continuation-object 'link) returns an inspector object containing the next continuation frame. The depth must be greater than 1.
(continuation-object 'link* n) returns an inspector object containing the nth continuation link. n must be less than the depth.
(continuation-object '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 #f if no source information is attached.
(continuation-object 'source-object) returns an inspector object containing the source object for the procedure application that resulted in the formation of the continuation or #f if no source object is attached.
(continuation-object '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: path, line, and 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 source-directories (Section 12.5) determines the set of directories searched for source files identified by relative path names.
Code inspector objects. Code inspector objects contain Chez Scheme code objects.
(code-object 'type) returns the symbol code.
(code-object 'name) returns a string or #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. #f is returned if the inspector cannot determine a name for the procedure.
(code-object 'realm) returns a symbol or #f. The realm of a code object is determined by the compile-procedure-realm parameter at the time that the code object is compiled.
(code-object 'source) returns an inspector object containing the source information attached to the code object or #f if no source information is attached.
(continuation-object 'source-object) returns an inspector object containing the source object for the code object or #f if no source object is attached.
(code-object '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: path, line, and 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 source-directories (Section 12.5) determines the set of directories searched for source files identified by relative path names.
(code-object 'free-count) returns the number of free variables in any procedure for which this is the corresponding code.
Variable inspector objects. Variable inspector objects encapsulate variable bindings. Although the actual underlying representation varies, the variable inspector object provides a uniform interface.
(variable-object 'type) returns the symbol variable.
(variable-object 'name) returns a symbol or #f. #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 generate-inspector-information (page 12.6) is false during compilation.
(variable-object 'ref) returns an inspector object containing the current value of the variable.
(variable-object 'set! e) returns unspecified, after setting the current value of the variable to e. An exception is raised with condition type &assertion if the variable is not assignable.
Port inspector objects. Port inspector objects contain ports.
(port-object 'type) returns the symbol port.
(port-object 'input?) returns #t if the port is an input port, #f otherwise.
(port-object 'output?) returns #t if the port is an output port, #f otherwise.
(port-object 'binary?) returns #t if the port is a binary port, #f otherwise.
(port-object 'closed?) returns #t if the port is closed, #f if the port is open.
(port-object 'name) returns an inspector object containing the port's name.
(port-object 'handler) returns a procedure inspector object encapsulating the port handler, such as would be returned by port-handler.
(port-object 'output-size) returns the output buffer size as a fixnum if the port is an output port (otherwise the value is unspecified).
(port-object 'output-index) returns the output buffer index as a fixnum if the port is an output port (otherwise the value is unspecified).
(port-object 'output-buffer) returns an inspector object containing the string used for buffered output.
(port-object 'input-size) returns the input buffer size as a fixnum if the port is an input port (otherwise the value is unspecified).
(port-object 'input-index) returns the input buffer index as a fixnum if the port is an input port (otherwise the value is unspecified).
(port-object 'input-buffer) returns an inspector object containing the string used for buffered input.
Symbol inspector objects. Symbol inspector objects contain symbols. These include gensyms.
(symbol-object 'type) returns the symbol symbol.
(symbol-object '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 symbol->string.
(symbol-object 'gensym?) returns #t if the symbol is a gensym, #f otherwise. Gensyms are created by gensym.
(symbol-object 'top-level-value) returns an inspector object containing the global value of the symbol.
(symbol-object 'property-list) returns an inspector object containing the property list for the symbol.
Record inspector objects. Record inspector objects contain records.
(record-object 'type) returns the symbol record.
(record-object 'name) returns a string inspector object corresponding to the name of the record type.
(record-object 'fields) returns an inspector object containing a list of the field names of the record type.
(record-object 'length) returns the number of fields.
(record-object 'rtd) returns an inspector object containing the record-type descriptor of the record type.
(record-object 'accessible? name) returns #t if the named field is accessible, #f otherwise. A field may be inaccessible if optimized away by the compiler.
(record-object 'ref name) returns an inspector object containing the value of the named field. An exception is raised with condition type &assertion if the named field is not accessible.
(record-object 'mutable? name) returns #t if the named field is mutable, #f otherwise. A field is immutable if it is not declared mutable or if the compiler optimizes away all assignments to the field.
(record-object 'set! name value) sets the value of the named field to value. An exception is raised with condition type &assertion if the named field is not assignable.
procedure: (make-object-finder pred)
procedure: (make-object-finder pred g)
procedure: (make-object-finder pred x g)
returns: see below
libraries: (chezscheme)
The procedure make-object-finder takes a predicate pred and two optional arguments: a starting point x and a maximum generation g. The starting point defaults to the value of the procedure oblist, and the maximum generation defaults to the value of the parameter collect-maximum-generation. make-object-finder returns an object finder p that can be used to search for objects satisfying pred within the starting-point object x. Immediate objects and objects in generations older than g are treated as leaves. p is a procedure accepting no arguments. If an object y satisfying pred can be found starting with x, p returns a list whose first element is y and whose remaining elements represent the path of objects from x to y, listed in reverse order. p can be invoked multiple times to find additional objects satisfying the predicate, if any. p returns #f if no more objects matching the predicate can be found.
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 x and all that is reachable from x.
The interactive inspector provides a convenient interface to the object finder in the form of find and 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 --retain-static-relocation can be used to prevent the relocation tables from being discarded.
The procedures compute-size and 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, object-counts is potentially much more efficient.
The procedure compute-size-increments is similar to compute-size mapped over a list of elements, but it reports a size for each later element without including the size of objects reachable from ealier elements, and it treats weak and ephemeron pairs differently. For a large number of reachable objects, compute-size-increments uses much less memory than compute-size.
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 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 (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 --retain-static-relocation can be used to prevent the relocation tables from being discarded.
procedure: (compute-size object)
procedure: (compute-size object generation)
returns: see below
libraries: (chezscheme)
object can be any object. generation must be a fixnum between 0 and the value of collect-maximum-generation, inclusive, or the symbol static. If generation is not supplied, it defaults to the value of collect-maximum-generation.
compute-size returns the amount of memory, in bytes, occupied by object and anything reachable from object in any generation less than or equal to generation. Immediate values such as fixnums, booleans, and characters have zero size. Size computation for a thread is limited when the thread is still active, since its full continuation cannot be inspected in that case, but the full continuation is inspected if the thread is inactive (such as during a garbage collection rendezvous when a different thread is selected by the rendezvous).
The following examples are valid for machines with 32-bit pointers.
(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
procedure: (compute-composition object)
procedure: (compute-composition object generation)
returns: see below
libraries: (chezscheme)
object can be any object. generation must be a fixnum between 0 and the value of collect-maximum-generation, inclusive, or the symbol static. If generation is not supplied, it defaults to the value of collect-maximum-generation.
compute-composition returns an association list representing the composition of object, including anything reachable from it in any generation less than or equal to generation. The association list has the following structure:
((type count . bytes) ...)
type is either the name of a primitive type, represented as a symbol, e.g., pair, or a record-type descriptor (rtd). count and 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.
(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))
procedure: (compute-size-increments list)
procedure: (compute-size-increments list generation)
returns: a list as described below
libraries: (chezscheme)
list must be a list, but each element can be any object. generation must be a fixnum between 0 and the value of collect-maximum-generation, inclusive, or the symbol static. If generation is not supplied, it defaults to the value of collect-maximum-generation. In the threaded versions of Chez Scheme, the thread that invokes compute-size-increments must be the only active thread.
compute-size-increments is like mapping compute-size over list, except that any object reachable from an earlier element of list is not treated as reachable by a later element of list. In addition, each immediate element of list is not treated as reachable by earlier elements of list---although other values reachable from later elements of list may be considered reachable from earlier elements.
Unlike compute-size, compute-size-increments does not consider the car of a weak pair reachable from the weak pair. It also does not consider the car or cdr of an ephemeron pair to be reachable from the ephemeron pair, unless the car is already determined to be reachable (perhaps from an earlier element of list); if the car of an ephemeron pair is discovered to be reachable later (perhaps from a later element of list), then the cdr of the ephemeron pair is considered to be reachable from the car, which has the effect of charging the memory of the cdr to the same element of list as the memory of the car.
The following examples are valid for machines with 32-bit pointers.
(compute-size-increments (list 0)) (0)
(compute-size-increments (list (cons 0 0))) (8)
(compute-size-increments (list (cons 0 0) (cons 0 0))) (8 8)
(compute-size-increments (let ([p (cons 0 0)])
(list p p))) (8 0)
(compute-size-increments (let ([p (cons 0 0)])
(list (cons 1 p) (cons 1 p)))) (16 8)
(compute-size-increments (list (ephemeron-cons 0 0))) (16)
(compute-size-increments (let* ([p (cons 0 0)]
[e (ephemeron-cons p (cons 0 0))])
(list e p))) (16 16)
Chez Scheme Version 10 User's Guide
Copyright © 2024 Cisco Systems, Inc.
Licensed under the Apache License Version 2.0
(full copyright notice.).
Revised February 2024 for Chez Scheme Version 10.0.0
about this book