(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.
(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.
(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:
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).
(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.
(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.
(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.
(system-features) => alist
System-features returns an association lists of system features. Most entries are self-explanatory. The following are a more subtle:
(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.
(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.
(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.
(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.