Refine documentation in gc_disclaim.h

(a cherry-pick of commits 8ce6ef666, 4158701ae from 'master')

* include/gc_disclaim.h (GC_disclaim_proc, GC_register_disclaim_proc,
GC_finalized_malloc): Refine comment.
* include/gc_disclaim.h (GC_register_disclaim_proc,
GC_finalized_malloc): Refine comment about the protection of the
finalizer closure object from collection.

diff --git a/include/gc_disclaim.h b/include/gc_disclaim.h
index 7f5ffb1409eb54fc480a643e3d03521e5603b9d9..8123838ed48f0aab6230c2b025b3397b00ce8ab1 100644 (file)
--- a/include/gc_disclaim.h
+++ b/include/gc_disclaim.h
@@ -29,15 +29,16 @@
 /* finalized allocations.  The function is thread-safe.                 */
 GC_API void GC_CALL GC_init_finalized_malloc(void);
 
-/* Type of a disclaim call-back.                                        */
+/* Type of a disclaim call-back.  Called with the allocation lock held. */
 typedef int (GC_CALLBACK * GC_disclaim_proc)(void * /*obj*/);
 
 /* Register "proc" to be called on each object of "kind" ready to be    */
 /* reclaimed.  If "proc" returns non-zero, the collector will not       */
-/* reclaim the object on this GC cycle.  Objects reachable from "proc"  */
-/* will be protected from collection if "mark_from_all" is non-zero,    */
-/* but at the expense that long chains of objects will take many cycles */
-/* to reclaim.                                                          */
+/* reclaim the object on this GC cycle ("proc" should not try to        */
+/* resurrect the object otherwise).  Objects reachable from "proc"      */
+/* (including the referred closure object) will be protected from       */
+/* collection if "mark_from_all" is non-zero, but at the expense that   */
+/* long chains of objects will take many cycles to reclaim.             */
 GC_API void GC_CALL GC_register_disclaim_proc(int /*kind*/,
                                 GC_disclaim_proc /*proc*/,
                                 int /*mark_from_all*/) GC_ATTR_NONNULL(2);
@@ -52,6 +53,10 @@ struct GC_finalizer_closure {
 /* dedicated object kind with a disclaim procedure, and is more         */
 /* efficient than GC_register_finalizer and friends.                    */
 /* GC_init_finalized_malloc must be called before using this.           */
+/* The collector will reclaim the object during this GC cycle (thus,    */
+/* "proc" should not try to resurrect the object).  The other objects   */
+/* reachable from "proc" (including the closure object in case it is    */
+/* a heap-allocated one) will be protected from collection.             */
 /* Note that GC_size (applied to such allocated object) returns a value */
 /* slightly bigger than the specified allocation size, and that GC_base */
 /* result points to a word prior to the start of the allocated object.  */