Scieneer Common Lisp 1.3.9 online documentation

Garbage Collector


Garbage collector

The Scieneer Common Lisp uses are generational stop and copy garbage collector. Six object generations are available, numbered 0 to 5, and a seventh is used internally to hold the static built-in Scieneer Common Lisp code. New objects are allocated to generation 0 and when garbage is collected the live objects are progressively moved into older generations. Functions are available to modify the automatic garbage collection triggers, to force garbage collection, and to limit garbage collection. Much of the garbage collector state, including the object generations, is saved in lisp core files and is in effect when restarted.


ext:gc &key verbose gen full[Function]

Initiates a garbage collection of all generations below the given generation gen and moves all referenced objects in younger generations into generation gen. If the generation gen has reached its allocation trigger level and its object age trigger level then garbage in this generation will also be collected. Garbage collection of older generations may also occur if their allocation and age trigger levels are reached. If the gen is the keyword :full, or if the keyword argument :full is true then garbage is collected in all available generations. The keyword argument :verbose controls whether or not GC statistics are printed and defaults to the value of the variable ext:*gc-verbose*.

The function ext:gc-promote quickly moves objects into an older generation without collecting garbage and may be appropriate when it is known that most of the objects are referenced and will remain after garbage collection.

Garbage is automatically collected when allocation trigger levels and object age trigger levels are reached. See ext:bytes-consed-between-gcs, ext:generation-bytes-consed-between-gcs, and ext:generation-minimum-age-before-gc. All the objects in a generation are automatically promoted to the next older generation after garbage collection has occurred a specified number of times on the generation, see: ext:generation-gcs-before-promotion.

A number of mechanisms are available to inhibit garbage collection, see: ext:generation-gc-size-limit, ext:generation-gcs-before-promotion, ext:generation-expected-survival-rate, and ext:oldest-generation-to-gc.

ext:bytes-consed-between-gcs [Function]

Return the amount of memory that will be allocated before the next garbage collection of the youngest generation is initiated.

(setf (ext:bytes-consed-between-gcs ) bytes)[Function]

Set the amount of memory that may be allocated before the next garbage collection of the youngest generation is initiated.

ext:gc-promote generation[Function]

Promote the garbage collector generation of all lisp objects to be at least the given generation without collecting garbage. This can be a much faster way to move objects to an older generation than perform a garbage collection and may be appropriate when it is known that most objects are reachable and would remain after garbage collection,

ext:show-generations [Function]

Show a listing of the garbage collector generations.

ext:generation-bytes-consed-between-gcs generation[Function]

Return the number of bytes consed, or allocated, to the generation before garbage collection of the generation is automatically triggered. The average age of objects is also tested before garbage collection is automatically triggered, see ext:generation-minimum-age-before-gc. Garbage collection of the youngest generation is triggered by a separate mechanism, see ext:bytes-consed-between-gcs.

(setf (ext:generation-bytes-consed-between-gcs generation) bytes)[Function]

Set the number of bytes that the garbage collector allows to be consed, or allocated, to the generation before automatically triggering garbage collection of the generation. The default for all generations is 2000000 bytes. This parameter is saved in a lisp core file and is in effect when restarted. See also: ext:generation-bytes-consed-between-gcs, and ext:bytes-consed-between-gcs.

ext:generation-expected-survival-rate generation[Function]

Return the percentange of objects expected to survive garbage collection of the generation. The garbage collector uses this expected survival rate to estimate the memory required to perform the garbage collection and inhibits garbage collection if there is there is not be enough memory. During garbage collection, reachable objects are copied and this requires extra memory for the new copies - in the worst case the total memory required is twice the current amount of memory used by the generation. The percentage is the total number of bytes expected to be allocated to the generation after garbage collection divided by the number before garbage collection.

(setf (ext:generation-expected-survival-rate generation) rate)[Function]

Set the percentange of objects expected to survive garbage collection of the generation. Setting the percentage to zero prevents the garbage collector being inhibited and this is the default for all generations. This parameter is saved in a lisp core file and is in effect when restarted.

Setting this parameter to a non-zero value may allow an application to complete a computation without the risk of a large garbage collection exhausting available memory. While garbage collection of the generation is inhibited, younger objects will continue to be promoted into the generation and garbage will not be collected which will eventually cause the process to run out of memory. If an application has a large permanent heap then consider locking this into an older generation, see ext:oldest-generation-to-gc.

ext:generation-gc-size-limit generation[Function]

