Internal doc note on finalizer guarantee

doc/memory-management.rst

@@ -1122,21 +1122,23 @@ The following flags in the heap element header are used for controlling
 mark-and-sweep:
 
 * ``DUK_HEAPHDR_FLAG_REACHABLE``:
-  element is reachable through the reachability graph
+  element is reachable through the reachability graph.
 
 * ``DUK_HEAPHDR_FLAG_TEMPROOT``:
   element's reachability has been marked, but its children have not been
-  processed; this is required to limit the C recursion level
+  processed; this is required to limit the C recursion level.
 
 * ``DUK_HEAPHDR_FLAG_FINALIZABLE``:
   element is not reachable after the first marking pass (see algorithm),
   has a finalizer, and the finalizer has not been called in the previous
   mark-and-sweep round; object will be moved to the finalization work
-  list and will be considered (temporarily) a reachability root
+  list and will be considered (temporarily) a reachability root.
 
 * ``DUK_HEAPHDR_FLAG_FINALIZED``:
   element's finalizer has been executed, and if still unreachable, object
-  can be collected
+  can be collected.  The finalizer will not be called again until this
+  flag is cleared; this prevents accidental re-entry of the finalizer
+  until the object is explicitly rescued and this flag cleared.
 
 These are referred to as ``REACHABLE``, ``TEMPROOT``, ``FINALIZABLE``,
 and ``FINALIZED`` below for better readability.  All the flags are clear

doc/sandboxing.rst

@@ -216,7 +216,9 @@ Suggestions for sandboxing:
   reference directly.
 
 * Write finalizers very carefully.  Make minimal assumptions on which
-  thread they run, i.e. which global object they see.
+  thread they run, i.e. which global object they see.  It's also best
+  practice to tolerate re-entry (although Duktape 1.4.0 and above has
+  a guarantee of no re-entry unless object is rescued).
 
 * For sandboxed environments it may be sensible to make all finalizers
   native code so that they can access the necessary thread contexts