Debugging Garbage Collector Related Problems

From: hboehm Date: Wed, 27 Aug 2008 22:14:51 +0000 (+0000) Subject: 2008-08-27 Hans Boehm X-Git-Tag: gc7_2alpha2~65 X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=2ceea97cdf78c8a1c575a5002457d7cd648e740e;p=gc 2008-08-27 Hans Boehm * doc/simple_example.html: update --enable-full-debug reference, Make HTML formatting standards compliant. * doc/debugging.html, doc/leak.html: Fix HTML formatting bugs. * doc/gcinterface.html: specify encoding. --- diff --git a/ChangeLog b/ChangeLog index 2fe46e9f..b3b43cc4 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,9 @@ +2008-08-27 Hans Boehm + * doc/simple_example.html: update --enable-full-debug reference, + Make HTML formatting standards compliant. + * doc/debugging.html, doc/leak.html: Fix HTML formatting bugs. + * doc/gcinterface.html: specify encoding. + 2008-08-27 Hans Boehm (with help from Marco Maggi) * doc/simple_example.html: Update thread-local allocation description. diff --git a/doc/debugging.html b/doc/debugging.html index 7c65f2bb..4db5f2a5 100644 --- a/doc/debugging.html +++ b/doc/debugging.html @@ -1,5 +1,7 @@ - + + + Debugging Garbage Collector Related Problems @@ -81,8 +83,8 @@ void * big_realloc(void *p, size_t new_size) size_t old_size = GC_size(p); void * result; - if (new_size <= 10000) return(GC_realloc(p, new_size)); - if (new_size <= old_size) return(p); + if (new_size <= 10000) return(GC_realloc(p, new_size)); + if (new_size <= old_size) return(p); result = GC_malloc_ignore_off_page(new_size); if (result == 0) return(0); memcpy(result,p,old_size); @@ -186,7 +188,8 @@ primitives is gc_typed.h, or separate out the pointerfree component. to allocate large objects. (See gc.h and above for details. Large means > 100K in most environments.)

If your heap size is larger than 100MB or so, build the collector with --DLARGE_CONFIG. This allows the collector to keep more precise black-list +-DLARGE_CONFIG. +This allows the collector to keep more precise black-list information.

If you are using heaps close to, or larger than, a gigabyte on a 32-bit machine, you may want to consider moving to a platform with 64-bit pointers. diff --git a/doc/gcinterface.html b/doc/gcinterface.html index bd7b4a94..5c90665e 100644 --- a/doc/gcinterface.html +++ b/doc/gcinterface.html @@ -1,5 +1,7 @@ - + + + Garbage Collector Interface diff --git a/doc/leak.html b/doc/leak.html index fc9c3eb7..b3c21a09 100644 --- a/doc/leak.html +++ b/doc/leak.html @@ -1,5 +1,7 @@ - + + + Using the Garbage Collector as Leak Detector @@ -27,7 +29,8 @@ leak detection support. Version 5.3 adds the following features:

Leak detection mode can be initiated at run-time by -setting GC_find_leak instead of building the collector with FIND_LEAK +setting GC_find_leak instead of building the +collector with FIND_LEAK defined. This variable should be set to a nonzero value at program startup.

Leaked objects should be reported and then correctly garbage collected. @@ -38,7 +41,7 @@ with any reasonable version of the collector.

To use the collector as a leak detector, follow the following steps:

Build the collector with -DFIND_LEAK. Otherwise use default +
Build the collector with -DFIND_LEAK. Otherwise use default build options.

Change the program so that all allocation and deallocation goes through the garbage collector. @@ -92,9 +95,9 @@ The following header file leak_detector.h is included in the #define CHECK_LEAKS() GC_gcollect()

