GNU Info

(librep.info)Guardians

---

Next: Streams Prev: Hash Tables Up: The language

---

Enter node , (file) or (file)node

Guardians
=========

   A "guardian" is a lisp object used to control when other data
objects are recycled by the garbage collector (Note: Garbage
Collection).(1) 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.

 - Function: make-guardian
     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:

        * If objects are associated with the guardian that have been
          proved to be inaccessible, then return one of those objects,
          and remove it from the list of objects associated with the
          guardian.

        * If none of the associated objects have been proved to be
          inaccessible, then return the value false.

   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)
        => ()

   ---------- Footnotes ----------

   (1) 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.'