Annotation of win32/gc/doc/README, revision 1.5
1.1 paf 1: Copyright (c) 1988, 1989 Hans-J. Boehm, Alan J. Demers
2: Copyright (c) 1991-1996 by Xerox Corporation. All rights reserved.
3: Copyright (c) 1996-1999 by Silicon Graphics. All rights reserved.
1.5 ! misha 4: Copyright (c) 1999-2005 Hewlett-Packard Development Company, L.P.
1.1 paf 5:
6: The file linux_threads.c is also
7: Copyright (c) 1998 by Fergus Henderson. All rights reserved.
8:
9: The files Makefile.am, and configure.in are
10: Copyright (c) 2001 by Red Hat Inc. All rights reserved.
11:
12: Several files supporting GNU-style builds are copyrighted by the Free
13: Software Foundation, and carry a different license from that given
1.5 ! misha 14: below. The files included in the libatomic_ops distribution (included
! 15: here) use either the license below, or a similar MIT-style license,
! 16: or, for some files not actually used by the garbage-collector library, the
! 17: GPL.
1.1 paf 18:
19: THIS MATERIAL IS PROVIDED AS IS, WITH ABSOLUTELY NO WARRANTY EXPRESSED
20: OR IMPLIED. ANY USE IS AT YOUR OWN RISK.
21:
22: Permission is hereby granted to use or copy this program
23: for any purpose, provided the above notices are retained on all copies.
24: Permission to modify the code and to distribute modified code is granted,
25: provided the above notices are retained, and a notice that the code was
26: modified is included with the above copyright notice.
27:
28: A few of the files needed to use the GNU-style build procedure come with
29: slightly different licenses, though they are all similar in spirit. A few
30: are GPL'ed, but with an exception that should cover all uses in the
31: collector. (If you are concerned about such things, I recommend you look
32: at the notice in config.guess or ltmain.sh.)
33:
1.5 ! misha 34: This is version 7.1 of a conservative garbage collector for C and C++.
1.1 paf 35:
36: You might find a more recent version of this at
37:
38: http://www.hpl.hp.com/personal/Hans_Boehm/gc
39:
40: OVERVIEW
41:
42: This is intended to be a general purpose, garbage collecting storage
43: allocator. The algorithms used are described in:
44:
45: Boehm, H., and M. Weiser, "Garbage Collection in an Uncooperative Environment",
46: Software Practice & Experience, September 1988, pp. 807-820.
47:
48: Boehm, H., A. Demers, and S. Shenker, "Mostly Parallel Garbage Collection",
49: Proceedings of the ACM SIGPLAN '91 Conference on Programming Language Design
50: and Implementation, SIGPLAN Notices 26, 6 (June 1991), pp. 157-164.
51:
52: Boehm, H., "Space Efficient Conservative Garbage Collection", Proceedings
53: of the ACM SIGPLAN '91 Conference on Programming Language Design and
54: Implementation, SIGPLAN Notices 28, 6 (June 1993), pp. 197-206.
55:
56: Boehm H., "Reducing Garbage Collector Cache Misses", Proceedings of the
57: 2000 International Symposium on Memory Management.
58:
59: Possible interactions between the collector and optimizing compilers are
60: discussed in
61:
62: Boehm, H., and D. Chase, "A Proposal for GC-safe C Compilation",
63: The Journal of C Language Translation 4, 2 (December 1992).
64:
65: and
66:
67: Boehm H., "Simple GC-safe Compilation", Proceedings
68: of the ACM SIGPLAN '96 Conference on Programming Language Design and
69: Implementation.
70:
71: (Some of these are also available from
72: http://www.hpl.hp.com/personal/Hans_Boehm/papers/, among other places.)
73:
74: Unlike the collector described in the second reference, this collector
75: operates either with the mutator stopped during the entire collection
76: (default) or incrementally during allocations. (The latter is supported
1.5 ! misha 77: on fewer machines.) On the most common platforms, it can be built
1.1 paf 78: with or without thread support. On a few platforms, it can take advantage
79: of a multiprocessor to speed up garbage collection.
80:
81: Many of the ideas underlying the collector have previously been explored
82: by others. Notably, some of the run-time systems developed at Xerox PARC
83: in the early 1980s conservatively scanned thread stacks to locate possible
84: pointers (cf. Paul Rovner, "On Adding Garbage Collection and Runtime Types
85: to a Strongly-Typed Statically Checked, Concurrent Language" Xerox PARC
86: CSL 84-7). Doug McIlroy wrote a simpler fully conservative collector that
87: was part of version 8 UNIX (tm), but appears to not have received
88: widespread use.
89:
90: Rudimentary tools for use of the collector as a leak detector are included
91: (see http://www.hpl.hp.com/personal/Hans_Boehm/gc/leak.html),
92: as is a fairly sophisticated string package "cord" that makes use of the
93: collector. (See doc/README.cords and H.-J. Boehm, R. Atkinson, and M. Plass,
94: "Ropes: An Alternative to Strings", Software Practice and Experience 25, 12
95: (December 1995), pp. 1315-1330. This is very similar to the "rope" package
96: in Xerox Cedar, or the "rope" package in the SGI STL or the g++ distribution.)
97:
98: Further collector documantation can be found at
99:
100: http://www.hpl.hp.com/personal/Hans_Boehm/gc
101:
102:
103: GENERAL DESCRIPTION
104:
105: This is a garbage collecting storage allocator that is intended to be
106: used as a plug-in replacement for C's malloc.
107:
108: Since the collector does not require pointers to be tagged, it does not
109: attempt to ensure that all inaccessible storage is reclaimed. However,
110: in our experience, it is typically more successful at reclaiming unused
111: memory than most C programs using explicit deallocation. Unlike manually
112: introduced leaks, the amount of unreclaimed memory typically stays
113: bounded.
114:
115: In the following, an "object" is defined to be a region of memory allocated
116: by the routines described below.
117:
118: Any objects not intended to be collected must be pointed to either
119: from other such accessible objects, or from the registers,
120: stack, data, or statically allocated bss segments. Pointers from
121: the stack or registers may point to anywhere inside an object.
122: The same is true for heap pointers if the collector is compiled with
1.5 ! misha 123: ALL_INTERIOR_POINTERS defined, or GC_all_interior_pointers is otherwise
! 124: set, as is now the default.
1.1 paf 125:
126: Compiling without ALL_INTERIOR_POINTERS may reduce accidental retention
127: of garbage objects, by requiring pointers from the heap to to the beginning
128: of an object. But this no longer appears to be a significant
1.5 ! misha 129: issue for most programs occupying a small fraction of the possible
! 130: address space.
1.1 paf 131:
132: There are a number of routines which modify the pointer recognition
133: algorithm. GC_register_displacement allows certain interior pointers
134: to be recognized even if ALL_INTERIOR_POINTERS is nor defined.
135: GC_malloc_ignore_off_page allows some pointers into the middle of large objects
136: to be disregarded, greatly reducing the probablility of accidental
137: retention of large objects. For most purposes it seems best to compile
138: with ALL_INTERIOR_POINTERS and to use GC_malloc_ignore_off_page if
139: you get collector warnings from allocations of very large objects.
140: See README.debugging for details.
141:
142: WARNING: pointers inside memory allocated by the standard "malloc" are not
143: seen by the garbage collector. Thus objects pointed to only from such a
144: region may be prematurely deallocated. It is thus suggested that the
145: standard "malloc" be used only for memory regions, such as I/O buffers, that
146: are guaranteed not to contain pointers to garbage collectable memory.
147: Pointers in C language automatic, static, or register variables,
148: are correctly recognized. (Note that GC_malloc_uncollectable has semantics
149: similar to standard malloc, but allocates objects that are traced by the
150: collector.)
151:
152: WARNING: the collector does not always know how to find pointers in data
153: areas that are associated with dynamic libraries. This is easy to
154: remedy IF you know how to find those data areas on your operating
155: system (see GC_add_roots). Code for doing this under SunOS, IRIX 5.X and 6.X,
156: HP/UX, Alpha OSF/1, Linux, and win32 is included and used by default. (See
157: README.win32 for win32 details.) On other systems pointers from dynamic
158: library data areas may not be considered by the collector.
159: If you're writing a program that depends on the collector scanning
160: dynamic library data areas, it may be a good idea to include at least
161: one call to GC_is_visible() to ensure that those areas are visible
162: to the collector.
163:
164: Note that the garbage collector does not need to be informed of shared
165: read-only data. However if the shared library mechanism can introduce
166: discontiguous data areas that may contain pointers, then the collector does
167: need to be informed.
168:
169: Signal processing for most signals may be deferred during collection,
170: and during uninterruptible parts of the allocation process.
171: Like standard ANSI C mallocs, by default it is unsafe to invoke
172: malloc (and other GC routines) from a signal handler while another
173: malloc call may be in progress. Removing -DNO_SIGNALS from Makefile
174: attempts to remedy that. But that may not be reliable with a compiler that
175: substantially reorders memory operations inside GC_malloc.
176:
177: The allocator/collector can also be configured for thread-safe operation.
178: (Full signal safety can also be achieved, but only at the cost of two system
179: calls per malloc, which is usually unacceptable.)
180: WARNING: the collector does not guarantee to scan thread-local storage
181: (e.g. of the kind accessed with pthread_getspecific()). The collector
182: does scan thread stacks, though, so generally the best solution is to
183: ensure that any pointers stored in thread-local storage are also
184: stored on the thread's stack for the duration of their lifetime.
185: (This is arguably a longstanding bug, but it hasn't been fixed yet.)
186:
187: INSTALLATION AND PORTABILITY
188:
1.5 ! misha 189: As distributed, the collector operates silently
! 190: In the event of problems, this can usually be changed by defining the
! 191: GC_PRINT_STATS or GC_PRINT_VERBOSE_STATS environment variables. This
! 192: will result in a few lines of descriptive output for each collection.
1.1 paf 193: (The given statistics exhibit a few peculiarities.
194: Things don't appear to add up for a variety of reasons, most notably
195: fragmentation losses. These are probably much more significant for the
196: contrived program "test.c" than for your application.)
197:
1.5 ! misha 198: On most Un*x-like platforms, the collector can be built either using a
! 199: GNU autoconf-based build infrastructure (type "configure; make" in the
! 200: simplest case), or with a classic makefile by itself (type
! 201: "cp Makefile.direct Makefile; make"). Here we focus on the latter option.
! 202: On other platforms, typically only the latter option is available, though
! 203: with a different supplied Makefile.)
! 204:
! 205: Typing "make test" nstead of "make" will automatically build the collector
1.1 paf 206: and then run setjmp_test and gctest. Setjmp_test will give you information
207: about configuring the collector, which is useful primarily if you have
208: a machine that's not already supported. Gctest is a somewhat superficial
209: test of collector functionality. Failure is indicated by a core dump or
210: a message to the effect that the collector is broken. Gctest takes about
1.5 ! misha 211: a second to two to run on reasonable 2007 vintage desktops.
! 212: It may use up to about 30MB of memory. (The
1.1 paf 213: multi-threaded version will use more. 64-bit versions may use more.)
214: "Make test" will also, as its last step, attempt to build and test the
1.5 ! misha 215: "cord" string library.)
1.1 paf 216:
217: The Makefile will generate a library gc.a which you should link against.
218: Typing "make cords" will add the cord library to gc.a.
219: Note that this requires an ANSI C compiler.
220:
221: It is suggested that if you need to replace a piece of the collector
222: (e.g. GC_mark_rts.c) you simply list your version ahead of gc.a on the
223: ld command line, rather than replacing the one in gc.a. (This will
224: generate numerous warnings under some versions of AIX, but it still
225: works.)
226:
227: All include files that need to be used by clients will be put in the
228: include subdirectory. (Normally this is just gc.h. "Make cords" adds
229: "cord.h" and "ec.h".)
230:
231: The collector currently is designed to run essentially unmodified on
232: machines that use a flat 32-bit or 64-bit address space.
233: That includes the vast majority of Workstations and X86 (X >= 3) PCs.
234: (The list here was deleted because it was getting too long and constantly
235: out of date.)
236:
237: In a few cases (Amiga, OS/2, Win32, MacOS) a separate makefile
238: or equivalent is supplied. Many of these have separate README.system
239: files.
240:
241: Dynamic libraries are completely supported only under SunOS/Solaris,
242: (and even that support is not functional on the last Sun 3 release),
243: Linux, FreeBSD, NetBSD, IRIX 5&6, HP/UX, Win32 (not Win32S) and OSF/1
244: on DEC AXP machines plus perhaps a few others listed near the top
245: of dyn_load.c. On other machines we recommend that you do one of
246: the following:
247:
248: 1) Add dynamic library support (and send us the code).
249: 2) Use static versions of the libraries.
250: 3) Arrange for dynamic libraries to use the standard malloc.
251: This is still dangerous if the library stores a pointer to a
252: garbage collected object. But nearly all standard interfaces
253: prohibit this, because they deal correctly with pointers
254: to stack allocated objects. (Strtok is an exception. Don't
255: use it.)
256:
257: In all cases we assume that pointer alignment is consistent with that
258: enforced by the standard C compilers. If you use a nonstandard compiler
259: you may have to adjust the alignment parameters defined in gc_priv.h.
260: Note that this may also be an issue with packed records/structs, if those
261: enforce less alignment for pointers.
262:
263: A port to a machine that is not byte addressed, or does not use 32 bit
264: or 64 bit addresses will require a major effort. A port to plain MSDOS
265: or win16 is hard.
266:
1.5 ! misha 267: For machines not already mentioned, or for nonstandard compilers,
! 268: some porting suggestions are provided in the "porting.html" file.
1.1 paf 269:
270: THE C INTERFACE TO THE ALLOCATOR
271:
272: The following routines are intended to be directly called by the user.
273: Note that usually only GC_malloc is necessary. GC_clear_roots and GC_add_roots
274: calls may be required if the collector has to trace from nonstandard places
275: (e.g. from dynamic library data areas on a machine on which the
276: collector doesn't already understand them.) On some machines, it may
277: be desirable to set GC_stacktop to a good approximation of the stack base.
278: (This enhances code portability on HP PA machines, since there is no
279: good way for the collector to compute this value.) Client code may include
280: "gc.h", which defines all of the following, plus many others.
281:
282: 1) GC_malloc(nbytes)
283: - allocate an object of size nbytes. Unlike malloc, the object is
284: cleared before being returned to the user. Gc_malloc will
285: invoke the garbage collector when it determines this to be appropriate.
286: GC_malloc may return 0 if it is unable to acquire sufficient
287: space from the operating system. This is the most probable
288: consequence of running out of space. Other possible consequences
289: are that a function call will fail due to lack of stack space,
290: or that the collector will fail in other ways because it cannot
291: maintain its internal data structures, or that a crucial system
292: process will fail and take down the machine. Most of these
293: possibilities are independent of the malloc implementation.
294:
295: 2) GC_malloc_atomic(nbytes)
296: - allocate an object of size nbytes that is guaranteed not to contain any
297: pointers. The returned object is not guaranteed to be cleared.
298: (Can always be replaced by GC_malloc, but results in faster collection
299: times. The collector will probably run faster if large character
300: arrays, etc. are allocated with GC_malloc_atomic than if they are
301: statically allocated.)
302:
303: 3) GC_realloc(object, new_size)
304: - change the size of object to be new_size. Returns a pointer to the
305: new object, which may, or may not, be the same as the pointer to
306: the old object. The new object is taken to be atomic iff the old one
307: was. If the new object is composite and larger than the original object,
308: then the newly added bytes are cleared (we hope). This is very likely
309: to allocate a new object, unless MERGE_SIZES is defined in gc_priv.h.
310: Even then, it is likely to recycle the old object only if the object
311: is grown in small additive increments (which, we claim, is generally bad
312: coding practice.)
313:
314: 4) GC_free(object)
315: - explicitly deallocate an object returned by GC_malloc or
316: GC_malloc_atomic. Not necessary, but can be used to minimize
317: collections if performance is critical. Probably a performance
318: loss for very small objects (<= 8 bytes).
319:
320: 5) GC_expand_hp(bytes)
321: - Explicitly increase the heap size. (This is normally done automatically
322: if a garbage collection failed to GC_reclaim enough memory. Explicit
323: calls to GC_expand_hp may prevent unnecessarily frequent collections at
324: program startup.)
325:
326: 6) GC_malloc_ignore_off_page(bytes)
327: - identical to GC_malloc, but the client promises to keep a pointer to
328: the somewhere within the first 256 bytes of the object while it is
329: live. (This pointer should nortmally be declared volatile to prevent
330: interference from compiler optimizations.) This is the recommended
331: way to allocate anything that is likely to be larger than 100Kbytes
332: or so. (GC_malloc may result in failure to reclaim such objects.)
333:
334: 7) GC_set_warn_proc(proc)
335: - Can be used to redirect warnings from the collector. Such warnings
336: should be rare, and should not be ignored during code development.
337:
338: 8) GC_enable_incremental()
339: - Enables generational and incremental collection. Useful for large
340: heaps on machines that provide access to page dirty information.
341: Some dirty bit implementations may interfere with debugging
342: (by catching address faults) and place restrictions on heap arguments
343: to system calls (since write faults inside a system call may not be
344: handled well).
345:
346: 9) Several routines to allow for registration of finalization code.
347: User supplied finalization code may be invoked when an object becomes
348: unreachable. To call (*f)(obj, x) when obj becomes inaccessible, use
349: GC_register_finalizer(obj, f, x, 0, 0);
350: For more sophisticated uses, and for finalization ordering issues,
351: see gc.h.
352:
353: The global variable GC_free_space_divisor may be adjusted up from its
354: default value of 4 to use less space and more collection time, or down for
355: the opposite effect. Setting it to 1 or 0 will effectively disable collections
356: and cause all allocations to simply grow the heap.
357:
358: The variable GC_non_gc_bytes, which is normally 0, may be changed to reflect
359: the amount of memory allocated by the above routines that should not be
360: considered as a candidate for collection. Careless use may, of course, result
361: in excessive memory consumption.
362:
363: Some additional tuning is possible through the parameters defined
364: near the top of gc_priv.h.
365:
366: If only GC_malloc is intended to be used, it might be appropriate to define:
367:
368: #define malloc(n) GC_malloc(n)
369: #define calloc(m,n) GC_malloc((m)*(n))
370:
371: For small pieces of VERY allocation intensive code, gc_inl.h
372: includes some allocation macros that may be used in place of GC_malloc
373: and friends.
374:
375: All externally visible names in the garbage collector start with "GC_".
376: To avoid name conflicts, client code should avoid this prefix, except when
377: accessing garbage collector routines or variables.
378:
379: There are provisions for allocation with explicit type information.
380: This is rarely necessary. Details can be found in gc_typed.h.
381:
382: THE C++ INTERFACE TO THE ALLOCATOR:
383:
384: The Ellis-Hull C++ interface to the collector is included in
385: the collector distribution. If you intend to use this, type
386: "make c++" after the initial build of the collector is complete.
387: See gc_cpp.h for the definition of the interface. This interface
388: tries to approximate the Ellis-Detlefs C++ garbage collection
389: proposal without compiler changes.
390:
1.5 ! misha 391: Very often it will also be necessary to use gc_allocator.h and the
! 392: allocator declared there to construct STL data structures. Otherwise
! 393: subobjects of STL data structures wil be allcoated using a system
! 394: allocator, and objects they refer to may be prematurely collected.
1.1 paf 395:
396: USE AS LEAK DETECTOR:
397:
398: The collector may be used to track down leaks in C programs that are
399: intended to run with malloc/free (e.g. code with extreme real-time or
400: portability constraints). To do so define FIND_LEAK in Makefile
401: This will cause the collector to invoke the report_leak
402: routine defined near the top of reclaim.c whenever an inaccessible
403: object is found that has not been explicitly freed. Such objects will
404: also be automatically reclaimed.
1.5 ! misha 405: If all objects are allocated with GC_DEBUG_MALLOC (see next section), then
! 406: the default version of report_leak will report at least the source file and
! 407: line number at which the leaked object was allocated. This may sometimes be
! 408: sufficient. (On a few machines, it will also report a cryptic stack trace.
! 409: If this is not symbolic, it can somethimes be called into a sympolic stack
! 410: trace by invoking program "foo" with "callprocs foo". Callprocs is a short
! 411: shell script that invokes adb to expand program counter values to symbolic
! 412: addresses. It was largely supplied by Scott Schwartz.)
1.1 paf 413: Note that the debugging facilities described in the next section can
414: sometimes be slightly LESS effective in leak finding mode, since in
415: leak finding mode, GC_debug_free actually results in reuse of the object.
416: (Otherwise the object is simply marked invalid.) Also note that the test
417: program is not designed to run meaningfully in FIND_LEAK mode.
418: Use "make gc.a" to build the collector.
419:
420: DEBUGGING FACILITIES:
421:
422: The routines GC_debug_malloc, GC_debug_malloc_atomic, GC_debug_realloc,
423: and GC_debug_free provide an alternate interface to the collector, which
424: provides some help with memory overwrite errors, and the like.
425: Objects allocated in this way are annotated with additional
426: information. Some of this information is checked during garbage
427: collections, and detected inconsistencies are reported to stderr.
428:
429: Simple cases of writing past the end of an allocated object should
430: be caught if the object is explicitly deallocated, or if the
431: collector is invoked while the object is live. The first deallocation
432: of an object will clear the debugging info associated with an
433: object, so accidentally repeated calls to GC_debug_free will report the
434: deallocation of an object without debugging information. Out of
435: memory errors will be reported to stderr, in addition to returning
436: NIL.
437:
438: GC_debug_malloc checking during garbage collection is enabled
439: with the first call to GC_debug_malloc. This will result in some
440: slowdown during collections. If frequent heap checks are desired,
441: this can be achieved by explicitly invoking GC_gcollect, e.g. from
442: the debugger.
443:
444: GC_debug_malloc allocated objects should not be passed to GC_realloc
445: or GC_free, and conversely. It is however acceptable to allocate only
446: some objects with GC_debug_malloc, and to use GC_malloc for other objects,
447: provided the two pools are kept distinct. In this case, there is a very
448: low probablility that GC_malloc allocated objects may be misidentified as
449: having been overwritten. This should happen with probability at most
450: one in 2**32. This probability is zero if GC_debug_malloc is never called.
451:
452: GC_debug_malloc, GC_malloc_atomic, and GC_debug_realloc take two
453: additional trailing arguments, a string and an integer. These are not
454: interpreted by the allocator. They are stored in the object (the string is
455: not copied). If an error involving the object is detected, they are printed.
456:
457: The macros GC_MALLOC, GC_MALLOC_ATOMIC, GC_REALLOC, GC_FREE, and
458: GC_REGISTER_FINALIZER are also provided. These require the same arguments
459: as the corresponding (nondebugging) routines. If gc.h is included
460: with GC_DEBUG defined, they call the debugging versions of these
461: functions, passing the current file name and line number as the two
462: extra arguments, where appropriate. If gc.h is included without GC_DEBUG
463: defined, then all these macros will instead be defined to their nondebugging
464: equivalents. (GC_REGISTER_FINALIZER is necessary, since pointers to
465: objects with debugging information are really pointers to a displacement
466: of 16 bytes form the object beginning, and some translation is necessary
467: when finalization routines are invoked. For details, about what's stored
468: in the header, see the definition of the type oh in debug_malloc.c)
469:
470: INCREMENTAL/GENERATIONAL COLLECTION:
471:
472: The collector normally interrupts client code for the duration of
473: a garbage collection mark phase. This may be unacceptable if interactive
474: response is needed for programs with large heaps. The collector
475: can also run in a "generational" mode, in which it usually attempts to
476: collect only objects allocated since the last garbage collection.
477: Furthermore, in this mode, garbage collections run mostly incrementally,
478: with a small amount of work performed in response to each of a large number of
479: GC_malloc requests.
480:
481: This mode is enabled by a call to GC_enable_incremental().
482:
483: Incremental and generational collection is effective in reducing
484: pause times only if the collector has some way to tell which objects
485: or pages have been recently modified. The collector uses two sources
486: of information:
487:
488: 1. Information provided by the VM system. This may be provided in
489: one of several forms. Under Solaris 2.X (and potentially under other
490: similar systems) information on dirty pages can be read from the
491: /proc file system. Under other systems (currently SunOS4.X) it is
492: possible to write-protect the heap, and catch the resulting faults.
493: On these systems we require that system calls writing to the heap
494: (other than read) be handled specially by client code.
495: See os_dep.c for details.
496:
497: 2. Information supplied by the programmer. We define "stubborn"
498: objects to be objects that are rarely changed. Such an object
499: can be allocated (and enabled for writing) with GC_malloc_stubborn.
500: Once it has been initialized, the collector should be informed with
501: a call to GC_end_stubborn_change. Subsequent writes that store
502: pointers into the object must be preceded by a call to
503: GC_change_stubborn.
504:
505: This mechanism performs best for objects that are written only for
506: initialization, and such that only one stubborn object is writable
507: at once. It is typically not worth using for short-lived
508: objects. Stubborn objects are treated less efficiently than pointerfree
509: (atomic) objects.
510:
511: A rough rule of thumb is that, in the absence of VM information, garbage
512: collection pauses are proportional to the amount of pointerful storage
513: plus the amount of modified "stubborn" storage that is reachable during
514: the collection.
515:
516: Initial allocation of stubborn objects takes longer than allocation
517: of other objects, since other data structures need to be maintained.
518:
519: We recommend against random use of stubborn objects in client
520: code, since bugs caused by inappropriate writes to stubborn objects
521: are likely to be very infrequently observed and hard to trace.
522: However, their use may be appropriate in a few carefully written
523: library routines that do not make the objects themselves available
524: for writing by client code.
525:
526:
527: BUGS:
528:
529: Any memory that does not have a recognizable pointer to it will be
530: reclaimed. Exclusive-or'ing forward and backward links in a list
531: doesn't cut it.
532: Some C optimizers may lose the last undisguised pointer to a memory
533: object as a consequence of clever optimizations. This has almost
534: never been observed in practice. Send mail to boehm@acm.org
535: for suggestions on how to fix your compiler.
536: This is not a real-time collector. In the standard configuration,
537: percentage of time required for collection should be constant across
538: heap sizes. But collection pauses will increase for larger heaps.
1.5 ! misha 539: They will decrease with the number of processors if parallel marking
! 540: is enabled.
! 541: (On 2007 vintage machines, GC times may be on the order of 5 msecs
! 542: per MB of accessible memory that needs to be scanned and processor.
! 543: Your mileage may vary.) The incremental/generational collection facility
! 544: may help in some cases.
1.1 paf 545: Please address bug reports to boehm@acm.org. If you are
546: contemplating a major addition, you might also send mail to ask whether
547: it's already been done (or whether we tried and discarded it).
548:
E-mail:
![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to README CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [parser3project] / win32 / gc / doc