6.42.2 Guardians programming interface

Function: make-guardian

Build and return a new guardian object: a closure that can be called with one or zero arguments, and that is interfaced with the garbage collector of Vicare in a non–portable way.

The guardian work like this:

• When the closure is called with one argument: it adds the argument to an internal set of “guarded values”, accessible to the garbage collector; the return value if the argument itself.
• When the garbage collector detects no other references to a value in the set of guarded values: the guardian removes it from the set and appends it to an internal queue (FIFO).
• When the closure is called with zero arguments: it removes the first value from the internal queue and returns it; if no values are in the queue it returns #f.

After an object has been returned by the guardian, it is no more “guarded” so it will be garbage collected when it will become inaccessible (unless it is again registered in a guardian).

NOTE It is possible to register an object in more than one guardian; when the object is found inaccessible all the guardian closures that have it will return it to the caller. This may lead to invalid finalisation operations, it is the responsibility of the programmer to avoid this.

NOTE It is possible to register an object multiple times in the same guardian; when the object is found inaccessible the guardian closure that has it will return it to the caller multiple times. This may lead to invalid finalisation operations, it is the responsibility of the programmer to avoid this.

Parameter: post-gc-hooks

Hold a list of thunks evaluated after each garbage collection run. It can be used to run a guardian cleanup function like this (using the example in the previous section):

(define (run-block-guardian)
  (do ((p (block-guardian) (block-guardian)))
      ((not p))
    (free p)))

(post-gc-hooks
 (cons run-block-guardian
  (post-gc-hooks)))