System Control

Procedure collect

(collect) => unspecified
(collect generation) => unspecified
(collect generation method) => unspecified

Collect initiates a garbage collection. If the system has multiple generations, then the optional arguments are interpreted as follows. The generation is the generation to collect, where 0 is the youngest generation. The method determines how the collection is performed. If method is the symbol collect, then a full collection is performed in that generation, whatever that means -- in a normal multi-generational copying collector, it means that all live objects in the generation's current semispace and all live objects from all younger generations are copied into the generation's other semispace. If method is the symbol promote, then live objects are promoted from younger generations into the target generation -- in our example collector, that means that the objects are copied into the target generation's current semispace.

The default value for generation is 0, and the default value for method is collect.

Note that the collector's internal policy settings may cause it to perform a more major type of collection than the one requested; for example, an attempt to collect generation 2 could cause the collector to promote all live data into generation 3.

Procedure GC-counter

(gc-counter) => fixnum

GC-counter returns the number of garbage collections performed since startup. On a 32-bit system, the counter wraps around every 1,073,741,824 collections.

GC-counter is a primitive and compiles to a single load instruction on the SPARC.

Procedure gcctl

(gcctl heap-number operation operand) => unspecified

[GCCTL is largely obsolete in the new garbage collector but may be resurrected in the future. It can still be used to control the non-predictive collector.]

gcctl controls garbage collection policy on a heap-wise basis. The heap-number is the heap to operate on, like for the command line switches: heap 1 is the youngest. If the given heap number does not correspond to a heap, gcctl fails silently.

The operation is a symbol that selects the operation to perform, and the operand is the operand to that operation, always a number. For the non-predictive garbage collector, the following operator/operand pairs are meaningful:

  • j-fixed, n: after a collection, the collector parameter j should be set to the value n, if possible. (Non-predictive heaps only.)
  • j-percent, n: after a collection, the collector parameter j should be set to be n percent of the number of free steps. (Non-predictive heaps only.)
  • incr-fixed, n: when growing the heap, the growing should be done in increments of n. In the non-predictive heap, n is the number of steps. In other heaps, n denotes kilobytes.
  • incr-percent, n: when growing the heap, the growing should be done in increments of n percent.

Example: if the non-predictive heap is heap number 2, then the expressions

        (gcctl 2 'j-fixed 0)
        (gcctl 2 'incr-fixed 1)
makes the non-predictive collector simulate a normal stop-and-copy collector (because j is always set to 0), and grows the heap only one step at a time as necessary. This may be useful for certain kinds of experiments.

Example: ditto, the expressions

        (gcctl 2 'j-percent 50)
        (gcctl 2 'incr-percent 20)
selects the default policy settings.

Note: The gcctl facility is experimental. A more developed facility will allow controlling heap contraction policy, as well as setting all the watermarks. Certainly one can envision other uses, too. Finally, it needs to be possible to get current values.

Note: Currently the non-predictive heap (np-sc-heap.c) and the standard stop-and-copy "old" heap (old-heap.c) are supported, but not the standard "young" heap (young-heap.c), nor the stop-and-copy collector (sc-heap.c).

Procedure sro

(sro pointer-tag type-tag limit) => vector

SRO ("standing room only") is a system primitive that traverses the entire heap and returns a vector that contains all live objects in the heap that satisfy the constraints imposed by its parameters:

For example, (sro -1 -1 -1) returns a vector that contains all live objects (not including the vector), and (sro 5 2 3) returns a vector containing all live flonums (bytevector-like, with typetag 2) that are referred to in no more than 3 places.

Procedure stats-dump-on

(stats-dump-on filename) => unspecified

Stats-dump-on turns on garbage collection statistics dumping. After each collection, a complete RTS statistics dump is appended to the file named by filename.

The file format and contents are documented in a banner written at the top of the output file. In addition, accessor procedures for the output structure are defined in the program Util/process-stats.sch.

Stats-dump-on does not perform an initial dump when the file is first opened; only at the first collection is the first set of statistics dumped. The user might therefore want to initiate a minor collection just after turning on dumping in order to have a baseline set of data.

Procedure stats-dump-off

(stats-dump-off) => unspecified

Stats-dump-off turns off garbage collection statistics dumping (which was turned on with stats-dump-on). It does not dump a final set of statistics before closing the file; therefore, the user may wish to initiate a minor collection before calling this procedure.

Procedure system-features

(system-features) => alist

System-features returns an association lists of system features. Most entries are self-explanatory. The following are a more subtle:

  • The value of architecture-name is Larceny's notion of the architecture for which it was compiled, not the architecture the program is currently running on. For example, the value of this feature is "Standard-C" if you're running Petit Larceny.
  • The value of heap-area-info is a vector of vectors, one subvector for each heap area in the running system. The subvector has four entries: the generation number, the area type, the current size, and additional information.

Procedure display-memstats

(display-memstats vector) => unspecified
(display-memstats vector 'minimal) => unspecified
(display-memstats vector 'full) => unspecified

Display-memstats takes as its argument a vector as returned by memstats and displays the contents of the vector in human-readable form on the current output port. By default, not all of the values in the vector are displayed.

If the symbol minimal is passed as the second argument, then only a small number of statistics generally relevant to running benchmarks are displayed.

If the symbol full is passed as the second argument, then all statistics are displayed.

Procedure memstats

(memstats) => vector

Memstats returns a freshly allocated vector containing run-time-system resource usage statistics. Many of these will make no sense whatsoever to you unless you also study the RTS sources. A listing of the contents of the vector is available here.

Procedure run-with-stats

(run-with-stats thunk) => obj

Run-with-stats evaluates thunk, then prints a short summary of run-time statistics, as with

   (display-memstats ... 'minimal),
and then returns the result of evaluating thunk.

Procedure run-benchmark

(run-benchmark name k thunk ok?) => obj

Run-benchmark prints a short banner (including the identifying name) to identify the benchmark, then runs thunk k times, and finally tests the value returned from the last call to thunk by applying the predicate ok? to it. If the predicate returns true, then run-benchmark prints summary statistics, as with

   (display-memstats ... 'minimal).
If the predicate returns false, an error is signalled.

$Id: syscontrol.html,v 1.5 1999/11/02 16:35:34 lth Exp $