System Control

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.

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

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)

Example: ditto, the expressions

        (gcctl 2 'j-percent 50)
        (gcctl 2 'incr-percent 20)

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).

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.

• 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.