Next: Metaobject Protocol, Up: Beyond the ANSI Standard
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.
gencontrols 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
functionto be called when there are no more references toobject, including references infunctionitself.If
dont-saveis true, the finalizer will be cancelled whensave-lisp-and-dieis called: this is useful for finalizers deallocating system memory, which might otherwise be called with addresses from the old image.In a multithreaded environment
functionmay be called in any thread. In both single and multithreaded environmentsfunctionmay be called in any dynamic scope: consequences are unspecified iffunctionis not fully re-entrant.Errors from
functionare handled and cause awarningto be signalled in whichever thread thefunctionwas 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-pointeris valid, return the value ofweak-pointerandt. If the referent ofweak-pointerhas been garbage collected, returns the valuesnilandnil.
Total
cputime 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 measuregctime 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 ongencgcplatforms only.Experimental: interface subject to change.
Number of bytes allocated to
generationcurrently. Available ongencgcplatforms only.Experimental: interface subject to change.
Number of bytes that can be allocated to
generationbefore that generation is considered for garbage collection. This value is meaningless for generation 0 (the nursery): seebytes-consed-between-gcsinstead. Default is 20Mb. Can be assigned to usingsetf. Available ongencgcplatforms only.Experimental: interface subject to change.
Minimum average age of objects allocated to
generationbefore that generation is may be garbage collected. Default is 0.75. See alsogeneration-average-age. Can be assigned to usingsetf. Available ongencgcplatforms only.Experimental: interface subject to change.
Number of times garbage collection is done on
generationbefore automatic promotion to the next generation is triggered. Can be assigned to usingsetf. Available ongencgcplatforms only.Experimental: interface subject to change.
Number of times garbage collection has been done on
generationwithout promotion. Available ongencgcplatforms 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-profilepackage does), or to design a more microefficient interface and submit it as a patch.