1.0.11.1: Handle set-but-empty environment variables
[sbcl.git] / src / code / final.lisp
1 ;;;; finalization based on weak pointers
2
3 ;;;; This software is part of the SBCL system. See the README file for
4 ;;;; more information.
5 ;;;;
6 ;;;; This software is derived from the CMU CL system, which was
7 ;;;; written at Carnegie Mellon University and released into the
8 ;;;; public domain. The software is in the public domain and is
9 ;;;; provided with absolutely no warranty. See the COPYING and CREDITS
10 ;;;; files for more information.
11
12 (in-package "SB!IMPL")
13
14 (defvar *finalizer-store* nil)
15
16 (defvar *finalizer-store-lock*
17   (sb!thread:make-mutex :name "Finalizer store lock."))
18
19 (defmacro with-finalizer-store-lock (&body body)
20   `(sb!thread::call-with-system-mutex (lambda () ,@body)
21                                       *finalizer-store-lock*
22                                       t))
23
24 (defun finalize (object function &key dont-save)
25   #!+sb-doc
26   "Arrange for the designated FUNCTION to be called when there
27 are no more references to OBJECT, including references in
28 FUNCTION itself.
29
30 If DONT-SAVE is true, the finalizer will be cancelled when
31 SAVE-LISP-AND-DIE is called: this is useful for finalizers
32 deallocating system memory, which might otherwise be called
33 with addresses from the old image.
34
35 In a multithreaded environment FUNCTION may be called in any
36 thread. In both single and multithreaded environments FUNCTION
37 may be called in any dynamic scope: consequences are unspecified
38 if FUNCTION is not fully re-entrant.
39
40 Errors from FUNCTION are handled and cause a WARNING to be
41 signalled in whichever thread the FUNCTION was called in.
42
43 Examples:
44
45   ;;; good (assumes RELEASE-HANDLE is re-entrant)
46   (let* ((handle (get-handle))
47          (object (make-object handle)))
48    (finalize object (lambda () (release-handle handle)))
49    object)
50
51   ;;; bad, finalizer refers to object being finalized, causing
52   ;;; it to be retained indefinitely
53   (let* ((handle (get-handle))
54          (object (make-object handle)))
55     (finalize object (lambda () (release-handle (object-handle object)))))
56
57   ;;; bad, not re-entrant
58   (defvar *rec* nil)
59
60   (defun oops ()
61    (when *rec*
62      (error \"recursive OOPS\"))
63    (let ((*rec* t))
64      (gc))) ; or just cons enough to cause one
65
66   (progn
67     (finalize \"oops\" #'oops)
68     (oops)) ; causes GC and re-entry to #'oops due to the finalizer
69             ; -> ERROR, caught, WARNING signalled"
70   (unless object
71     (error "Cannot finalize NIL."))
72   (with-finalizer-store-lock
73     (push (list (make-weak-pointer object) function dont-save)
74           *finalizer-store*))
75   object)
76
77 (defun deinit-finalizers ()
78   ;; remove :dont-save finalizers
79   (with-finalizer-store-lock
80     (setf *finalizer-store* (delete-if #'third *finalizer-store*)))
81   nil)
82
83 (defun cancel-finalization (object)
84   #!+sb-doc
85   "Cancel any finalization for OBJECT."
86   ;; Check for NIL to avoid deleting finalizers that are waiting to be
87   ;; run.
88   (when object
89     (with-finalizer-store-lock
90         (setf *finalizer-store*
91               (delete object *finalizer-store*
92                       :key (lambda (list)
93                              (weak-pointer-value (car list))))))
94     object))
95
96 (defun run-pending-finalizers ()
97   (let (pending)
98     (with-finalizer-store-lock
99         (setf *finalizer-store*
100               (delete-if (lambda (list)
101                            (when (null (weak-pointer-value (car list)))
102                              (push (second list) pending)
103                              t))
104                           *finalizer-store*)))
105     ;; We want to run the finalizer bodies outside the lock in case
106     ;; finalization of X causes finalization to be added for Y.
107     (dolist (fun pending)
108       (handler-case
109           (funcall fun)
110         (error (c)
111           (warn "Error calling finalizer ~S:~%  ~S" fun c)))))
112   nil)