Implementing finalization hooks.

* gc.c (struct fin_reg): New struct type.
(final_list, final_tail, mark_makefresh): New static variables.
(mark_obj): Under generational GC, if make_makefresh is in
effect, set the generation to -1 on all marked objects.
(sweep_one): In an EXTRA_DEBUGGING  build, call breakpt
if the object being swept is the one in break_obj.
Under generational GC, place reachable objects that are
in generation -1 the freshobj nursery and assign them to generation 0,
rather than sticking them into the mature generation 1.
(sweep): Under generational gc, reset the freshobj_idx variable
here, so that sweep_one has an empty nursery in which
to place the generation -1 objects.
(prepare_finals, call_finals): New static functions.
(gc): Call prepare_finals before sweep, and call call_finals
just before re-enabling GC and returning. Do not reset freshobj_idx to
zero; this was done in sweep, which may have added entries into it.
(gc_finalize): New function.
(gc_late_init): Register gc_finalize as intrinsic function finalize.

* txr.1: Documented finalize.

* HACKING: Documented finalization, described the additional
meaning of the -1 generation, and added a section on debugging with
break_obj and breakpt.

1 files changed, 56 insertions, 0 deletions

diff --git a/txr.1 b/txr.1
index c2742885..5b19b877 100644
--- a/txr.1
+++ b/txr.1
@@ -25501,6 +25501,62 @@ of memory. It is for this reason that the garbage collector uses the GC delta.
 There is a default GC delta of 64 megabytes. This may be overridden in
 special builds of \*(TX for small systems.
 
+.coNP Function @ finalize
+.synb
+.mets (finalize < object << function )
+.syne
+
+.desc
+The
+.code finalize
+function registers
+.meta function
+to be invoked in the situation when
+.meta object
+is identified by the garbage collector as unreachable.
+This function is called a finalizer.
+
+If and when this situation occurs, the finalizer
+.meta function
+will be called with
+.meta object
+as its only argument.
+
+Finalizers are called in the same order in which they are registered:
+newer registrations are called after older registrations.
+
+If
+.meta object
+is registered multiple times by multiple calls to
+.codn finalize ,
+then if those finalizers are called, they are all called, in the order
+of registration.
+
+After a finalization call takes place, its registration is removed;
+.meta object
+and
+.meta function
+are no longer associated.  However, neither
+.meta object
+nor
+.meta function
+are reclaimed immediately; they are treated as if they were reachable objects
+until at least the next garbage collection pass.
+It is therefore safe for
+.meta function
+to store somewhere a persistent reference to
+.meta object
+or to itself, thereby reinstanting these objects as reachable.
+
+.meta function
+is itself permitted to call
+.code finalize
+to register the original
+.code object
+or any other object for finalization. Such registrations made during
+finalization execution are not eligible for the current phase of finalization
+processing; they will be processed in a later garbage collection pass.
+
 .SS* Modularization
 .coNP Special variable @ *self-path*
 .desc