6.19.4 Automatic finalisation of records

Vicare allows records to be finalised either explicitly or automatically by the garbage collector, by applying a destruction function to them; here is how automatic finalisation works:

#!r6rs
(import (vicare))

(define-record-type <alpha>
  (fields a b c))

(define (<alpha>-destructor rec)
  (fprintf (current-error-port) "finalising ~s\n" rec))

(record-type-destructor-set! (record-type-descriptor <alpha>)
                             <alpha>-destructor)

(pretty-print (make-<alpha> 1 2 3) (current-error-port))
-| (record <alpha> (a 1) (b 2) (c 3))

(collect)
-| finalising #[record <alpha> a=1 b=2 c=3]

A destructor function is associated to a record–type by registering it in the record–type descriptor. After a destructor is set in the descriptor: new instances of the record–type are registered, upon creation, into an internal guardian, iklib guardians for details; whenever such records are garbage collected: the guardian applies the destructor to them.

When the destructor is called by the garbage collector: exceptions raised by it are catched with guard and discarded; destructor functions should take care of exceptions by themselves.

It is possible for a destructor function to be applied multiple times to the same record: once a destructor is set in the descriptor, it can be explicitly applied to records and later applied again by the garbage collector. Destructor functions must be written in such a way that multiple applications are not a problem. For example, it is usually possible, upon destruction, to reset some record fields to the void object: when the destructor detects a field set to void, it knows that the record has already been finalised.

Function: record-type-destructor-set! rtd destructor

Select the procedure destructor as destructor for R6RS records of type rtd; return unspecified values. The destructor accepts a single argument being the record to finalise; the destructor can return unspecified values.

Function: record-type-destructor rtd

Return the function set in rtd as instance destructor; return #f if no destructor is set in rtd.

Function: record-destructor record

Return the current destructor for the record record: #f or a function.

Parameter: record-guardian-logger

Select a record destruction logging mode for debugging purposes. When a record is finalised by the garbage collector, using the destructor registered in the RTD:

• If this parameter is set to #f: no additional actions are performed.
• If this parameter is set to #t: the function record-guardian-log is used to log the operations to the textual output port returned by current-error-port.
• If this parameter is set to a procedure: such procedure is used to log the operations in a user selected way.

See the documentation of record-guardian-log for the calling protocol of the logger functions.

Function: record-guardian-log record exception action

Built in logger function to be used to log record finalisation operations by the garbage collector. record is the record to be finalised; exception is #f or an object raised by the record destructor; action is one of the symbols: before-destruction, after-destruction, exception.

When this function is used as value for the parameter record-guardian-logger:

• The function is called whenever a record is registered for destruction with action set to the symbol registration and exception set to #f.
• The function is called just before the record is finalised with action set to the symbol before-destruction and exception set to #f.
• The function is called right after the record has been finalised with action set to the symbol after-destruction and exception set to #f.
• If an exception is raised by the destructor: such exception is catched and this function is called with action set to exception and exception set to the raised object.

The current implementation is the following:

(define (record-guardian-log S E action)
  (case action
    ((registration)
     (fprintf (current-error-port)
       "*** Vicare debug: record guardian: registered record:\n\
        ***\t~s\n" S))
    ((before-destruction)
     (fprintf (current-error-port)
       "*** Vicare debug: record guardian: before destruction:\n\
        ***\t~s\n" S))
    ((after-destruction)
     (fprintf (current-error-port)
       "*** Vicare debug: record guardian: after destruction:\n\
        ***\t~s\n" S))
    ((exception)
     (fprintf (current-error-port)
       "*** Vicare debug: record guardian: exception:\n\
        ***\t~s\n\
        ***\t~s\n" S E))
    (else
     (assertion-violation 'record-guardian-log
       "invalid action in record destruction process" S action))))