Refine do_blocking() documentation in gc.h

* include/gc.h (GC_do_blocking): Refine comment (copy part of comment
from misc.c, add information that GC should be initialized and the
current thread should be registered).
* misc.c (GC_do_blocking): Remove title comment (as it duplicates the
one in gc.h).

diff --git a/include/gc.h b/include/gc.h
index 1866c3a6c6fc389bec571cc531a4f9c388ec670c..40ce86573c299470a16200b352ec365ca10bcee1 100644 (file)
--- a/include/gc.h
+++ b/include/gc.h
@@ -1546,8 +1546,13 @@ GC_API void * GC_CALL GC_call_with_stack_base(GC_stack_base_func /* fn */,
 /* the current thread (this means that the thread is not suspended and  */
 /* the thread's stack frames "belonging" to the functions in the        */
 /* "inactive" state are not scanned during garbage collections).  It is */
-/* allowed for fn to call GC_call_with_gc_active() (even recursively),  */
-/* thus temporarily toggling the collector's state back to "active".    */
+/* assumed that the collector is already initialized and the current    */
+/* thread is registered.  It is allowed for fn to call                  */
+/* GC_call_with_gc_active() (even recursively), thus temporarily        */
+/* toggling the collector's state back to "active".  The latter         */
+/* technique might be used to make stack scanning more precise (i.e.    */
+/* scan only stack frames of functions that allocate garbage collected  */
+/* memory and/or manipulate pointers to the garbage collected heap).    */
 GC_API void * GC_CALL GC_do_blocking(GC_fn_type /* fn */,
                                 void * /* client_data */) GC_ATTR_NONNULL(1);
 

diff --git a/misc.c b/misc.c
index 30ce3c2399bfe348deed58d9da1b6d8bb6eb0716..21baef8f0b16cdece05d2752fe6d234b4a33d995 100644 (file)
--- a/misc.c
+++ b/misc.c
@@ -2202,14 +2202,6 @@ STATIC void GC_do_blocking_inner(ptr_t data, void * context GC_ATTR_UNUSED)
 
 #endif /* !THREADS */
 
-/* Wrapper for functions that are likely to block (or, at least, do not */
-/* allocate garbage collected memory and/or manipulate pointers to the  */
-/* garbage collected heap) for an appreciable length of time.           */
-/* In the single threaded case, GC_do_blocking() (together              */
-/* with GC_call_with_gc_active()) might be used to make stack scanning  */
-/* more precise (i.e. scan only stack frames of functions that allocate */
-/* garbage collected memory and/or manipulate pointers to the garbage   */
-/* collected heap).                                                     */
 GC_API void * GC_CALL GC_do_blocking(GC_fn_type fn, void * client_data)
 {
     struct blocking_data my_data;