[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Emacs-diffs] master 2cc23f1: Finalizer documentation, minor improvement
From: |
Daniel Colascione |
Subject: |
[Emacs-diffs] master 2cc23f1: Finalizer documentation, minor improvements |
Date: |
Tue, 03 Mar 2015 03:08:27 +0000 |
branch: master
commit 2cc23f170f920cbfc9df4c28bce6ca9d82c4e6cd
Author: Daniel Colascione <address@hidden>
Commit: Daniel Colascione <address@hidden>
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 e7d79d5..c27805b 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,3 +1,9 @@
+2015-03-03 Daniel Colascione <address@hidden>
+
+ * 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 <address@hidden>
* control.texi (Generators): New section
diff --git a/doc/lispref/elisp.texi b/doc/lispref/elisp.texi
index 3802e49..fc552be 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 ba28b63..b28b3b0 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.
address@hidden Finalizer Type
address@hidden 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.
+
address@hidden 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}.
address@hidden will be run once per finalizer object.
address@hidden 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},
address@hidden, @code{float}, @code{font-entity}, @code{font-object},
address@hidden, @code{frame}, @code{hash-table}, @code{integer},
address@hidden, @code{overlay}, @code{process}, @code{string},
address@hidden, @code{symbol}, @code{vector}, @code{window}, or
address@hidden
address@hidden, @code{finalizer}, @code{float}, @code{font-entity},
address@hidden, @code{font-spec}, @code{frame}, @code{hash-table},
address@hidden, @code{marker}, @code{overlay}, @code{process},
address@hidden, @code{subr}, @code{symbol}, @code{vector},
address@hidden, or @code{window-configuration}.
@example
(type-of 1)
diff --git a/src/ChangeLog b/src/ChangeLog
index 2f04d0b..930a33b 100644
--- a/src/ChangeLog
+++ b/src/ChangeLog
@@ -1,3 +1,11 @@
+2015-03-03 Daniel Colascione <address@hidden>
+
+ * 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 <address@hidden>
* print.c (print_object): Print finalizers.
diff --git a/src/data.c b/src/data.c
index 4770658..c96841a 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 d391fd5..838d036 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 ("#<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 64ad851..3a311e9 100644
--- a/test/ChangeLog
+++ b/test/ChangeLog
@@ -1,3 +1,8 @@
+2015-03-03 Daniel Colascione <address@hidden>
+
+ * automated/finalizer-tests.el (finalizer-object-type): Test that
+ `type-of' works correctly for finalizers.
+
2015-03-02 Daniel Colascione <address@hidden>
* automated/generator-tests.el: New tests
diff --git a/test/automated/finalizer-tests.el
b/test/automated/finalizer-tests.el
index 5308f01..4746dbe 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)))
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- [Emacs-diffs] master 2cc23f1: Finalizer documentation, minor improvements,
Daniel Colascione <=