A guardian is a lisp object used to control when other data objects are recycled by the garbage collector (see Garbage Collection).7 The usual behaviour of the collector is to recycle objects as soon as they have no remaining references.
Guardians allow the programmer to detect when a specified object would be freed by the garbage collector, and to implement their own allocation policy. This can be useful, for example, with objects that have a high creation-overhead, and thus need to be cached for performance reasons.
This function allocates and returns a new guardian. Each guardian has a list of data objects associated with it; some of which may have been proved to have no remaining references to them (except from the guardian system).
Calling the guardian object with a single argument, adds that value to the list of objects associated with that guardian. Calling the guardian with no arguments has one of two effects:
Note the use of the word “prove” in the above description, objects are only moved into a guardian’s inaccessible set by the garbage collector.
Here is an example use of the guardian system:
;; create a new guardian object (setq G (make-guardian)) ;; create a lisp object (setq x (cons 'a 'b)) ⇒ (a . b) ;; protect the object using the guardian (G x) ;; remove the sole reference to the object (setq x nil) ⇒ () ;; invoke the garbage collector, this will ;; prove that the value added to the ;; guardian is no longer accessible (garbage-collect) ;; call the guardian to retrieve the ;; inaccessible value (G) ⇒ (a . b) ;; no more inaccessible values available (G) ⇒ ()
Guardians were first described in a paper by R. Kent Dybvig, Carl Bruggeman, and David Eby: "Guardians in a Generation-Based Garbage Collector", ACM SIGPLAN Conference on Programming Language Design and Implementation, June 1993.