2.4 Garbage Collection

This section describes procedures that control garbage collection. See Memory Usage, for a discussion of how MIT/GNU Scheme uses memory.

procedure: gc-flip [safety-margin]

Forces a garbage collection to occur. Returns the number of words of storage available after collection, an exact non-negative integer.

Safety-margin determines the number of words of storage available to system tasks after the need for a garbage collection is detected and before the garbage collector is started. (An example of such a system task is changing the run-light to show “gc” when scheme is running under Emacs.) Caution: You should not specify safety-margin unless you know what you are doing. If you specify a value that is too small, you can put Scheme in an unusable state.

procedure: purify object [pure-space? [queue?]]

Moves object from the heap into constant space. Has no effect if object is already stored in constant space. Object is moved in its entirety; if it is a compound object such as a list, a vector, or a record, then all of the objects that object points to are also moved to constant space. See Memory Usage.

The optional argument pure-space? is obsolete; it defaults to #t and when explicitly specified should always be #t.

The optional argument queue?, if #f, specifies that object should be moved to constant space immediately; otherwise object is queued to be moved during the next garbage collection. This argument defaults to #t. The reason for queuing these requests is that moving an object to constant space requires a garbage collection to occur, a relatively slow process. By queuing the requests, this overhead is avoided, because moving an object during a garbage collection has no effect on the time of the garbage collection. Furthermore, if several requests are queued, they can all be processed together in one garbage collection, while if done separately they would each require their own garbage collection.

procedure: flush-purification-queue!

Forces any pending queued purification requests to be processed. This examines the purify queue, and if it contains any requests, forces a garbage collection to process them. If the queue is empty, does nothing.

procedure: print-gc-statistics

Prints out information about memory allocation and the garbage collector. The information is printed to the current output port. Shows how much space is “in use” and how much is “free”, separately for the heap and constant space. The amounts are shown in words, and also in 1024-word blocks; the block figures make it convenient to use these numbers to adjust the arguments given to the --heap and --constant command-line options. Following the allocation figures, information about the most recent 8 garbage collections is shown, in the same format as a GC notification.

Note that these numbers are accurate at the time that print-gc-statistics is called. In the case of the heap, the “in use” figure shows how much memory has been used since the last garbage collection, and includes all live objects as well as any uncollected garbage that has accumulated since then. The only accurate way to determine the size of live storage is to subtract the value of ‘(gc-flip)’ from the size of the heap. The size of the heap can be determined by adding the “in use” and “free” figures reported by print-gc-statistics.

(print-gc-statistics)
constant in use:   534121 words =   521 blocks +  617 words
constant free:        128 words =     0 blocks +  128 words
heap in use:        34845 words =    34 blocks +   29 words
heap free:         205530 words =   200 blocks +  730 words
GC #1: took: 0.13 (81%) CPU time, 0.15 (1%) real time; free: 207210
;No value

procedure: set-gc-notification! [on?]

Controls whether the user is notified of garbage collections. If on? is true, notification is enabled; otherwise notification is disabled. If on? is not given, it defaults to #t. When Scheme starts, notification is disabled.

The notification appears as a single line like the following, showing how many garbage collections have occurred, the time taken to perform the garbage collection and the free storage remaining (in words) after collection.

GC #5: took: 0.50 (8%) CPU time, 0.70 (2%) real time; free: 364346

To operate comfortably, the amount of free storage after garbage collection should be a substantial proportion of the heap size. If the CPU time percentage is consistently high (over 20%), you should consider running with a larger heap. A rough rule of thumb to halve the GC overhead is to take the amount of free storage, divide by 1000, and add this figure to the current value used for the --heap command-line option. Unfortunately there is no way to adjust the heap size without restarting Scheme.

procedure: toggle-gc-notification!

Toggles GC notification on and off. If GC notification is turned on, turns it off; otherwise turns it on.