release-object-and-nullify

release-object-and-nullify Macro

Summary

64-bit LispWorks only: Explicitly release the memory of an object if possible.

Package

system

Signature

release-object-and-nullify place => released-p

Arguments

place⇩

A generalized reference (see the Common Lisp definition).

Values

released-p

A boolean.

Description

The macro release-object-and-nullify checks if place contains a pointer to an object that can be explicitly released, and if it does then it frees the object and sets place to nil.

place must be the only reference to the object to be released, and no other thread can be still accessing the object. release-object-and-nullify releases the memory and stores nil in place, so there is no dangling pointer to the object.

The released memory is returned to the operating system for objects that are allocated in their own segment. Currently, these are objects larger than 1 MB in the Mobile GC, larger than 64 MB in the ordinary 64-bit GC. For other objects, the memory will eventually be reclaimed by the GC, except for permanent objects that are not in their own segment, which are never reclaimed.

release-object-and-nullify cannot be executed in interpreted code (because the interpreted code would keep pointers to the object). It must be compiled.

Notes

If the pointer in place is not the only reference, then you will be left with "dangling" pointers to a free memory, with unpredictable results.

release-object-and-nullify is mainly intended to be used with references to the large objects that are allocated in their own segment, where it can return the memory to the operating system, and hence reduce the memory usage substantially without waiting for a GC. In particular, it is the only way to release the memory of such objects that were made permanent in the Mobile GC. This is the main purpose of it.

Since release-object-and-nullify does not release the memory for objects that are not in their own segment, it is not very useful for such objects. However, it may have a useful effect when called on an object that contains pointers and is in a higher generation, because objects in lower generations that are kept alive because of pointers from this object can be GCed earlier, but in most cases it probably does not justify the effort. release-object-and-nullify can be called with a reference to a permanent object too, and if it is allocated in its own segment then the memory will also be released.

release-object-and-nullify releases only the object that is referenced by place, but not anything that this object points to, which means that you may not get the effect you expect for an object that is complex, such as a hash-table, a CLOS instance, a pathname or a non-simple array.