Finalizer documentation, minor improvements

* doc/lispref/objects.texi (Finalizer Type): New section
(Type Predicates): Mention finalizers in `type-of' documentation.
* doc/lispref/elisp.texi (Top): Link to finalizer type.

* src/data.c (Ftype_of): Make `type-of' work with finalizers.
(syms_of_data): Register Qfinalizer.

* src/print.c (print_object): Print whether a finalizer has
been called.

* test/automated/finalizer-tests.el (finalizer-object-type): Test that
`type-of' works correctly for finalizers.

diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index e7d79d55c7e8f768884ea305baa090aa32ed7cdf..c27805b3d6e4c51c338135862a4c41597a896f70 100644 (file)
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,3 +1,9 @@
+2015-03-03  Daniel Colascione  <dancol@dancol.org>
+
+       * objects.texi (Finalizer Type): New section for finalizer objects.
+       (Type Predicates): Mention finalizers in `type-of' documentation.
+       * elisp.texi (Top): Link to finalizer type.
+
 2015-03-02  Daniel Colascione  <dancol@dancol.org>
 
        * control.texi (Generators): New section

diff --git a/doc/lispref/elisp.texi b/doc/lispref/elisp.texi
index 3802e49ec3df502b697e1bf4ac919e923be9199f..fc552be161b5eb1c0f2de4961dfe42860e8af3f0 100644 (file)
--- a/doc/lispref/elisp.texi
+++ b/doc/lispref/elisp.texi
@@ -316,6 +316,7 @@ Programming Types
 * Byte-Code Type::      A function written in Lisp, then compiled.
 * Autoload Type::       A type used for automatically loading seldom-used
                           functions.
+* Finalizer Type::      Runs code when no longer reachable.
 
 Character Type
 

diff --git a/doc/lispref/objects.texi b/doc/lispref/objects.texi
index ba28b63f0de9607675bdef69e8079b9fbfdd2cbd..b28b3b00898a896db86ebdee235d29039dd4bb39 100644 (file)
--- a/doc/lispref/objects.texi
+++ b/doc/lispref/objects.texi
@@ -156,6 +156,8 @@ latter are unique to Emacs Lisp.
 * Byte-Code Type::      A function written in Lisp, then compiled.
 * Autoload Type::       A type used for automatically loading seldom-used
                         functions.
+* Finalizer Type::      Runs code when no longer reachable.
+
 @end menu
 
 @node Integer Type
@@ -1361,6 +1363,31 @@ in the loaded file.
 @code{autoload}, which stores the object in the function cell of a
 symbol.  @xref{Autoload}, for more details.
 
+@node Finalizer Type
+@subsection Finalizer Type
+
+  A @dfn{finalizer object} helps Lisp code clean up after objects that
+are no longer needed.  A finalizer holds a Lisp function object.
+When a finalizer object becomes unreachable after a garbage collection
+pass, Emacs calls the finalizer's associated function object.
+When deciding whether a finalizer is reachable, Emacs does not count
+references from finalizer objects themselves, allowing you to use
+finalizers without having to worry about accidentally capturing
+references to finalized objects themselves.
+
+Errors in finalizers are printed to @code{*Messages*}.  Emacs runs
+a given finalizer object's associated function exactly once, even
+if that function fails.
+
+@defun make-finalizer function
+Make a finalizer that will run @var{function}.  @var{function} will be
+called after garbage collection when the returned finalizer object
+becomes unreachable.  If the finalizer object is reachable only
+through references from finalizer objects, it does not count as
+reachable for the purpose of deciding whether to run @var{function}.
+@var{function} will be run once per finalizer object.
+@end defun
+
 @node Editing Types
 @section Editing Types
 @cindex editing types
@@ -1907,11 +1934,11 @@ types.  In most cases, it is more convenient to use type predicates than
 This function returns a symbol naming the primitive type of
 @var{object}.  The value is one of the symbols @code{bool-vector},
 @code{buffer}, @code{char-table}, @code{compiled-function},