Return the size limit, in bytes, beyond which garbage collection will not be performed on the given generation. When the garbage collector encounters such a limit it finishes and does not continue with the next generation.

(setf (ext:generation-gc-size-limit generation) limit)[Function]

Set the size limit, in bytes, beyond which garbage collection will not be performed on the given generation. Setting the limit to zero effectively inhibits garbage collection for the generation or older generations. When the limit is the keyword :unlimited the size limit is set to the maximum making it effectively unlimited. This parameter is initially unlimited on all generations, and is saved in a lisp core file and is in effect when restarted.

Setting a generation GC limit is useful when building a large heap of persistent objects, in which case garbage collection will just copy the objects around and this can be very time consuming for a large heap. See also: ext:oldest-generation-to-gc.

ext:generation-gcs-before-promotion generation[Function]

Return the number of times that garbage must be collected in the generation before the objects in the generation are promoted.

(setf (ext:generation-gcs-before-promotion generation) gcs)[Function]

Set the number of times that garbage must be collected in the generation before the objects in the generation are promoted. Increasing the number of garbage collections required before promotion slow the progression of objects to older generations. The default for all generations is one garbage collection. This parameter is saved in a lisp core file and is in effect when restarted.

ext:generation-minimum-age-before-gc generation[Function]

Return the average memory age for the generation before garbage collection of the generation is automatically triggered. The age is a double-float and the unit of measurement is the number of times the garbage collection of the immediately younger generation has promoted objects to the generation. When objects are initially allocated to the generation their age is zero, and each time the immediately younger generation allocates objects to the generation the age of all objects in the generation increases by one. The age of all objects in the generation are averaged. The number of bytes allocated to the generation is also tested before automatically triggering garbage collection of the generation, see ext:generation-bytes-consed-between-gcs.

(setf (ext:generation-minimum-age-before-gc generation) age)[Function]

Set the average memory age for the generation before garbage collection of the generation is automatically triggered. The default for all generations is 0.75. Increasing the minimum age reduces the rate of garbage collection which in turn slows the progression of objects to older generations. This parameter is saved in a lisp core file and is in effect when restarted. See also: ext:generation-minimum-age-before-gc.

ext:oldest-generation-to-gc [Function]

Return the oldest generation for which garbage collection will occur. When garbage collection is performed on this genertation the reachable objects remain in this generation and are never raised to the next generation.

(setf (ext:oldest-generation-to-gc ) generation)[Function]

Set the oldest generation for which garbage collection will occur. This parameter is initially the oldest available generation, and is saved in a lisp core file and is in effect when restarted.

Applications with a large permanent memory heap can move objects into an older generation and then decrease the oldest generation subject to garbage collection which will prevent unnecessary garbage collection of the permanent objects and also prevent new objects being moved into this old permanent generation where garbage is not collected.

For applications that generate a lot of short lived objects the full set of generations may be a liability because they delay the collection of garbage. Decreasing the oldest generation subject to garbage collection reduces the number of generations available to new objects and may be appropriate for such applications.

Garbage collection of an older generation may be inhibited while still allowing younger objects to be promoted into it by setting a low generation garbage collection size limit, see: ext:generation-gc-size-limit.

ext:*gc-generations*[Constant]

The number of available garbage collector generations.


Example: Building a large heap

Building a large heap can be eased by tuning the garbage collector. If most objects allocated are persistent then repeated garbage collection just wastes time, and garbage collection of a heap larger than available memory can be very slow, so limiting garbage collection can be very useful. In this example garbage collection of generation one and older generations is inhibited. Most short lived objects will be garbage collected with generation zero and the persistent objects will collect in generation one. When done, all the objects are quickly moved into the oldest generation without garbage collecting, and then garbage collection of this generation is inhibited and also the promotion of objects to this generation is inhibited. The resulting heap can be saved, ready to quickly restart.

;;; Inhibit garbage collection of generations 1+.
(setf (ext:generation-gc-size-limit 1) 0)

;;; Build a relatively large heap...
(length (setf *a1* (make-array (* 512 1024 1024))))

;;; Move all objects into the oldest available generation 5.
(ext:gc-promote 5)

;;; Set the oldest generation subject to garbage collection to
;;; generation 4, preventing garbage collection of generation 5 and
;;; also preventing further objects being promoted into generation 5.
(setf (ext:oldest-generation-to-gc) 4)

;;; Reset the size limit on generation 1.
(setf (ext:generation-gc-size-limit 1) :unlimited)

;;; Save a lisp core file.
(ext:save-lisp "app.core")