Refine API GC setters and getter comments regarding locking.

* include/gc_mark.h (GC_set_start_callback): Refine comment (the
function acquires the GC lock).
* include/gc.h (GC_set_all_interior_pointers, GC_set_stop_func,
GC_get_stack_base): Likewise.
* include/gc.h (GC_get_version, GC_get_gc_no, GC_get_parallel,
GC_set_find_leak, GC_get_all_interior_pointers,
GC_get_dont_precollect, GC_get_pages_executable, GC_set_max_heap_size,
GC_set_force_unmap_on_gcollect): Refine comment (the function is
lock-free).

diff --git a/include/gc.h b/include/gc.h
index ae7d046fdf6a0f009b439c0bddb63113e8d13d2f..e0c4b43fd09a07556f9a39dfc5d49186617c57c3 100644 (file)
--- a/include/gc.h
+++ b/include/gc.h
@@ -65,8 +65,8 @@
   typedef long GC_signed_word;
 #endif
 
-/* Get the GC library version. The returned value is in the form:       */
-/* ((version_major<<16) | (version_minor<<8) | alpha_version).          */
+/* Get the GC library version. The returned value is a constant in the  */
+/* form: ((version_major<<16) | (version_minor<<8) | alpha_version).    */
 GC_API unsigned GC_CALL GC_get_version(void);
 
 /* Public read-only variables */
@@ -75,7 +75,7 @@ GC_API unsigned GC_CALL GC_get_version(void);
 GC_API GC_word GC_gc_no;/* Counter incremented per collection.          */
                         /* Includes empty GCs at startup.               */
 GC_API GC_word GC_CALL GC_get_gc_no(void);
-                        /* GC_get_gc_no() uses no synchronization, so   */
+                        /* GC_get_gc_no() is unsynchronized, so         */
                         /* it requires GC_call_with_alloc_lock() to     */
                         /* avoid data races on multiprocessors.         */
 
@@ -89,7 +89,9 @@ GC_API GC_word GC_CALL GC_get_gc_no(void);
                         /*  GC_NPROC is not set and this is an MP.      */
                         /* If GC_parallel is set, incremental           */
                         /* collection is only partially functional,     */
-                        /* and may not be desirable.                    */
+                        /* and may not be desirable. This getter does   */
+                        /* not use or need synchronization (i.e.        */
+                        /* acquiring the GC lock).                      */
   GC_API int GC_CALL GC_get_parallel(void);
 #endif
 
@@ -117,21 +119,24 @@ GC_API int GC_find_leak;
                         /* deallocated with GC_free.  Initial value     */
                         /* is determined by FIND_LEAK macro.            */
                         /* The value should not typically be modified   */
-                        /* after GC initialization.                     */
+                        /* after GC initialization (and, thus, it does  */
+                        /* not use or need synchronization).            */
 GC_API void GC_CALL GC_set_find_leak(int);
 GC_API int GC_CALL GC_get_find_leak(void);
 
 GC_API int GC_all_interior_pointers;
                         /* Arrange for pointers to object interiors to  */
-                        /* be recognized as valid.  May not be changed  */
-                        /* after GC initialization.  The initial value  */
+                        /* be recognized as valid.  Typically should    */
+                        /* not be changed after GC initialization (in   */
+                        /* case of calling it after the GC is           */
+                        /* initialized, the setter acquires the GC lock */
+                        /* (to avoid data races).  The initial value    */
                         /* depends on whether the GC is built with      */
                         /* ALL_INTERIOR_POINTERS macro defined or not.  */
                         /* Unless DONT_ADD_BYTE_AT_END is defined, this */
                         /* also affects whether sizes are increased by  */
                         /* at least a byte to allow "off the end"       */
-                        /* pointer recognition.                         */
-                        /* MUST BE 0 or 1.                              */
+                        /* pointer recognition.  Must be only 0 or 1.   */
 GC_API void GC_CALL GC_set_all_interior_pointers(int);
 GC_API int GC_CALL GC_get_all_interior_pointers(void);
 
@@ -289,7 +294,10 @@ GC_API int GC_dont_precollect;  /* Don't collect as part of GC          */
                                 /* manually initialize the root set     */
                                 /* before the first collection.         */
                                 /* Interferes with blacklisting.        */
-                                /* Wizards only.                        */
+                                /* Wizards only.  The setter and getter */
+                                /* are unsynchronized (and no external  */
+                                /* locking is needed since the value is */
+                                /* accessed at GC initialization only). */
 GC_API void GC_CALL GC_set_dont_precollect(int);
 GC_API int GC_CALL GC_get_dont_precollect(void);
 