-@code{cons}, @code{float}, @code{font-entity}, @code{font-object},
-@code{font-spec}, @code{frame}, @code{hash-table}, @code{integer},
-@code{marker}, @code{overlay}, @code{process}, @code{string},
-@code{subr}, @code{symbol}, @code{vector}, @code{window}, or
-@code{window-configuration}.
+@code{cons}, @code{finalizer}, @code{float}, @code{font-entity},
+@code{font-object}, @code{font-spec}, @code{frame}, @code{hash-table},
+@code{integer}, @code{marker}, @code{overlay}, @code{process},
+@code{string}, @code{subr}, @code{symbol}, @code{vector},
+@code{window}, or @code{window-configuration}.
 
 @example
 (type-of 1)

diff --git a/src/ChangeLog b/src/ChangeLog
index 2f04d0b040acbdfa70b08312c980982e96f62e28..930a33b277ae091e7f1130913342fbcd0dba88e7 100644 (file)
--- a/src/ChangeLog
+++ b/src/ChangeLog
@@ -1,3 +1,11 @@
+2015-03-03  Daniel Colascione  <dancol@dancol.org>
+
+       * print.c (print_object): Print whether a finalizer has
+       been called.
+
+       * data.c (Ftype_of): Make `type-of' work with finalizers.
+       (syms_of_data): Register Qfinalizer.
+
 2015-03-02  Daniel Colascione  <dancol@dancol.org>
 
        * print.c (print_object): Print finalizers.

diff --git a/src/data.c b/src/data.c
index 47706584f5e2b5ef830cb80805a4b8ca7944742c..c96841aebbf09354f1bc94fe64b1b27d1bbee56b 100644 (file)
--- a/src/data.c
+++ b/src/data.c
@@ -223,7 +223,9 @@ for example, (type-of 1) returns `integer'.  */)
        case Lisp_Misc_Overlay:
          return Qoverlay;
        case Lisp_Misc_Float:
-         return Qfloat;
+          return Qfloat;
+        case Lisp_Misc_Finalizer:
+          return Qfinalizer;
        }
       emacs_abort ();
 
@@ -3547,6 +3549,7 @@ syms_of_data (void)
   DEFSYM (Qcons, "cons");
   DEFSYM (Qmarker, "marker");
   DEFSYM (Qoverlay, "overlay");
+  DEFSYM (Qfinalizer, "finalizer");
   DEFSYM (Qfloat, "float");
   DEFSYM (Qwindow_configuration, "window-configuration");
   DEFSYM (Qprocess, "process");

diff --git a/src/print.c b/src/print.c
index d391fd5f7a37a9ecf387309e94138a8bd5f2ea4a..838d03666d41a5befd580cee083c270c0ba9447a 100644 (file)
--- a/src/print.c
+++ b/src/print.c
@@ -2046,7 +2046,10 @@ print_object (Lisp_Object obj, Lisp_Object printcharfun, bool escapeflag)
           break;
 
         case Lisp_Misc_Finalizer:
-          strout ("#<finalizer>", -1, -1, printcharfun);
+          strout ("#<finalizer", -1, -1, printcharfun);
+          if (NILP (XFINALIZER (obj)->function))
+            strout (" used", -1, -1, printcharfun);
+          strout (">", -1, -1, printcharfun);
           break;
 
          /* Remaining cases shouldn't happen in normal usage, but let's

diff --git a/test/ChangeLog b/test/ChangeLog
index 64ad85198afbf14fa3702fd9bf7268e47f367f79..3a311e97aa5a88681f238a089f05ce4a72a557b3 100644 (file)
--- a/test/ChangeLog
+++ b/test/ChangeLog
@@ -1,3 +1,8 @@
+2015-03-03  Daniel Colascione  <dancol@dancol.org>
+
+       * automated/finalizer-tests.el (finalizer-object-type): Test that
+       `type-of' works correctly for finalizers.
+
 2015-03-02  Daniel Colascione  <dancol@dancol.org>
 
        * automated/generator-tests.el: New tests

diff --git a/test/automated/finalizer-tests.el b/test/automated/finalizer-tests.el
index 5308f01085b1df18f647444ef132c468e6e59df7..4746dbea9b74d9905a99b87b3daae127786435de 100644 (file)
--- a/test/automated/finalizer-tests.el
+++ b/test/automated/finalizer-tests.el
@@ -76,3 +76,6 @@
       (should (equal
                (buffer-substring (point) (point-at-eol))
                "finalizer failed: (error \"ABCDEF\")")))))
+
+(ert-deftest finalizer-object-type ()
+  (should (equal (type-of (make-finalizer nil)) 'finalizer)))