From 9178d45a3a71525de17c20a6b6110eb84b8e6332 Mon Sep 17 00:00:00 2001 From: Ivan Maidanski Date: Tue, 6 Sep 2011 18:25:04 +0400 Subject: [PATCH] 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). --- include/gc.h | 44 +++++++++++++++++++++++++++++--------------- include/gc_mark.h | 2 +- 2 files changed, 30 insertions(+), 16 deletions(-) diff --git a/include/gc.h b/include/gc.h index 19d61f06..4fabc94b 100644 --- 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 3c35ced2..d5594e64 100644 --- 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); -- 2.40.0