summaryrefslogtreecommitdiff
path: root/include
diff options
context:
space:
mode:
authorIvan Maidanski <ivmai@mail.ru>2011-09-06 16:25:04 +0200
committerIvan Maidanski <ivmai@mail.ru>2011-09-12 12:25:08 +0200
commited9b8b97e2d72aa28b85999c7e57172e130fbc22 (patch)
tree76e2faab05701c558dab69101115d09d8bc702c7 /include
parent005792c614d9932735290e9314a3db0d5e757fda (diff)
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).
Diffstat (limited to 'include')
-rw-r--r--include/gc.h44
-rw-r--r--include/gc_mark.h2
2 files changed, 30 insertions, 16 deletions
diff --git a/include/gc.h b/include/gc.h
index ae7d046..e0c4b43 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 3c35ced..d5594e6 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);