[BACK]Return to README CVS log [TXT][DIR] Up to [local] / OpenXM_contrib2 / asir2000 / gc / doc

Annotation of OpenXM_contrib2/asir2000/gc/doc/README, Revision 1.3

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

FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>