16.4 Garbage Collection

Set the PLTDISABLEGC environment variable (to any value) before Racket starts to disable garbage collection. Set the PLT_INCREMENTAL_GC environment variable to a value that starts with 1, y, or Y to request incremental mode at all times, but calling (collect-garbage 'incremental) in a program with a periodic task is generally a better mechanism for requesting incremental mode. Set the PLT_INCREMENTAL_GC environment variable to a value that starts with 0, n, or N to disable incremental-mode requests.

Each garbage collection logs a message (see Logging) at the 'debug level with topic 'GC. In the 3m and CS variants of Racket, “major” collections are also logged at the 'debug level with the topic 'GC:major. In the 3m and CS variants of Racket, the data portion of the message is an instance of a gc-info prefab structure type with 10 fields as follows, but future versions of Racket may use a gc-info prefab structure with additional fields:

(struct gc-info (mode pre-amount pre-admin-amount code-amount

post-amount post-admin-amount

start-process-time end-process-time

start-time end-time)

#:prefab)

• The mode field is a symbol 'major, 'minor, or 'incremental; 'major indicates a collection that inspects all memory, 'minor indicates collection that mostly inspects just recent allocations, and 'incremental indicates a minor collection that performs extra work toward the next major collection.

  Changed in version 6.3.0.7 of package base: Changed first field from a boolean (#t for 'major, #f for 'minor) to a mode symbol.

• The pre-amount field reports place-local memory use (i.e., not counting the memory use of child places) in bytes at the time that the garbage collection started. Additional bytes registered via make-phantom-bytes are included.

• The pre-admin-amount is a larger number that includes memory use for the garbage collector’s overhead, such as space on memory pages that are mapped but not currently used.

• The code-amount field reports additional memory use for generated native code (which is the same just before and after a garbage collection, since it is released via finalization).

• The post-amount and post-admin-amount fields correspond to pre-amount and pre-admin-amount, but after garbage collection. In typical configurations, the difference between post-amount and pre-amount contributes to post-admin-amount, since reclaimed pages tend to stay in reserve with the expectation that they’ll be needed again (but the pages are released if multiple collections pass without need for the pages).

• The start-process-time and end-process-time fields report processor time (in the sense of current-process-milliseconds) at the start and end of garbage collection. The difference between the times is the processor time consumed by collection.

• The start-time and end-time fields report real time (in the sense of current-inexact-milliseconds) at the start and end of garbage collection. The difference between the times is the real time consumed by garbage collection.

The format of the logged message’s text is subject to change. Currently, after a prefix that indicates the place and collection mode, the text has the format

‹used›(‹admin›)[‹code›]; free ‹reclaimed›(‹adjust›) ‹elapsed› @ ‹timestamp›

‹used›		Collectable memory in use just prior to garbage collection
‹admin›		Additional memory used as to manage collectable memory
‹code›		Additional memory used for generated machine code
‹reclaimed›		Collectable memory reclaimed by garbage collection
‹adjust›		Negation of change to administrative memory minus ‹reclaimed›
‹elapsed›		Processor time used to perform garbage collection
‹timestamp›		Processor time since startup of garbage collection’s start

Changed in version 6.3.0.7 of package base: Added PLT_INCREMENTAL_GC.
Changed in version 7.6.0.9: Added major-collection logging for the topic 'GC:major.

• 'major — Forces a “major” collection, which inspects all memory. Some effectively unreachable data may remain uncollected, because the collector cannot prove that it is unreachable.

  This mode of collect-garbage procedure provides some control over the timing of collections, but garbage will obviously be collected even if this procedure is never called—unless garbage collection is disabled by setting PLTDISABLEGC.

• 'minor — Requests a “minor” collection, which mostly inspects only recent allocations. If minor collection is not supported (e.g., when (system-type 'gc) returns 'cgc) or if the next collection must be a major collection, no collection is performed. More generally, minor collections triggered by (collect-garbage 'minor) do not cause major collections any sooner than they would occur otherwise.

• 'incremental — Does not request an immediate collection, but requests extra effort going forward to avoid major collections, even if it requires more work per minor collection to incrementally perform the work of a major collection. This incremental-mode request expires at the next major collection.

  The intent of incremental mode is to significantly reduce pause times due to major collections, but incremental mode may imply longer minor-collection times and higher memory use. Currently, incremental mode is only meaningful when (system-type 'gc) returns '3m or 'cs; it has no effect in other Racket variants.

  If the PLT_INCREMENTAL_GC environment variable’s value starts with 0, n, or N on start-up, then incremental-mode requests are ignored.

Changed in version 6.3 of package base: Added the request argument.
Changed in version 6.3.0.2: Added 'incremental mode.
Changed in version 7.7.0.4: Added 'incremental effect for Racket CS.

• If mode is #f (the default), the result is an estimate of the number of bytes reachable from any custodian.

• If mode is 'cumulative, returns an estimate of the total number of bytes allocated since start up, including bytes that have since been reclaimed by garbage collection.

• If mode is a custodian, returns an estimate of the number of bytes of memory occupied by reachable data from mode. This estimate is calculated by the last garbage collection, and can be 0 if none occurred (or if none occurred since the given custodian was created). The current-memory-use function does not perform a collection by itself; doing one before the call will generally decrease the result (or increase it from 0 if no collections happened yet).

  When Racket is compiled without support for memory accounting, the estimate is the same as when mode is #f (i.e., all memory) for any individual custodian. See also custodian-memory-accounting-available?.

See also vector-set-performance-stats!.

Changed in version 6.6.0.3 of package base: Added 'cumulative mode.

Various combinations of v arguments can control the information in a dump. The information that is available depends on your Racket build; check the end of a dump from a particular build to see if it offers additional information; otherwise, all vs are ignored.