Next: , Up: Beyond the ANSI Standard


7.1 Garbage Collection

SBCL provides additional garbage collection functionality not specified by ANSI.

— Variable: sb-ext:*after-gc-hooks*

Called after each garbage collection, except for garbage collections triggered during thread exits. In a multithreaded environment these hooks may run in any thread.

— Function: sb-ext:gc &key gen full &allow-other-keys

Initiate a garbage collection. gen controls the number of generations to garbage collect.

7.1.1 Finalization

Finalization allows code to be executed after an object has been garbage collected. This is useful for example for releasing foreign memory associated with a Lisp object.

— Function: sb-ext:finalize object function &key dont-save

Arrange for the designated function to be called when there are no more references to object, including references in function itself.

If dont-save is true, the finalizer will be cancelled when save-lisp-and-die is called: this is useful for finalizers deallocating system memory, which might otherwise be called with addresses from the old image.

In a multithreaded environment function may be called in any thread. In both single and multithreaded environments function may be called in any dynamic scope: consequences are unspecified if function is not fully re-entrant.

Errors from function are handled and cause a warning to be signalled in whichever thread the function was called in.

Examples:

            ;;; GOOD, assuming RELEASE-HANDLE is re-entrant.
            (let* ((handle (get-handle))
                   (object (make-object handle)))
             (finalize object (lambda () (release-handle handle)))
             object)
          
            ;;; BAD, finalizer refers to object being finalized, causing
            ;;; it to be retained indefinitely!
            (let* ((handle (get-handle))
                   (object (make-object handle)))
              (finalize object
                        (lambda ()
                          (release-handle (object-handle object)))))
          
            ;;; BAD, not re-entrant!
            (defvar *rec* nil)
          
            (defun oops ()
             (when *rec*
               (error "recursive OOPS"))
             (let ((*rec* t))
               (gc))) ; or just cons enough to cause one
          
            (progn
              (finalize "oops" #'oops)
              (oops)) ; GC causes re-entry to #'oops due to the finalizer
                      ; -> ERROR, caught, WARNING signalled

— Function: sb-ext:cancel-finalization object

Cancel any finalization for object.

7.1.2 Weak Pointers

Weak pointers allow references to objects to be maintained without keeping them from being garbage collected: useful for building caches among other things.

Hash tables can also have weak keys and values: see Hash Table Extensions.

— Function: sb-ext:make-weak-pointer object

Allocate and return a weak pointer which points to object.

— Function: sb-ext:weak-pointer-value weak-pointer

If weak-pointer is valid, return the value of weak-pointer and t. If the referent of weak-pointer has been garbage collected, returns the values nil and nil.

7.1.3 Introspection and Tuning

— Variable: sb-ext:*gc-run-time*

Total cpu time spent doing garbage collection (as reported by get-internal-run-time.) Initialized to zero on startup. It is safe to bind this to zero in order to measure gc time inside a certain section of code, but doing so may interfere with results reported by eg. time.

— Function: sb-ext:bytes-consed-between-gcs

The amount of memory that will be allocated before the next garbage collection is initiated. This can be set with setf.

— Function: sb-ext:generation-average-age generation

Average age of memory allocated to generation: average number of times objects allocated to the generation have seen younger objects promoted to it. Available on gencgc platforms only.

Experimental: interface subject to change.

— Function: sb-ext:generation-bytes-allocated generation

Number of bytes allocated to generation currently. Available on gencgc platforms only.

Experimental: interface subject to change.

— Function: sb-ext:generation-bytes-consed-between-gcs generation

Number of bytes that can be allocated to generation before that generation is considered for garbage collection. This value is meaningless for generation 0 (the nursery): see bytes-consed-between-gcs instead. Default is 20Mb. Can be assigned to using setf. Available on gencgc platforms only.

Experimental: interface subject to change.

— Function: sb-ext:generation-minimum-age-before-gc generation

Minimum average age of objects allocated to generation before that generation is may be garbage collected. Default is 0.75. See also generation-average-age. Can be assigned to using setf. Available on gencgc platforms only.

Experimental: interface subject to change.

— Function: sb-ext:generation-number-of-gcs-before-promotion generation

Number of times garbage collection is done on generation before automatic promotion to the next generation is triggered. Can be assigned to using setf. Available on gencgc platforms only.

Experimental: interface subject to change.

— Function: sb-ext:generation-number-of-gcs generation

Number of times garbage collection has been done on generation without promotion. Available on gencgc platforms only.

Experimental: interface subject to change.

— Function: sb-ext:get-bytes-consed

Return the number of bytes consed since the program began. Typically this result will be a consed bignum, so if you have an application (e.g. profiling) which can't tolerate the overhead of consing bignums, you'll probably want either to hack in at a lower level (as the code in the sb-profile package does), or to design a more microefficient interface and submit it as a patch.