elisp: Finalizer Type
2.3.18 Finalizer Type
---------------------
A “finalizer object” helps Lisp code clean up after objects that are no
longer needed. A finalizer holds a Lisp function object. When a
finalizer object becomes unreachable after a garbage collection pass,
Emacs calls the finalizer’s associated function object. When deciding
whether a finalizer is reachable, Emacs does not count references from
finalizer objects themselves, allowing you to use finalizers without
having to worry about accidentally capturing references to finalized
objects themselves.
Errors in finalizers are printed to ‘*Messages*’. Emacs runs a given
finalizer object’s associated function exactly once, even if that
function fails.
-- Function: make-finalizer function
Make a finalizer that will run FUNCTION. FUNCTION will be called
after garbage collection when the returned finalizer object becomes
unreachable. If the finalizer object is reachable only through
references from finalizer objects, it does not count as reachable
for the purpose of deciding whether to run FUNCTION. FUNCTION will
be run once per finalizer object.