set-blocking-gen-num

set-blocking-gen-num 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`⇩	A synonym for `max-size-to-copy`.
`max-size-to-copy`⇩	A positive real number, or `nil`.
`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 (or max-size) 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:

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.
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, max-size-to-copy, and the old value ofgc-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.