interrupts enabled.
* incompatible change: support for *BEFORE-GC-HOOKS* (that have been
inoperational for a while now) has been completely removed.
- * Null lexical environments are now printed as #<NULL-LEXENV>,
+ * null lexical environments are now printed as #<NULL-LEXENV>,
significantly reducing the amount of clutter in typical backtraces.
+ * documentation on weak pointers, finalization, and after GC hooks
+ has been added to the manual.
* optimization: REPLACE on declared (UNSIGNED-BYTE 8) vectors, as well
as other specialized array types, is much faster. SUBSEQ and
COPY-SEQ on such arrays have also been sped up.
it still has quite a few. @xref{Contributed Modules}.
@menu
-* Things Which Might Be In The Next ANSI Standard::
+* Garbage Collection::
+* Metaobject Protocol::
* Support For Unix::
* Customization Hooks for Users::
* Tools To Help Developers::
-* Resolution of Name Conflicts::
+* Resolution of Name Conflicts::
* Stale Extensions::
* Efficiency Hacks::
@end menu
-@node Things Which Might Be In The Next ANSI Standard
+@node Garbage Collection
@comment node-name, next, previous, up
-@section Things Which Might Be In The Next ANSI Standard
-
-SBCL provides extensive support for calling external C code,
-@ref{Foreign Function Interface}.
+@section Garbage Collection
SBCL provides additional garbage collection functionality not
specified by ANSI. Weak pointers allow references to objects to be
-maintained without keeping them from being GCed (garbage
-collected). And ``finalization'' hooks are available to cause code to
-be executed when an object has been GCed.
-@c <!-- FIXME: Actually documenting these would be good.:-| -->
-
-SBCL supports @dfn{Gray streams}, user-overloadable CLOS classes whose
-instances can be used as Lisp streams (e.g. passed as the first
-argument to @code{format}). Additionally, the bundled contrib module
-@dfn{sb-simple-streams} implements a subset of the Franz Allegro
-simple-streams proposal.
-
-SBCL supports a MetaObject Protocol which is intended to be compatible
+maintained without keeping them from being garbage collected, and
+``finalization'' hooks are available to cause code to be executed when
+an object has been garbage collected. Additionally users can specify
+their own cleanup actions to be executed with garbage collection.
+
+@include fun-sb-ext-finalize.texinfo
+@include fun-sb-ext-cancel-finalization.texinfo
+@include fun-sb-ext-make-weak-pointer.texinfo
+@include fun-sb-ext-weak-pointer-value.texinfo
+@include var-sb-ext-star-after-gc-hooks-star.texinfo
+
+@node Metaobject Protocol
+@comment node-name, next, previous, up
+@section Metaobject Protocol
+
+SBCL supports a metaobject protocol which is intended to be compatible
with AMOP; present exceptions to this (as distinct from current bugs)
are:
(defun finalize (object function)
#!+sb-doc
"Arrange for the designated FUNCTION to be called when there
-are no more references to OBJECT. In a multithreaded environment
-the finalizer may run in any thread."
- (sb!thread:with-mutex (*finalizer-store-lock*)
- (push (cons (make-weak-pointer object) function)
- *finalizer-store*))
+are no more references to OBJECT, including references in
+FUNCTION itself.
+
+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
+ (let* ((handle (get-handle))
+ (object (make-object handle)))
+ ;; assumes RELEASE-HANDLE is re-entrant
+ (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)) ; causes GC and re-entry to #'oops due to the finalizer
+ ; -> ERROR, caught, WARNING signalled"
+ (sb!sys:without-gcing
+ (sb!thread:with-mutex (*finalizer-store-lock*)
+ (push (cons (make-weak-pointer object) function)
+ *finalizer-store*)))
object)
(defun cancel-finalization (object)
;; Check for NIL to avoid deleting finalizers that are waiting to be
;; run.
(when object
- (sb!thread:with-mutex (*finalizer-store-lock*)
- (setf *finalizer-store*
- (delete object *finalizer-store*
- :key (lambda (pair)
- (weak-pointer-value (car pair))))))
+ (sb!sys:without-gcing
+ (sb!thread:with-mutex (*finalizer-store-lock*)
+ (setf *finalizer-store*
+ (delete object *finalizer-store*
+ :key (lambda (pair)
+ (weak-pointer-value (car pair)))))))
object))
(defun run-pending-finalizers ()
(let (pending)
- (sb!thread:with-mutex (*finalizer-store-lock*)
- (setf *finalizer-store*
- (delete-if (lambda (pair)
- (when (null (weak-pointer-value (car pair)))
- (push (cdr pair) pending)
- t))
- *finalizer-store*)))
+ (sb!sys:without-gcing
+ (sb!thread:with-mutex (*finalizer-store-lock*)
+ (setf *finalizer-store*
+ (delete-if (lambda (pair)
+ (when (null (weak-pointer-value (car pair)))
+ (push (cdr pair) pending)
+ t))
+ *finalizer-store*))))
;; We want to run the finalizer bodies outside the lock in case
;; finalization of X causes finalization to be added for Y.
(dolist (fun pending)
(defun make-weak-pointer (object)
#!+sb-doc
"Allocate and return a weak pointer which points to OBJECT."
- (declare (values weak-pointer))
(make-weak-pointer object))
#!-sb-fluid (declaim (inline weak-pointer-value))
(defun weak-pointer-value (weak-pointer)
#!+sb-doc
"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."
- (declare (type weak-pointer weak-pointer)
- (values t (member t nil)))
+If the referent of WEAK-POINTER has been garbage collected,
+returns the values NIL and NIL."
+ (declare (type weak-pointer weak-pointer))
;; We don't need to wrap this with a WITHOUT-GCING, because once we
;; have extracted the value, our reference to it will keep the weak
;; pointer from becoming broken. We just have to make sure the
;;; checkins which aren't released. (And occasionally for internal
;;; versions, especially for internal versions off the main CVS
;;; branch, it gets hairier, e.g. "0.pre7.14.flaky4.13".)
-"0.8.21.30"
+"0.8.21.31"
projects / sbcl.git / commitdiff