Refine documentation in gc_disclaim.h

* include/gc_disclaim.h (GC_disclaim_proc, GC_register_disclaim_proc,
GC_finalized_malloc): Refine comment.

diff --git a/include/gc_disclaim.h b/include/gc_disclaim.h
index 7f5ffb1..6764791 100644 (file)
--- a/include/gc_disclaim.h
+++ b/include/gc_disclaim.h
@@ -29,12 +29,13 @@
 /* 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"  */
+/* reclaim the object on this GC cycle ("proc" should not try to        */
+/* resurrect the object otherwise).  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.                                                          */
@@ -52,6 +53,9 @@ 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" 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.  */