[m-dev.] diff: improve boehm_gc documentation

[Fergus Henderson]

I've sent this patch off to Hans Boehm for inclusion in his next
release.  But I'll also go ahead and commit it in our repository.

Estimated hours taken: 0.75

boehm_gc/README:
boehm_gc/README.QUICK:
boehm_gc/gc.h:
	Improve the quality and visibility of the documentation
	about a couple of nasty caveats, namely that malloc()'d
	storage and thread-local storage is not traced by
	the collector.

Workspace: /home/pgrad/fjh/ws/hg2
Index: boehm_gc/gc.h
===================================================================
RCS file: /home/mercury1/repository/mercury/boehm_gc/gc.h,v
retrieving revision 1.28
diff -u -d -r1.28 gc.h
--- boehm_gc/gc.h	2000/09/18 11:08:50	1.28
+++ boehm_gc/gc.h	2000/10/04 04:33:18
@@ -708,7 +708,12 @@
 /* Note also that the collector cannot see thread specific data.	*/
 /* Thread specific data should generally consist of pointers to		*/
 /* uncollectable objects, which are deallocated using the destructor	*/
-/* facility in thr_keycreate.						*/
+/* facility in thr_keycreate.  But unless your uncollectable objects	*/
+/* are also atomic, you must take care to ensure that the thread 	*/
+/* specific data is also stored on the thread stack, so that the	*/
+/* collector doesn't try to reclaim collectable objects pointed to	*/
+/* only by uncollectable objects which are reachable only from		*/
+/* thread-local storage.						*/
 # include <thread.h>
 # include <signal.h>
   int GC_thr_create(void *stack_base, size_t stack_size,
Index: boehm_gc/README
===================================================================
RCS file: /home/mercury1/repository/mercury/boehm_gc/README,v
retrieving revision 1.10
diff -u -d -r1.10 README
--- boehm_gc/README	2000/09/18 11:08:48	1.10
+++ boehm_gc/README	2000/10/04 04:22:49
@@ -151,7 +151,7 @@
 you get collector warnings from allocations of very large objects.
 See README.debugging for details.
 
-  Note that pointers inside memory allocated by the standard "malloc" are not
+  WARNING: pointers inside memory allocated by the standard "malloc" are not
 seen by the garbage collector.  Thus objects pointed to only from such a
 region may be prematurely deallocated.  It is thus suggested that the
 standard "malloc" be used only for memory regions, such as I/O buffers, that
@@ -161,13 +161,17 @@
 similar to standard malloc, but allocates objects that are traced by the
 collector.)
 
-  The collector does not always know how to find pointers in data
+  WARNING: the collector does not always know how to find pointers in data
 areas that are associated with dynamic libraries.  This is easy to
 remedy IF you know how to find those data areas on your operating
 system (see GC_add_roots).  Code for doing this under SunOS, IRIX 5.X and 6.X,
 HP/UX, Alpha OSF/1, Linux, and win32 is included and used by default.  (See
 README.win32 for win32 details.)  On other systems pointers from dynamic
 library data areas may not be considered by the collector.
+If you're writing a program that depends on the collector scanning
+dynamic library data areas, it may be a good idea to include at least
+one call to GC_is_visible() to ensure that those areas are visible
+to the collector.
 
   Note that the garbage collector does not need to be informed of shared
 read-only data.  However if the shared library mechanism can introduce
@@ -185,7 +189,13 @@
 
   The allocator/collector can also be configured for thread-safe operation.
 (Full signal safety can also be achieved, but only at the cost of two system
-calls per malloc, which is usually unacceptable.)
+calls per malloc, which is usually unacceptable.) 
+WARNING: the collector does not guarantee to scan thread-local storage
+(e.g. of the kind accessed with pthread_getspecific()).  The collector
+does scan thread stacks, though, so generally the best solution is to
+ensure that any pointers stored in thread-local storage are also
+stored on the thread's stack for the duration of their lifetime.
+
 
 INSTALLATION AND PORTABILITY
 
Index: boehm_gc/README.QUICK
===================================================================
RCS file: /home/mercury1/repository/mercury/boehm_gc/README.QUICK,v
retrieving revision 1.2
diff -u -d -r1.2 README.QUICK
--- boehm_gc/README.QUICK	2000/09/18 11:08:48	1.2
+++ boehm_gc/README.QUICK	2000/10/04 04:40:07
@@ -41,3 +41,9 @@
 
 Define GC_DEBUG before including gc.h for additional checking.
 
+BEWARE:
+Don't store the last pointer to objects allocated with GC_MALLOC()
+etc. in malloc()'d memory or in thread-local storage, since by default
+the collector doesn't scan those areas, and so will prematurely
+collect objects that are only reachable via those areas.
+

-- 
Fergus Henderson <fjh at cs.mu.oz.au>  |  "I have always known that the pursuit
WWW: <http://www.cs.mu.oz.au/~fjh>  |  of excellence is a lethal habit"
PGP: finger fjh at 128.250.37.3        |     -- the last words of T. S. Garp.
--------------------------------------------------------------------------
mercury-developers mailing list
Post messages to:       mercury-developers at cs.mu.oz.au
Administrative Queries: owner-mercury-developers at cs.mu.oz.au
Subscriptions:          mercury-developers-request at cs.mu.oz.au
--------------------------------------------------------------------------