Function

Summary

Sets the blocking generation in 64-bit LispWorks.

Package

system

Signature

set-blocking-gen-num gen-num &key do-gc max-size max-size-to-copy gc-threshold => old-blocking-gen-num, do-gc, max-size-to-copy, old-gc-threshold

Arguments

gen-num

An integer between 0 and 7, inclusive.

do-gc

One of t, nil and :mark, or a real number between 0 and 10, inclusive.

max-size-to-copy

A positive real number, or nil.

max-size

A synonym for max-size-to-copy.

gc-threshold

An integer greater than 12800, or a real in the inclusive range [0 100], or nil.

Values

old-blocking-gen-num

An integer between 0 and 7, inclusive.

do-gc

One of t, nil and :mark, or a real number between 0 and 10, inclusive.

max-size-to-copy

A positive real number.

old-gc-threshold

A number.

Description

The function set-blocking-gen-num sets gen-num as the generation that blocks. That is, no object is automatically promoted out of generation gen-num to a higher generation.

If do-gc is non-nil, then generation gen-num is automatically collected when needed, as defined by gc-threshold (see set-gen-num-gc-threshold).

The actual value of do-gc specifies how to GC the blocking generation when required. The possible values of do-gc are interpreted as follows:

t

Use Copying GC.

:mark

Use Marking GC.

A number in the inclusive range [0, 10]

Use Marking GC with copying of fragmented segments. The value specifies the fragmentation-threshold (the same as the argument to marking-gc). This is the ratio between the amount of free space that cannot be easily used and the amount of allocated space inside a segment. Only segments with fragmentation higher than the threshold are copied.

The default value of do-gc is t.

max-size-to-copy is meaningful only if do-gc is a number. It specifies the maximum size in Gigabytes to try to copy. If the fragmented segments contain more data than this value, only some of them are copied in each GC.

If gc-threshold is non-nil, it is used to set the threshold for automatic GC using set-gen-num-gc-threshold.

The initial setup is as if this call has been made:

(sys:set-blocking-gen-num 3)

That is, the system will GC automatically according to the default gc-threshold using Copying GC.

Setting the blocking generation gen-num to a lower number is useful into two situations:

1. When you have an operation that allocates a significant amount of data, and almost of it goes when the operation finishes, it is useful to reduce the blocking gen-num during the operation. The macro block-promotion is a convenient way of doing that.
2. If you have a good idea of how your application behaves, it may be useful to block at a lower generation (2 or 1), and then periodically call gc-generation explicitly to promote long living objects to a higher generation. The advantage of doing this is that you can call gc-generation in places where you know there are not many short-lived objects alive.

Passing a do-gc value other than t is useful when the blocking generation can be large enough that copying it all may cause very serious paging. Passing do-gc :mark will stop the system from copying the blocking generation, but may cause fragmentation if a significant number of long-lived objects die after a while, and there are not explicit calls to gc-generation or marking-gc.

set-blocking-gen-num returns four values: the old blocking generation number, the old value of do-gc, the max-size-to-copy, and the old value of gc-threshold. It can be called with gen-num nil to query the values without changing any of them.

Notes

set-blocking-gen-num is implemented only in 64-bit LispWorks. It does nothing in the Mobile GC and its return value is not meaningful. It is not relevant to the Memory Management API in 32-bit implementations.

See also

block-promotion
gc-generation
marking-gc
set-automatic-gc-callback
set-gen-num-gc-threshold
Guidance for control of the memory management system