On this page:
collect-garbage
current-memory-use
dump-memory-stats

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

procedure

(collect-garbage [request])  void?

  request : (or/c 'major 'minor 'incremental) = 'major
Requests an immediate garbage collection or requests a garbage-collection mode, depending on request:

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.

procedure

(current-memory-use [mode])  exact-nonnegative-integer?

  mode : (or/c #f 'cumulative custodian?) = #f
Returns information about memory use:

See also vector-set-performance-stats!.

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

procedure

(dump-memory-stats v ...)  any

  v : any/c
Dumps information about memory usage to the low-level error port or console.

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.