From: Ivan Maidanski <ivmai@mail.ru>
Date: Thu, 25 Apr 2019 07:28:40 +0000 (+0300)
Subject: Refine do_blocking() documentation in gc.h
X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=51a44b9cdb0f28e60509a6d930e7787163d110c4;p=gc

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 1866c3a6..40ce8657 100644
--- 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 30ce3c23..21baef8f 100644
--- 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;