5.15 Finalization

The (hoot finalization) module provides an interface for the JavaScript FinalizationRegistry class, which notifies user code when a registered object has been garbage collected. Finalization registries are quite different from Guile’s guardians:

• Guardians return references to the objects they have protected from garbage collection. Finalization registries do not protect objects from garbage collection at all. Instead, when a registered object is garbage collected, the finalization registry passes along a user-specified “held value”. A held value cannot be a reference to the object being registered for finalization.
• Guardians are polled, whereas finalization registries use an asynchronous callback function.
• Finalization registries allow objects to be unregistered, whereas objects cannot be removed from a guardian once they have been added.

The following contrived example will print “hey” when the registered object is garbage collected:

(define (cleanup x)
  (display x)
  (newline))
(define registry (make-finalization-registry cleanup))
(finalization-registry-register! registry (list 'garbage) 'hey)

Procedure: make-finalization-registry cleanup ¶

Return a new finalization registry that will call cleanup (a procedure of one argument) whenever a registered object is garbage collected.

Procedure: finalization-registry? obj ¶

Return #t if obj is a finalization registry.

Procedure: finalization-registry-register! registry target held-value [unregister-token] ¶

Register target with registry. When target is garbage collected, the cleanup callback will receive held-value. held-value cannot be eq? to target.

If unregister-token is specified and not #f then this token can be used to unregister target later.

Procedure: finalization-registry-unregister! registry unregister-token ¶

Unregister the objects associated with unregister-token from registry. Return #t if at least one object was unregistered this way.