gc-7.2/doc/debugging.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
   2 <html lang="en-us">
   3 <HEAD>
   4 <meta http-equiv="Content-Type" content="text/html;charset=US-ASCII" >
   5 <TITLE>Debugging Garbage Collector Related Problems</title>
   6 </head>
   7 <BODY>
   8 <H1>Debugging Garbage Collector Related Problems</h1>
   9 This page contains some hints on
  10 debugging issues specific to
  11 the Boehm-Demers-Weiser conservative garbage collector.
  12 It applies both to debugging issues in client code that manifest themselves
  13 as collector misbehavior, and to debugging the collector itself.
  14 <P>
  15 If you suspect a bug in the collector itself, it is strongly recommended
  16 that you try the latest collector release, even if it is labelled as "alpha",
  17 before proceeding.
  18 <H2>Bus Errors and Segmentation Violations</h2>
  19 <P>
  20 If the fault occurred in GC_find_limit, or with incremental collection enabled,
  21 this is probably normal.  The collector installs handlers to take care of
  22 these.  You will not see these unless you are using a debugger.
  23 Your debugger <I>should</i> allow you to continue.
  24 It's often preferable to tell the debugger to ignore SIGBUS and SIGSEGV
  25 ("<TT>handle SIGSEGV SIGBUS nostop noprint</tt>" in gdb,
  26 "<TT>ignore SIGSEGV SIGBUS</tt>" in most versions of dbx)
  27 and set a breakpoint in <TT>abort</tt>.
  28 The collector will call abort if the signal had another cause,
  29 and there was not other handler previously installed.
  30 <P>
  31 We recommend debugging without incremental collection if possible.
  32 (This applies directly to UNIX systems.
  33 Debugging with incremental collection under win32 is worse.  See README.win32.)
  34 <P>
  35 If the application generates an unhandled SIGSEGV or equivalent, it may
  36 often be easiest to set the environment variable GC_LOOP_ON_ABORT.  On many
  37 platforms, this will cause the collector to loop in a handler when the
  38 SIGSEGV is encountered (or when the collector aborts for some other reason),
  39 and a debugger can then be attached to the looping
  40 process.  This sidesteps common operating system problems related
  41 to incomplete core files for multithreaded applications, etc.
  42 <H2>Other Signals</h2>
  43 On most platforms, the multithreaded version of the collector needs one or
  44 two other signals for internal use by the collector in stopping threads.
  45 It is normally wise to tell the debugger to ignore these.  On Linux,
  46 the collector currently uses SIGPWR and SIGXCPU by default.
  47 <H2>Warning Messages About Needing to Allocate Blacklisted Blocks</h2>
  48 The garbage collector generates warning messages of the form
  49 <PRE>
  50 Needed to allocate blacklisted block at 0x...
  51 </pre>
  52 or
  53 <PRE>
  54 Repeated allocation of very large block ...
  55 </pre>
  56 when it needs to allocate a block at a location that it knows to be
  57 referenced by a false pointer.  These false pointers can be either permanent
  58 (<I>e.g.</i> a static integer variable that never changes) or temporary.
  59 In the latter case, the warning is largely spurious, and the block will
  60 eventually be reclaimed normally.
  61 In the former case, the program will still run correctly, but the block
  62 will never be reclaimed.  Unless the block is intended to be
  63 permanent, the warning indicates a memory leak.
  64 <OL>
  65 <LI>Ignore these warnings while you are using GC_DEBUG.  Some of the routines
  66 mentioned below don't have debugging equivalents.  (Alternatively, write
  67 the missing routines and send them to me.)
  68 <LI>Replace allocator calls that request large blocks with calls to
  69 <TT>GC_malloc_ignore_off_page</tt> or
  70 <TT>GC_malloc_atomic_ignore_off_page</tt>.  You may want to set a
  71 breakpoint in <TT>GC_default_warn_proc</tt> to help you identify such calls.
  72 Make sure that a pointer to somewhere near the beginning of the resulting block
  73 is maintained in a (preferably volatile) variable as long as
  74 the block is needed.
  75 <LI>
  76 If the large blocks are allocated with realloc, we suggest instead allocating
  77 them with something like the following.  Note that the realloc size increment
  78 should be fairly large (e.g. a factor of 3/2) for this to exhibit reasonable
  79 performance.  But we all know we should do that anyway.
  80 <PRE>
  81 void * big_realloc(void *p, size_t new_size)
  82 {
  83     size_t old_size = GC_size(p);
  84     void * result;
  85
  86     if (new_size &lt;= 10000) return(GC_realloc(p, new_size));
  87     if (new_size &lt;= old_size) return(p);
  88     result = GC_malloc_ignore_off_page(new_size);
  89     if (result == 0) return(0);
  90     memcpy(result,p,old_size);
  91     GC_free(p);
  92     return(result);
  93 }
  94 </pre>
  95
  96 <LI> In the unlikely case that even relatively small object
  97 (&lt;20KB) allocations are triggering these warnings, then your address
  98 space contains lots of "bogus pointers", i.e. values that appear to
  99 be pointers but aren't.  Usually this can be solved by using GC_malloc_atomic
 100 or the routines in gc_typed.h to allocate large pointer-free regions of bitmaps, etc.  Sometimes the problem can be solved with trivial changes of encoding
 101 in certain values.  It is possible, to identify the source of the bogus
 102 pointers by building the collector with <TT>-DPRINT_BLACK_LIST</tt>,
 103 which will cause it to print the "bogus pointers", along with their location.
 104
 105 <LI> If you get only a fixed number of these warnings, you are probably only
 106 introducing a bounded leak by ignoring them.  If the data structures being
 107 allocated are intended to be permanent, then it is also safe to ignore them.
 108 The warnings can be turned off by calling GC_set_warn_proc with a procedure
 109 that ignores these warnings (e.g. by doing absolutely nothing).
 110 </ol>
 111
 112 <H2>The Collector References a Bad Address in <TT>GC_malloc</tt></h2>
 113
 114 This typically happens while the collector is trying to remove an entry from
 115 its free list, and the free list pointer is bad because the free list link
 116 in the last allocated object was bad.
 117 <P>
 118 With &gt; 99% probability, you wrote past the end of an allocated object.
 119 Try setting <TT>GC_DEBUG</tt> before including <TT>gc.h</tt> and
 120 allocating with <TT>GC_MALLOC</tt>.  This will try to detect such
 121 overwrite errors.
 122
 123 <H2>Unexpectedly Large Heap</h2>
 124
 125 Unexpected heap growth can be due to one of the following:
 126 <OL>
 127 <LI> Data structures that are being unintentionally retained.  This
 128 is commonly caused by data structures that are no longer being used,
 129 but were not cleared, or by caches growing without bounds.
 130 <LI> Pointer misidentification.  The garbage collector is interpreting
 131 integers or other data as pointers and retaining the "referenced"
 132 objects.  A common symptom is that GC_dump() shows much of the heap
 133 as black-listed.
 134 <LI> Heap fragmentation.  This should never result in unbounded growth,
 135 but it may account for larger heaps.  This is most commonly caused
 136 by allocation of large objects.  On some platforms it can be reduced
 137 by building with -DUSE_MUNMAP, which will cause the collector to unmap
 138 memory corresponding to pages that have not been recently used.
 139 <LI> Per object overhead.  This is usually a relatively minor effect, but
 140 it may be worth considering.  If the collector recognizes interior
 141 pointers, object sizes are increased, so that one-past-the-end pointers
 142 are correctly recognized.  The collector can be configured not to do this
 143 (<TT>-DDONT_ADD_BYTE_AT_END</tt>).
 144 <P>
 145 The collector rounds up object sizes so the result fits well into the
 146 chunk size (<TT>HBLKSIZE</tt>, normally 4K on 32 bit machines, 8K
 147 on 64 bit machines) used by the collector.   Thus it may be worth avoiding
 148 objects of size 2K + 1 (or 2K if a byte is being added at the end.)
 149 </ol>
 150 The last two cases can often be identified by looking at the output
 151 of a call to <TT>GC_dump()</tt>.  Among other things, it will print the
 152 list of free heap blocks, and a very brief description of all chunks in
 153 the heap, the object sizes they correspond to, and how many live objects
 154 were found in the chunk at the last collection.
 155 <P>
 156 Growing data structures can usually be identified by
 157 <OL>
 158 <LI> Building the collector with <TT>-DKEEP_BACK_PTRS</tt>,
 159 <LI> Preferably using debugging allocation (defining <TT>GC_DEBUG</tt>
 160 before including <TT>gc.h</tt> and allocating with <TT>GC_MALLOC</tt>),
 161 so that objects will be identified by their allocation site,
 162 <LI> Running the application long enough so
 163 that most of the heap is composed of "leaked" memory, and
 164 <LI> Then calling <TT>GC_generate_random_backtrace()</tt> from backptr.h
 165 a few times to determine why some randomly sampled objects in the heap are
 166 being retained.
 167 </ol>
 168 <P>
 169 The same technique can often be used to identify problems with false
 170 pointers, by noting whether the reference chains printed by
 171 <TT>GC_generate_random_backtrace()</tt> involve any misidentified pointers.
 172 An alternate technique is to build the collector with
 173 <TT>-DPRINT_BLACK_LIST</tt> which will cause it to report values that
 174 are almost, but not quite, look like heap pointers.  It is very likely that
 175 actual false pointers will come from similar sources.
 176 <P>
 177 In the unlikely case that false pointers are an issue, it can usually
 178 be resolved using one or more of the following techniques:
 179 <OL>
 180 <LI> Use <TT>GC_malloc_atomic</tt> for objects containing no pointers.
 181 This is especially important for large arrays containing compressed data,
 182 pseudo-random numbers, and the like.  It is also likely to improve GC
 183 performance, perhaps drastically so if the application is paging.
 184 <LI> If you allocate large objects containing only
 185 one or two pointers at the beginning, either try the typed allocation
 186 primitives is <TT>gc_typed.h</tt>, or separate out the pointerfree component.
 187 <LI> Consider using <TT>GC_malloc_ignore_off_page()</tt>
 188 to allocate large objects.  (See <TT>gc.h</tt> and above for details.
 189 Large means &gt; 100K in most environments.)
 190 <LI> If your heap size is larger than 100MB or so, build the collector with
 191 <TT>-DLARGE_CONFIG</tt>.
 192 This allows the collector to keep more precise black-list
 193 information.
 194 <LI> If you are using heaps close to, or larger than, a gigabyte on a 32-bit
 195 machine, you may want to consider moving to a platform with 64-bit pointers.
 196 This is very likely to resolve any false pointer issues.
 197 </ol>
 198 <H2>Prematurely Reclaimed Objects</h2>
 199 The usual symptom of this is a segmentation fault, or an obviously overwritten
 200 value in a heap object.  This should, of course, be impossible.  In practice,
 201 it may happen for reasons like the following:
 202 <OL>
 203 <LI> The collector did not intercept the creation of threads correctly in
 204 a multithreaded application, <I>e.g.</i> because the client called
 205 <TT>pthread_create</tt> without including <TT>gc.h</tt>, which redefines it.
 206 <LI> The last pointer to an object in the garbage collected heap was stored
 207 somewhere were the collector couldn't see it, <I>e.g.</i> in an
 208 object allocated with system <TT>malloc</tt>, in certain types of
 209 <TT>mmap</tt>ed files,
 210 or in some data structure visible only to the OS.  (On some platforms,
 211 thread-local storage is one of these.)
 212 <LI> The last pointer to an object was somehow disguised, <I>e.g.</i> by
 213 XORing it with another pointer.
 214 <LI> Incorrect use of <TT>GC_malloc_atomic</tt> or typed allocation.
 215 <LI> An incorrect <TT>GC_free</tt> call.
 216 <LI> The client program overwrote an internal garbage collector data structure.
 217 <LI> A garbage collector bug.
 218 <LI> (Empirically less likely than any of the above.) A compiler optimization
 219 that disguised the last pointer.
 220 </ol>
 221 The following relatively simple techniques should be tried first to narrow
 222 down the problem:
 223 <OL>
 224 <LI> If you are using the incremental collector try turning it off for
 225 debugging.
 226 <LI> If you are using shared libraries, try linking statically.  If that works,
 227 ensure that DYNAMIC_LOADING is defined on your platform.
 228 <LI> Try to reproduce the problem with fully debuggable unoptimized code.
 229 This will eliminate the last possibility, as well as making debugging easier.
 230 <LI> Try replacing any suspect typed allocation and <TT>GC_malloc_atomic</tt>
 231 calls with calls to <TT>GC_malloc</tt>.
 232 <LI> Try removing any GC_free calls (<I>e.g.</i> with a suitable
 233 <TT>#define</tt>).
 234 <LI> Rebuild the collector with <TT>-DGC_ASSERTIONS</tt>.
 235 <LI> If the following works on your platform (i.e. if gctest still works
 236 if you do this), try building the collector with
 237 <TT>-DREDIRECT_MALLOC=GC_malloc_uncollectable</tt>.  This will cause
 238 the collector to scan memory allocated with malloc.
 239 </ol>
 240 If all else fails, you will have to attack this with a debugger.
 241 Suggested steps:
 242 <OL>
 243 <LI> Call <TT>GC_dump()</tt> from the debugger around the time of the failure.  Verify
 244 that the collectors idea of the root set (i.e. static data regions which
 245 it should scan for pointers) looks plausible.  If not, i.e. if it doesn't
 246 include some static variables, report this as
 247 a collector bug.  Be sure to describe your platform precisely, since this sort
 248 of problem is nearly always very platform dependent.
 249 <LI> Especially if the failure is not deterministic, try to isolate it to
 250 a relatively small test case.
 251 <LI> Set a break point in <TT>GC_finish_collection</tt>.  This is a good
 252 point to examine what has been marked, i.e. found reachable, by the
 253 collector.
 254 <LI> If the failure is deterministic, run the process
 255 up to the last collection before the failure.
 256 Note that the variable <TT>GC_gc_no</tt> counts collections and can be used
 257 to set a conditional breakpoint in the right one.  It is incremented just
 258 before the call to GC_finish_collection.
 259 If object <TT>p</tt> was prematurely recycled, it may be helpful to
 260 look at <TT>*GC_find_header(p)</tt> at the failure point.
 261 The <TT>hb_last_reclaimed</tt> field will identify the collection number
 262 during which its block was last swept.
 263 <LI> Verify that the offending object still has its correct contents at
 264 this point.
 265 Then call <TT>GC_is_marked(p)</tt> from the debugger to verify that the
 266 object has not been marked, and is about to be reclaimed.  Note that
 267 <TT>GC_is_marked(p)</tt> expects the real address of an object (the
 268 address of the debug header if there is one), and thus it may
 269 be more appropriate to call <TT>GC_is_marked(GC_base(p))</tt>
 270 instead.
 271 <LI> Determine a path from a root, i.e. static variable, stack, or
 272 register variable,
 273 to the reclaimed object.  Call <TT>GC_is_marked(q)</tt> for each object
 274 <TT>q</tt> along the path, trying to locate the first unmarked object, say
 275 <TT>r</tt>.
 276 <LI> If <TT>r</tt> is pointed to by a static root,
 277 verify that the location
 278 pointing to it is part of the root set printed by <TT>GC_dump()</tt>.  If it
 279 is on the stack in the main (or only) thread, verify that
 280 <TT>GC_stackbottom</tt> is set correctly to the base of the stack.  If it is
 281 in another thread stack, check the collector's thread data structure
 282 (<TT>GC_thread[]</tt> on several platforms) to make sure that stack bounds
 283 are set correctly.
 284 <LI> If <TT>r</tt> is pointed to by heap object <TT>s</tt>, check that the
 285 collector's layout description for <TT>s</tt> is such that the pointer field
 286 will be scanned.  Call <TT>*GC_find_header(s)</tt> to look at the descriptor
 287 for the heap chunk.  The <TT>hb_descr</tt> field specifies the layout
 288 of objects in that chunk.  See gc_mark.h for the meaning of the descriptor.
 289 (If it's low order 2 bits are zero, then it is just the length of the
 290 object prefix to be scanned.  This form is always used for objects allocated
 291 with <TT>GC_malloc</tt> or <TT>GC_malloc_atomic</tt>.)
 292 <LI> If the failure is not deterministic, you may still be able to apply some
 293 of the above technique at the point of failure.  But remember that objects
 294 allocated since the last collection will not have been marked, even if the
 295 collector is functioning properly.  On some platforms, the collector
 296 can be configured to save call chains in objects for debugging.
 297 Enabling this feature will also cause it to save the call stack at the
 298 point of the last GC in GC_arrays._last_stack.
 299 <LI> When looking at GC internal data structures remember that a number
 300 of <TT>GC_</tt><I>xxx</i> variables are really macro defined to
 301 <TT>GC_arrays._</tt><I>xxx</i>, so that
 302 the collector can avoid scanning them.
 303 </ol>
 304 </body>
 305 </html>
 306
 307
 308
 309