set-memory-exhausted-callback

set-memory-exhausted-callback Function

Summary

Sets a callback that is called when memory is exhausted in 64-bit LispWorks.

Package

system

Signature

set-memory-exhausted-callback function &optional where => callbacks

Arguments

`function`⇩	A function designator, the keyword `:reset`, or `nil`.
`where`⇩	`:first`, `:last` or `nil`.

Values

callbacks

A list of function designators.

Description

The function set-memory-exhausted-callback adds a callback that is called when memory is exhausted. That is, when the system fails to map memory.

Note: set-memory-check is a more robust way to protect against memory exhaustion problems.

If function is a function designator then it should be a function with signature:

function gen-num size type-name static

function is expected to report what the system was trying to allocate when it failed to map memory. Its arguments are:

`gen-num`	The number of the generation in which it was trying to allocate.
`size`	The size in bytes which it was trying to allocate.
`type-name`	A string naming the allocation type it was trying to allocate.
`static`	A boolean, true if it was trying to allocate a static object, and false otherwise.

function can also have the special value :reset, which resets the callback list to nil.

function can also be nil, which means do nothing but simply return the current list of callbacks.

where defines the position in the list that the callback function is placed. Its allowed values are:

`:first`	`function` is placed first in the callbacks list.
`:last`	`function` is placed last in the callbacks list.
`nil`	`function` is removed from the callbacks list.

set-memory-exhausted-callback always first removes function from the callbacks list, and then adds it according to where. The default value of where is :first. Functions in the list are compared with equalp.

set-memory-exhausted-callback returns the callback list.

When a callback is called, Lisp already failed to map memory. This means that you must not rely on the callback to do real work. It should therefore attempt only a minimal amount of work such as clean-ups and generating debug information. It should not try to do real work.

After all the callbacks are called, the system signals an error of type storage-exhausted. The condition can be accessed using the accessors described for storage-exhausted.

Notes

set-memory-exhausted-callback is implemented only in 64-bit LispWorks. It is not relevant to the Memory Management API in 32-bit implementations.