-Assume the collector has been built with -DFIND_LEAK. (For very -new versions of the collector, we could instead add the statement -GC_find_leak = 1 as the first statement in main. +Assume the collector has been built with -DFIND_LEAK. (For +newer versions of the collector, we could instead add the statement +GC_find_leak = 1 as the first statement in main().

The program to be tested for leaks can then look like:

@@ -105,13 +108,13 @@ main() {
     int i;
     /* GC_find_leak = 1; for new collector versions not 	*/
     /* compiled with -DFIND_LEAK.				*/
-    for (i = 0; i < 10; ++i) {
+    for (i = 0; i < 10; ++i) {
 	p[i] = malloc(sizeof(int)+i);
     }
-    for (i = 1; i < 10; ++i) {
+    for (i = 1; i < 10; ++i) {
 	free(p[i]);
     }
-    for (i = 0; i < 9; ++i) {
+    for (i = 0; i < 9; ++i) {
 	p[i] = malloc(sizeof(int)+i);
     }
     CHECK_LEAKS();
@@ -165,11 +168,13 @@ detection mode on a program a.out under Linux/X86 as follows:
 a very recent (7.0alpha7+) collector version on Linux.
 On most platforms this does not
 work at all for multithreaded programs.
- If possible, ensure that the addr2line program is installed in
-/usr/bin.  (It comes with RedHat Linux.)
-
 If possible, compile a.out with full debug information.
+
 If possible, ensure that the addr2line program is installed in
+/usr/bin.  (It comes with most Linux distributions.)
+
 If possible, compile your program, which we'll call a.out,
+with full debug information.
 This will improve the quality of the leak reports.  With this approach, it is
-no longer necessary to call GC_ routines explicitly, though that can also
+no longer necessary to call GC_ routines explicitly,
+though that can also
 improve the quality of the leak reports.
 
 Build the collector and install it in directory foo as follows:
 
@@ -178,16 +183,19 @@ improve the quality of the leak reports.
  make
 
 make install
 
-With a very recent collector on Linux, it may be safe to omit the --disable-threads.
+With a very recent collector on Linux, it may sometimes be safe to omit
+the --disable-threads.  But the combination of thread support
+and malloc replacement is not yet rock solid.
 
 Set environment variables as follows:
 
- LD_PRELOAD=foo/lib/libgc.so
-
 GC_FIND_LEAK
-
 You may also want to set GC_PRINT_STATS (to confirm that the collector
-is running) and/or GC_LOOP_ON_ABORT (to facilitate debugging from another
+
 LD_PRELOAD=foo/lib/libgc.so
+
 GC_FIND_LEAK
+
 You may also want to set GC_PRINT_STATS
+(to confirm that the collector is running) and/or
+GC_LOOP_ON_ABORT (to facilitate debugging from another
 window if something goes wrong).
- Simply run a.out as you normally would.  Note that if you run anything
+
+
 Simply run a.out as you normally would.  Note that if you run anything
 else (e.g. your editor) with those environment variables set,
 it will also be leak tested.  This may or may not be useful and/or
 embarrassing.  It can generate
diff --git a/doc/simple_example.html b/doc/simple_example.html
index 91ffb92a..6ca3eee6 100644
--- a/doc/simple_example.html
+++ b/doc/simple_example.html
@@ -1,5 +1,7 @@
-
+
+
 
+
 Using the Garbage Collector: A simple example
 
 
@@ -13,8 +15,8 @@ It can be skipped, especially on first reading.
 If you haven't already so, unpack the collector and enter
 the newly created directory with
 -tar xvfz gc.tar.gz
-cd gc
+tar xvfz gc<version>.tar.gz
+cd gc<version>
 
 
 You can configure, build, and install the collector in a private
@@ -27,8 +29,8 @@ make install

Here the "make check" command is optional, but highly recommended. It runs a basic correctness test which usually takes well under a minute. +

Other platforms

On non-Unix, non-Linux platforms, the collector is usually built by copying the appropriate makefile (see the platform-specific README in doc/README.xxx in the distribution) to the file "Makefile" (overwriting the copy of @@ -36,24 +38,34 @@ Makefile.direct that was originally there), and then typing "make" (or "nmake" or ...). This builds the library in the source tree. You may want to move it and the files in the include directory to a more convenient place. +

+ If you use a makefile that does not require running a configure script, you should first look at the makefile, and adjust any options that are documented there. +

+ If your platform provides a "make" utility, that is generally preferred to platform- and compiler- dependent "project" files. (At least that is the strong preference of the would-be maintainer of those project files.) -

Threads

+ +

Threads

+ If you need thread support, configure the collector with -

+
+ --enable-threads=posix --enable-thread-local-alloc --enable-parallel-mark
 
+
 instead of
 --disable-threads
 If your target is a real old-fashioned uniprocessor (no "hyperthreading",
 etc.) you will want to omit --enable-parallel-mark.
-C++
+
+C++
+
 You will need to include the C++ support, which unfortunately tends to
 be among the least portable parts of the collector, since it seems
 to rely on some corner cases of the language.  On Linux, it
@@ -93,7 +105,7 @@ int main()
   int i;
 
   GC_INIT();	/* Optional on Linux/X86; see below.  */
-  for (i = 0; i < 10000000; ++i)
+  for (i = 0; i < 10000000; ++i)
    {
      int **p = (int **) GC_MALLOC(sizeof(int *));
      int *q = (int *) GC_MALLOC_ATOMIC(sizeof(int));
@@ -105,58 +117,75 @@ int main()
   return 0;
 }

Interaction with the system malloc

It is usually best not to mix garbage-collected allocation with the system malloc-free. If you do, you need to be careful not to store pointers to the garbage-collected heap in memory allocated with the system malloc. -

Other Platforms

+ + +

Other Platforms

+ On some other platforms it is necessary to call GC_INIT() from the main program, which is presumed to be part of the main executable, not a dynamic library. This can never hurt, and is thus generally good practice. + -

Threads

+ For a multithreaded program some more rules apply: +

+ Files that either allocate through the GC or make thread-related calls should first define the macro GC_THREADS, and then include "gc.h". On some platforms this will redefine some threads primitives, e.g. to let the collector keep track of thread creation. +

+ To take advantage of fast thread-local allocation in versions before 7.0, use the following instead of including gc.h: -

+
+ #define GC_REDIRECT_TO_LOCAL
 #include "gc_local_alloc.h"
 
+
 This will cause GC_MALLOC and GC_MALLOC_ATOMIC to keep per-thread allocation
 caches, and greatly reduce the number of lock acquisitions during allocation.
 For versions after 7.0, this happens implicitly if the collector is built
 with thread-local allocation enabled.
+

C++

+ In the case of C++, you need to be especially careful not to store pointers to the garbage-collected heap in areas that are not traced by the collector. The collector includes some alternate interfaces to make that easier. + -

Debugging

+ Additional debug checks can be performed by defining GC_DEBUG before including gc.h. Additional options are available if the collector -is also built with --enable-full_debug and all allocations are +is also built with --enable-gc-debug (--enable-full-debug in +some older versions) and all allocations are performed with GC_DEBUG defined. + -

What if I can't rewrite/recompile my program?

+ You may be able to build the collector with --enable-redirect-malloc and set the LD_PRELOAD environment variable to point to the resulting library, thus replacing the standard malloc with its garbage-collected counterpart. This is rather platform dependent. See the leak detection documentation for some more details. -

Compiling and linking

@@ -174,10 +203,8 @@ directly on the compile line; the dynamic library could have been used instead, provided we arranged for the dynamic loader to find it, e.g. by setting LD_LIBRARY_PATH. +

Threads

- -

Threads

- On pthread platforms, you will of course also have to link with -lpthread, and compile with any thread-safety options required by your compiler. @@ -186,7 +213,6 @@ or -lrt. Looking at threadlibs.c in the GC build directory should give you the appropriate list if a plain -lpthread doesn't work. -

Other platforms

Other platforms

Threads

Threads

C++

C++

Interaction with the system malloc

Interaction with the system malloc

Other Platforms

Other Platforms

Threads

Threads

C++

C++

Debugging

Debugging

What if I can't rewrite/recompile my program?

What if I can't rewrite/recompile my program?

Compiling and linking

Threads

Threads

Running the executable