Function

Summary

Does a Copying GC.

Package

hcl

Signature

gc-generation gen-num &key coalesce promote block => allocation

Arguments

gen-num

An integer between 0 and 7 inclusive, or t.

coalesce

A generalized boolean.

promote

A generalized boolean.

block

An integer between 0 and 7, inclusive, or one of the keywords :blocking-gen-num and :all.

Values

allocation

The total allocation in generation gen-num and younger generations.

Description

The function gc-generation does a Garbage Collection of a specific generation. The actual operation is different between 64-bit LispWorks and 32-bit LispWorks.

gen-num should be a valid generation number, or t. The value t is mapped to the blocking generation number in 64-bit LispWorks, and to 2 in 32-bit LispWorks. For backwards compatibility the keyword :blocking-gen-num is also accepted, with the same meaning as t.

It is especially helpful to GC the blocking generation (or other higher generations) when large, long-lived data structures become garbage. This is because higher generations are rarely collected by default. For the higher generations, the GC takes longer but recovers more space.

Another situation which may require gc-generation is when objects are marked for special free action (by flag-special-free-action or free-function in a weak hash table). If such objects live long enough to be promoted to higher generation, they may not be garbage collected long after there are no pointers to them. If the free action is important, you may need to periodically GC higher generation (typically the blocking generation, by passing gen-num t).

Operation in 64-bit LispWorks

By default gc-generation operates on the live objects in generation gen-num and all lower generations at or above the generation specified by block by copying them inside their current generation, and it operates on the live objects in generations lower than block by copying them to the next higher generation.

If promote is non-nil, the live objects in generation gen-num are also promoted to the next generation. That is the same operation that happens when the GC is invoked automatically. The default value of promote is nil.

If coalesce is non-nil, all non-static live objects in lower generations are promoted to generation gen-num. That is what clean-down does (with gen-num being the highest generation). It may be useful directly in some cases. The default value of coalesce is nil.

block specifies a generation number up to which to promote. An integer value specifies the generation number. If block is :blocking-gen-num, then gc-generation promotes up to the blocking generation. If block is :all, then gc-generation promotes nothing. The default value of block is :blocking-gen-num.

gc-generation is useful when you know points in your application where many objects tend to die, or when you know that that application is less heavily loaded at some time. Typically many objects die in the end (or beginning) of an iteration in a top level loop of the application, and that is normally a useful place to put a call to gc-generation of generation 2 or generation 3. If you know a time when the application can spend time garbage collecting, a call to gc-generation with a higher value of gen-num may be useful. It is probably never really useful to use gc-generation on generation 0 or 1.

To decide on which gen-num to call gc-generation, check which generation gets full by making periodic calls to room.

gc-generation with promote or coalesce may also be useful to move objects from the blocking generation to higher generations, which does not happen automatically (except when saving the image). For example, after loading a large amount of code, and before generating any data that may die shortly, assuming the blocking generation is 3, it may be useful to do:

(gc-generation 4 :coalesce t)

to move all (non-static) objects to generation 4, where they will not be touched by the GC any more (except following pointers to younger generations).

Operation in 32-bit LispWorks

gc-generation marks and sweeps the generation gen-num and all generations below, and then does some additional cleanups. coalesce, promote and block are ignored.

Compatibility notes

In 32-bit LispWorks, gc-generation simply calls mark-and-sweep. This has a similar effect, but two significant differences must be noted:

1. by default, gc-generation promotes the young generations, so repeated calls to gc-generation will promote everything to generation gen-num or generation block (whichever is lower). In contrast mark-and-sweep never promotes.
2. In 32-bit LispWorks, generation 2 is the blocking generation. In 64-bit LispWorks, the default blocking generation is generation 3. That is because the 64-bit implementation promotes faster and so needs more generations before the block.

Also note that

(gc-generation t)

is intended as the replacement of

(mark-and-sweep 2)

See also

clean-down
mark-and-sweep
marking-gc
set-blocking-gen-num
Guidance for control of the storage management system