Previous: Image-building commands, Up: Command processor


2.4.12 Resource statistics and control

Scheme48 provides several devices for querying statistics about various resources and controlling resources, both in the command processor and programmatically.

— command: ,collect

Forces a garbage collection and prints the amount of space in the heap before and after the collection.

— command: ,time expression

Evaluates expression and prints how long it took. Three numbers are printed: run time, GC time, and real time. The run time is the amount of time in Scheme code; the GC time is the amount of time spent in the garbage collector; and the real time is the actual amount of time that passed during the expression's evaluation.

— command: ,keep
— command: ,keep kind ...
— command: ,flush
— command: ,flush kind ...

Scheme48 maintains several different kinds of information used for debugging information. `,keep' with no arguments shows what kinds of debugging data are preserved and what kinds are not. `,keep kind ...' requests that the debugging data of the given kinds should be kept; the ,flush command requests the opposite. `,flush' with no arguments flushes location names and resets the debug data table. The following are the kinds of debugging data:

names
procedure names
maps
environment maps used by the debugger to show local variable names
files
filenames where procedures were defined
source
source code surrounding continuations, printed by the debugger
tabulate
if true, will store debug data records in a global table that can be easily flushed; if false, will store directly in compiled code

,flush can also accept location-names, which will flush the table of top-level variables' names (printed, for example, by the ,bound? command); file-packages, which will flush the table that maps filenames to packages in which code from those files should be evaluated; or table, in which case the table of debug data is flushed.

Removing much debug data can significantly reduce the size of Scheme48 heap images, but it can also make error messages and debugging much more difficult. Usually, all debug data is retained; only for images that must be small and that do not need to be debuggable should the debugging data flags be turned off.

The spatial structure exports these utilities for displaying various statistics about the heap:

— procedure: space –> unspecified
— procedure: vector-space [predicate] –> unspecified
— procedure: record-space [predicate] –> unspecified

Space prints out a list of the numbers of all objects and the number of bytes allocated for those objects on the heap, partitioned by the objects' primitive types and whether or not they are immutable (pure) or mutable (impure). Vector-space prints the number of vectors and the number of bytes used to store those vectors of several different varieties, based on certain heuristics about their form. If the predicate argument is passed, it gathers only vectors that satisfy that predicate. Record-space prints out, for each record type in the heap, both the number of all instances of that record type and the number of bytes used to store all of those instances. Like vector-space, if the predicate argument is passed, record-space will consider only those records that satisfy the predicate.

All of these three procedures first invoke the garbage collector before gathering statistics.

The traverse structure provides a simple utility for finding paths by which objects refer to one another.

— procedure: traverse-breadth-first object –> unspecified
— procedure: traverse-depth-first object –> unspecified

These traverse the heap, starting at object, recording all objects transitively referred to. Traverse-breadth-first uses a FIFO-queue-directed breadth-first graph traversal, while traverse-depth-first uses a LIFO-stack-directed depth-first graph traversal. The traversal halts at any leaves in the graph, which are distinguished by an internal leaf predicate in the module. See below on set-leaf-predicate! on how to customize this and what the default is.

The traversal information is recorded in a global resource; it is not thread-safe, and intended only for interactive usage. The record can be reset by passing some simple object with no references to either traverse-breadth-first or traverse-depth-first; e.g., (traverse-depth-first #f).

— procedure: trail object –> unspecified

After traversing the heap from an initial object, (trail object) prints the path of references and intermediate objects by which the initial object holds a transitive reference to object.

— procedure: set-leaf-predicate! predicate –> unspecified
— procedure: usual-leaf-predicate object –> boolean

Set-leaf-predicate! sets the current leaf predicate to be predicate. Usual-leaf-predicate is the default leaf predicate; it considers simple numbers (integers and flonums), strings, byte vectors, characters, and immediate objects (true, false, nil, and the unspecific object) to be leaves, and everything else to be branches.