From 2cc23f170f920cbfc9df4c28bce6ca9d82c4e6cd Mon Sep 17 00:00:00 2001 From: Daniel Colascione Date: Mon, 2 Mar 2015 19:08:06 -0800 Subject: [PATCH] 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. --- doc/lispref/ChangeLog | 6 +++++ doc/lispref/elisp.texi | 1 + doc/lispref/objects.texi | 37 ++++++++++++++++++++++++++----- src/ChangeLog | 8 +++++++ src/data.c | 5 ++++- src/print.c | 5 ++++- test/ChangeLog | 5 +++++ test/automated/finalizer-tests.el | 3 +++ 8 files changed, 63 insertions(+), 7 deletions(-) diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog index e7d79d55c7e..c27805b3d6e 100644 --- a/doc/lispref/ChangeLog +++ b/doc/lispref/ChangeLog @@ -1,3 +1,9 @@ +2015-03-03 Daniel Colascione + + * 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 * control.texi (Generators): New section diff --git a/doc/lispref/elisp.texi b/doc/lispref/elisp.texi index 3802e49ec3d..fc552be161b 100644 --- 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 ba28b63f0de..b28b3b00898 100644 --- 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 2f04d0b040a..930a33b277a 100644 --- a/src/ChangeLog +++ b/src/ChangeLog @@ -1,3 +1,11 @@ +2015-03-03 Daniel Colascione + + * 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 * print.c (print_object): Print finalizers. diff --git a/src/data.c b/src/data.c index 47706584f5e..c96841aebbf 100644 --- 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 d391fd5f7a3..838d03666d4 100644 --- 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 ("#", -1, -1, printcharfun); + strout ("#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 64ad85198af..3a311e97aa5 100644 --- a/test/ChangeLog +++ b/test/ChangeLog @@ -1,3 +1,8 @@ +2015-03-03 Daniel Colascione + + * automated/finalizer-tests.el (finalizer-object-type): Test that + `type-of' works correctly for finalizers. + 2015-03-02 Daniel Colascione * automated/generator-tests.el: New tests diff --git a/test/automated/finalizer-tests.el b/test/automated/finalizer-tests.el index 5308f01085b..4746dbea9b7 100644 --- 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))) -- 2.39.2