SBCL provides additional garbage collection functionality not specified by ANSI.
Called after each garbage collection, except for garbage collections triggered during thread exits. In a multithreaded environment these hooks may run in any thread.
Initiate a garbage collection.
gen
controls the number of generations to garbage collect.
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.
Arrange for the designated
function
to be called when there are no more references toobject
, including references infunction
itself.If
dont-save
is true, the finalizer will be cancelled whensave-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 environmentsfunction
may be called in any dynamic scope: consequences are unspecified iffunction
is not fully re-entrant.Errors from
function
are handled and cause awarning
to be signalled in whichever thread thefunction
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
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.
If
weak-pointer
is valid, return the value ofweak-pointer
andt
. If the referent ofweak-pointer
has been garbage collected, returns the valuesnil
andnil
.
Total
cpu
time spent doing garbage collection (as reported byget-internal-run-time
.) Initialized to zero on startup. It is safe to bind this to zero in order to measuregc
time inside a certain section of code, but doing so may interfere with results reported by eg.time
.
The amount of memory that will be allocated before the next garbage collection is initiated. This can be set with
setf
.
Average age of memory allocated to
generation:
average number of times objects allocated to the generation have seen younger objects promoted to it. Available ongencgc
platforms only.Experimental: interface subject to change.
Number of bytes allocated to
generation
currently. Available ongencgc
platforms only.Experimental: interface subject to change.
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): seebytes-consed-between-gcs
instead. Default is 20Mb. Can be assigned to usingsetf
. Available ongencgc
platforms only.Experimental: interface subject to change.
Minimum average age of objects allocated to
generation
before that generation is may be garbage collected. Default is 0.75. See alsogeneration-average-age
. Can be assigned to usingsetf
. Available ongencgc
platforms only.Experimental: interface subject to change.
Number of times garbage collection is done on
generation
before automatic promotion to the next generation is triggered. Can be assigned to usingsetf
. Available ongencgc
platforms only.Experimental: interface subject to change.
Number of times garbage collection has been done on
generation
without promotion. Available ongencgc
platforms only.Experimental: interface subject to change.
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.