schedule-finalization

Arguments: object function &key queue

Returns a finalization for object. When the garbage collector identifies object as garbage (meaning only the finalization and possibly weak vectors reference it), the garbage collector notes this fact and when it finishes garbage collecting, it either (depending on the value of the queue argument) calls the function denoted by function with object as the single argument or enqueues a list of two elements (the function from the finalization and the object in question) on the queue denoted by queue.

When the system sees that a finalization should be applied, it creates a hard reference to the object until the finalization is applied, preventing additional finalizations on that object from triggering until after the finalization is complete. Any particular finalization will only trigger once. When the triggered finalization is about to be applied, either by calling the finalization function or by enqueueing the list, its hard reference to the object is broken, so that even if the finalization object remains live, it will not keep the object alive. Then the finalization function is called (if queue is nil) or enqueued (if queue is true) and the finalization is disabled.

When queue is nil, the function is called and after a finalization function returns, the finalization is disabled so that (assuming that nothing in function caused object not to be garbage) the object is again identified as garbage during the next garbage collection and then scavenged (or global gc'ed) away.

If queue is non-nil, it must be an instance of mp:queue. As said, the system only places the list of the finalization function and the object on that queue. It is the programs responsibility to apply the function call-finalizer to that list.

object can be any Lisp object; function can be a function object or a symbol denoting a function. The function must accept one argument.

Multiple finalizations can be scheduled for the same object; all are run if and when the gc identifies the object as garbage, though not necessarily during the same gc. The order of the running of multiple finalizations is unspecified. The functions may be run asynchronously after being triggered by a gc.

A finalization can be unscheduled with unschedule-finalization.

See also gc.htm for general information on garbage collection Allegro CL. See section Finalizations in that document for details of finalizations.

Copyright (c) 1998-2022, Franz Inc. Lafayette, CA., USA. All rights reserved.
This page was not revised from the 10.0 page.
Created 2019.8.20.