Commit 2cc23f17 authored by Daniel Colascione's avatar Daniel Colascione
Browse files

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.
parent 8af3e184
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
......
......@@ -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
......
......@@ -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)
......
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.
......
......@@ -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");
......
......@@ -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
......
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
......
......@@ -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)))
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment