Function

Summary

Attempts to reduce the size of the Lisp image, without enlarging it even temporarily.

Package

hcl

Signature

reduce-memory &optional full => new-size

Arguments

full

nil or t (or 0, 1, 2 or :aggressive on Mobile GC).

Values

new-size

A positive integer.

Description

The function reduce-memory frees memory and tries to reduce the size of the Lisp image, without enlarging it even temporarily.

reduce-memory has the same effect as clean-down, except that clean-down may temporarily increase the size of the image in order to be able to promote from lower generations. reduce-memory never increases the image size, which means that it may fail to promote. This will cause future garbage collections to be slower, until the promotion actually occurs.

reduce-memory is intended to be used when the operating system signals that the memory is low, which is a common feature of mobile platforms, for example onTrimMemory and onLowMemory in Android and didRceciveMemoryWarning in iOS. Using clean-down in this situation may cause a temporary increase in size, which may cause the system to run out of memory, or maybe just kill the Lisp process. In other circumstances clean-down should do a better job (and you might also consider try-move-in-generation).

In 32-bit LispWorks, if full is nil, reduce-memory frees memory and promotes live objects to generation 2. When full is non-nil, reduce-memory frees and promotes to generation 3.

In ordinary (Sparse) 64-bit LispWorks, full is ignored. The call just frees what it can free easily.

When using the Mobile GC, if full is nil, reduce-memory just frees what it can free easily. If full is t, reduce-memory performs a garbage collection on generation 2 and then frees what it can free easily. If full is :aggressive, reduce-memory performs one or more garbage collections until memory is no longer being freed and then frees what it can free easily. When full is a integer (0, 1 or 2), it specifies a generation number to garbage collect and reduce-memory garbage collects this generation and then frees what it can free easily. Using 2 is the same as using t.

The default value of full is nil.

reduce-memory returns the new size of the Lisp image after reduction, in bytes.

Notes

1. The default of full is nil, which is different from clean-down where it defaults to t.
2. In 32-bit LispWorks, reduce-memory with no argument or nil differs from (clean-down nil) by trying to reduce the memory. (clean-down nil) frees and promotes, but does not try to reduce the size (and may actually increase it).
3. When using the Mobile GC, reduce-memory releases any reserved memory that the system keeps. As a result any following reduce-memory with argument non-nil will be less effective because there will be no reserved memory to perform copying garbage collection.

See also

clean-down
try-move-in-generation (32-bit only)