@@ -326,8 +334,9 @@ GC_API unsigned long GC_CALL GC_get_time_limit(void);
 GC_API void GC_CALL GC_set_pages_executable(int);
 
 /* Returns non-zero value if the GC is set to the allocate-executable   */
-/* mode.  The mode could be changed by GC_set_pages_executable() unless */
-/* the latter has no effect on the platform.                            */
+/* mode.  The mode could be changed by GC_set_pages_executable (before  */
+/* GC_INIT) unless the former has no effect on the platform.  Does not  */
+/* use or need synchronization (i.e. acquiring the allocator lock).     */
 GC_API int GC_CALL GC_get_pages_executable(void);
 
 /* Initialize the collector.  Portable clients should call GC_INIT()    */
@@ -424,7 +433,9 @@ GC_API int GC_CALL GC_expand_hp(size_t /* number_of_bytes */);
 
 /* Limit the heap size to n bytes.  Useful when you're debugging,       */
 /* especially on systems that don't handle running out of memory well.  */
-/* n == 0 ==> unbounded.  This is the default.                          */
+/* n == 0 ==> unbounded.  This is the default.  This setter function is */
+/* unsynchronized (so it might require GC_call_with_alloc_lock to avoid */
+/* data races).                                                         */
 GC_API void GC_CALL GC_set_max_heap_size(GC_word /* n */);
 
 /* Inform the collector that a certain section of statically allocated  */
@@ -498,6 +509,7 @@ GC_API int GC_CALL GC_try_to_collect(GC_stop_func /* stop_func */);
 /* Set and get the default stop_func.  The default stop_func is used by */
 /* GC_gcollect() and by implicitly trigged collections (except for the  */
 /* case when handling out of memory).  Must not be 0.                   */
+/* Both the setter and getter acquire the GC lock to avoid data races.  */
 GC_API void GC_CALL GC_set_stop_func(GC_stop_func /* stop_func */);
 GC_API GC_stop_func GC_CALL GC_get_stop_func(void);
 
@@ -1100,7 +1112,8 @@ GC_API void * GC_CALL GC_call_with_gc_active(GC_fn_type /* fn */,
 /* like the JNI AttachCurrentThread in an environment in which new      */
 /* threads are not automatically registered with the collector.         */
 /* It is also unfortunately hard to implement well on many platforms.   */
-/* Returns GC_SUCCESS or GC_UNIMPLEMENTED.                              */
+/* Returns GC_SUCCESS or GC_UNIMPLEMENTED.  This function acquires the  */
+/* GC lock on some platforms.                                           */
 GC_API int GC_CALL GC_get_stack_base(struct GC_stack_base *);
 
 /* The following routines are primarily intended for use with a         */
@@ -1316,7 +1329,8 @@ GC_API void GC_CALL GC_register_has_static_roots_callback(
 /* Public setter and getter for switching "unmap as much as possible"   */
 /* mode on(1) and off(0).  Has no effect unless unmapping is turned on. */
 /* Has no effect on implicitly-initiated garbage collections.  Initial  */
-/* value is controlled by GC_FORCE_UNMAP_ON_GCOLLECT.                   */
+/* value is controlled by GC_FORCE_UNMAP_ON_GCOLLECT.  The setter and   */
+/* getter are unsynchronized.                                           */
 GC_API void GC_CALL GC_set_force_unmap_on_gcollect(int);
 GC_API int GC_CALL GC_get_force_unmap_on_gcollect(void);
 

diff --git a/include/gc_mark.h b/include/gc_mark.h
index 3c35ced24fc35ac71713f2a4419830b821d3ae18..d5594e645a4f0f0015bb8072f61cdfc6d805f6f9 100644 (file)
--- a/include/gc_mark.h
+++ b/include/gc_mark.h
@@ -218,7 +218,7 @@ GC_API size_t GC_CALL GC_get_free_bytes_inner(void);
 /* the callback should not, directly or indirectly, make any GC_ or     */
 /* potentially blocking calls.  In particular, it is not safe to        */
 /* allocate memory using the garbage collector from within the callback */
-/* function.                                                            */
+/* function.  Both the setter and getter acquire the GC lock.           */
 typedef void (GC_CALLBACK * GC_start_callback_proc)(void);
 GC_API void GC_CALL GC_set_start_callback(GC_start_callback_proc);
 GC_API GC_start_callback_proc GC_CALL GC_get_start_callback(void);