diff options
Diffstat (limited to 'boehm-gc/README')
| -rw-r--r-- | boehm-gc/README | 1545 |
1 files changed, 0 insertions, 1545 deletions
diff --git a/boehm-gc/README b/boehm-gc/README deleted file mode 100644 index 4461e303102..00000000000 --- a/boehm-gc/README +++ /dev/null @@ -1,1545 +0,0 @@ -Copyright 1988, 1989 Hans-J. Boehm, Alan J. Demers -Copyright (c) 1991-1996 by Xerox Corporation. All rights reserved. -Copyright (c) 1996-1999 by Silicon Graphics. All rights reserved. -Copyright (c) 1999 by Hewlett-Packard Company. All rights reserved. - - [ This version of the collector modified by Cygnus Solutions. - See the file ChangeLog for details ] - -THIS MATERIAL IS PROVIDED AS IS, WITH ABSOLUTELY NO WARRANTY EXPRESSED -OR IMPLIED. ANY USE IS AT YOUR OWN RISK. - -Permission is hereby granted to use or copy this program -for any purpose, provided the above notices are retained on all copies. -Permission to modify the code and to distribute modified code is granted, -provided the above notices are retained, and a notice that the code was -modified is included with the above copyright notice. - -This is version 5.0alpha4 of a conservative garbage collector for C and C++. - -You might find a more recent version of this at - -http://www.hpl.hp.com/personal/Hans_Boehm/gc - -HISTORY - - - Early versions of this collector were developed as a part of research -projects supported in part by the National Science Foundation -and the Defense Advance Research Projects Agency. -Much of the code was rewritten by Hans-J. Boehm (boehm@acm.org) at Xerox PARC -and at SGI. - -Some other contributors: - -More recent contributors are mentioned in the modification history at the -end of this file. My apologies for any omissions. - -The SPARC specific code was contributed by Mark Weiser -(weiser@parc.xerox.com). The Encore Multimax modifications were supplied by -Kevin Kenny (kenny@m.cs.uiuc.edu). The adaptation to the RT is largely due -to Vernon Lee (scorpion@rice.edu), on machines made available by IBM. -Much of the HP specific code and a number of good suggestions for improving the -generic code are due to Walter Underwood (wunder@hp-ses.sde.hp.com). -Robert Brazile (brazile@diamond.bbn.com) originally supplied the ULTRIX code. -Al Dosser (dosser@src.dec.com) and Regis Cridlig (Regis.Cridlig@cl.cam.ac.uk) -subsequently provided updates and information on variation between ULTRIX -systems. Parag Patel (parag@netcom.com) supplied the A/UX code. -Jesper Peterson(jep@mtiame.mtia.oz.au), Michel Schinz, and -Martin Tauchmann (martintauchmann@bigfoot.com) supplied the Amiga port. -Thomas Funke (thf@zelator.in-berlin.de(?)) and -Brian D.Carlstrom (bdc@clark.lcs.mit.edu) supplied the NeXT ports. -Douglas Steel (doug@wg.icl.co.uk) provided ICL DRS6000 code. -Bill Janssen (janssen@parc.xerox.com) supplied the SunOS dynamic loader -specific code. Manuel Serrano (serrano@cornas.inria.fr) supplied linux and -Sony News specific code. Al Dosser provided Alpha/OSF/1 code. He and -Dave Detlefs(detlefs@src.dec.com) also provided several generic bug fixes. -Alistair G. Crooks(agc@uts.amdahl.com) supplied the NetBSD and 386BSD ports. -Jeffrey Hsu (hsu@soda.berkeley.edu) provided the FreeBSD port. -Brent Benson (brent@jade.ssd.csd.harris.com) ported the collector to -a Motorola 88K processor running CX/UX (Harris NightHawk). -Ari Huttunen (Ari.Huttunen@hut.fi) generalized the OS/2 port to -nonIBM development environments (a nontrivial task). -Patrick Beard (beard@cs.ucdavis.edu) provided the initial MacOS port. -David Chase, then at Olivetti Research, suggested several improvements. -Scott Schwartz (schwartz@groucho.cse.psu.edu) supplied some of the -code to save and print call stacks for leak detection on a SPARC. -Jesse Hull and John Ellis supplied the C++ interface code. -Zhong Shao performed much of the experimentation that led to the -current typed allocation facility. (His dynamic type inference code hasn't -made it into the released version of the collector, yet.) -(Blame for misinstallation of these modifications goes to the first author, -however.) - -OVERVIEW - - This is intended to be a general purpose, garbage collecting storage -allocator. The algorithms used are described in: - -Boehm, H., and M. Weiser, "Garbage Collection in an Uncooperative Environment", -Software Practice & Experience, September 1988, pp. 807-820. - -Boehm, H., A. Demers, and S. Shenker, "Mostly Parallel Garbage Collection", -Proceedings of the ACM SIGPLAN '91 Conference on Programming Language Design -and Implementation, SIGPLAN Notices 26, 6 (June 1991), pp. 157-164. - -Boehm, H., "Space Efficient Conservative Garbage Collection", Proceedings -of the ACM SIGPLAN '91 Conference on Programming Language Design and -Implementation, SIGPLAN Notices 28, 6 (June 1993), pp. 197-206. - - Possible interactions between the collector and optimizing compilers are -discussed in - -Boehm, H., and D. Chase, "A Proposal for GC-safe C Compilation", -The Journal of C Language Translation 4, 2 (December 1992). - -and - -Boehm H., "Simple GC-safe Compilation", Proceedings -of the ACM SIGPLAN '96 Conference on Programming Language Design and -Implementation. - -(Both are also available from -http://reality.sgi.com/boehm/papers/, among other places.) - - Unlike the collector described in the second reference, this collector -operates either with the mutator stopped during the entire collection -(default) or incrementally during allocations. (The latter is supported -on only a few machines.) It does not rely on threads, but is intended -to be thread-safe. - - Some of the ideas underlying the collector have previously been explored -by others. (Doug McIlroy wrote a vaguely similar collector that is part of -version 8 UNIX (tm).) However none of this work appears to have been widely -disseminated. - - Rudimentary tools for use of the collector as a leak detector are included, as -is a fairly sophisticated string package "cord" that makes use of the collector. -(See cord/README.) - - -GENERAL DESCRIPTION - - This is a garbage collecting storage allocator that is intended to be -used as a plug-in replacement for C's malloc. - - Since the collector does not require pointers to be tagged, it does not -attempt to ensure that all inaccessible storage is reclaimed. However, -in our experience, it is typically more successful at reclaiming unused -memory than most C programs using explicit deallocation. Unlike manually -introduced leaks, the amount of unreclaimed memory typically stays -bounded. - - In the following, an "object" is defined to be a region of memory allocated -by the routines described below. - - Any objects not intended to be collected must be pointed to either -from other such accessible objects, or from the registers, -stack, data, or statically allocated bss segments. Pointers from -the stack or registers may point to anywhere inside an object. -The same is true for heap pointers if the collector is compiled with - ALL_INTERIOR_POINTERS defined, as is now the default. - -Compiling without ALL_INTERIOR_POINTERS may reduce accidental retention -of garbage objects, by requiring pointers from the heap to to the beginning -of an object. But this no longer appears to be a significant -issue for most programs. - -There are a number of routines which modify the pointer recognition -algorithm. GC_register_displacement allows certain interior pointers -to be recognized even if ALL_INTERIOR_POINTERS is nor defined. -GC_malloc_ignore_off_page allows some pointers into the middle of large objects -to be disregarded, greatly reducing the probablility of accidental -retention of large objects. For most purposes it seems best to compile -with ALL_INTERIOR_POINTERS and to use GC_malloc_ignore_off_page if -you get collector warnings from allocations of very large objects. -See README.debugging for details. - - Note that pointers inside memory allocated by the standard "malloc" are not -seen by the garbage collector. Thus objects pointed to only from such a -region may be prematurely deallocated. It is thus suggested that the -standard "malloc" be used only for memory regions, such as I/O buffers, that -are guaranteed not to contain pointers to garbage collectable memory. -Pointers in C language automatic, static, or register variables, -are correctly recognized. (Note that GC_malloc_uncollectable has semantics -similar to standard malloc, but allocates objects that are traced by the -collector.) - - The collector does not always know how to find pointers in data -areas that are associated with dynamic libraries. This is easy to -remedy IF you know how to find those data areas on your operating -system (see GC_add_roots). Code for doing this under SunOS, IRIX 5.X and 6.X, -HP/UX, Alpha OSF/1, Linux, and win32 is included and used by default. (See -README.win32 for win32 details.) On other systems pointers from dynamic -library data areas may not be considered by the collector. - - Note that the garbage collector does not need to be informed of shared -read-only data. However if the shared library mechanism can introduce -discontiguous data areas that may contain pointers, then the collector does -need to be informed. - - Signal processing for most signals may be deferred during collection, -and during uninterruptible parts of the allocation process. Unlike -standard ANSI C mallocs, it can be safe to invoke malloc -from a signal handler while another malloc is in progress, provided -the original malloc is not restarted. (Empirically, many UNIX -applications already assume this.) To obtain this level of signal -safety, remove the definition of -DNO_SIGNALS in Makefile. This incurs -a minor performance penalty, and hence is no longer the default. - - The allocator/collector can also be configured for thread-safe operation. -(Full signal safety can also be achieved, but only at the cost of two system -calls per malloc, which is usually unacceptable.) - -INSTALLATION AND PORTABILITY - - As distributed, the macro SILENT is defined in Makefile. -In the event of problems, this can be removed to obtain a moderate -amount of descriptive output for each collection. -(The given statistics exhibit a few peculiarities. -Things don't appear to add up for a variety of reasons, most notably -fragmentation losses. These are probably much more significant for the -contrived program "test.c" than for your application.) - - Note that typing "make test" will automatically build the collector -and then run setjmp_test and gctest. Setjmp_test will give you information -about configuring the collector, which is useful primarily if you have -a machine that's not already supported. Gctest is a somewhat superficial -test of collector functionality. Failure is indicated by a core dump or -a message to the effect that the collector is broken. Gctest takes about -35 seconds to run on a SPARCstation 2. On a slower machine, -expect it to take a while. It may use up to 8 MB of memory. (The -multi-threaded version will use more.) "Make test" will also, as -its last step, attempt to build and test the "cord" string library. -This will fail without an ANSI C compiler. - - The Makefile will generate a library gc.a which you should link against. -Typing "make cords" will add the cord library to gc.a. -Note that this requires an ANSI C compiler. - - It is suggested that if you need to replace a piece of the collector -(e.g. GC_mark_rts.c) you simply list your version ahead of gc.a on the - work.) -ld command line, rather than replacing the one in gc.a. (This will -generate numerous warnings under some versions of AIX, but it still -works.) - - All include files that need to be used by clients will be put in the -include subdirectory. (Normally this is just gc.h. "Make cords" adds -"cord.h" and "ec.h".) - - The collector currently is designed to run essentially unmodified on -machines that use a flat 32-bit or 64-bit address space. -That includes the vast majority of Workstations and X86 (X >= 3) PCs. -(The list here was deleted because it was getting too long and constantly -out of date.) - It does NOT run under plain 16-bit DOS or Windows 3.X. There are however -various packages (e.g. win32s, djgpp) that allow flat 32-bit address -applications to run under those systemsif the have at least an 80386 processor, -and several of those are compatible with the collector. - - In a few cases (Amiga, OS/2, Win32, MacOS) a separate makefile -or equivalent is supplied. Many of these have separate README.system -files. - - Dynamic libraries are completely supported only under SunOS -(and even that support is not functional on the last Sun 3 release), -IRIX 5&6, HP-PA, Win32 (not Win32S) and OSF/1 on DEC AXP machines. -On other machines we recommend that you do one of the following: - - 1) Add dynamic library support (and send us the code). - 2) Use static versions of the libraries. - 3) Arrange for dynamic libraries to use the standard malloc. - This is still dangerous if the library stores a pointer to a - garbage collected object. But nearly all standard interfaces - prohibit this, because they deal correctly with pointers - to stack allocated objects. (Strtok is an exception. Don't - use it.) - - In all cases we assume that pointer alignment is consistent with that -enforced by the standard C compilers. If you use a nonstandard compiler -you may have to adjust the alignment parameters defined in gc_priv.h. - - A port to a machine that is not byte addressed, or does not use 32 bit -or 64 bit addresses will require a major effort. A port to plain MSDOS -or win16 is hard. - - For machines not already mentioned, or for nonstandard compilers, the -following are likely to require change: - -1. The parameters in gcconfig.h. - The parameters that will usually require adjustment are - STACKBOTTOM, ALIGNMENT and DATASTART. Setjmp_test - prints its guesses of the first two. - DATASTART should be an expression for computing the - address of the beginning of the data segment. This can often be - &etext. But some memory management units require that there be - some unmapped space between the text and the data segment. Thus - it may be more complicated. On UNIX systems, this is rarely - documented. But the adb "$m" command may be helpful. (Note - that DATASTART will usually be a function of &etext. Thus a - single experiment is usually insufficient.) - STACKBOTTOM is used to initialize GC_stackbottom, which - should be a sufficient approximation to the coldest stack address. - On some machines, it is difficult to obtain such a value that is - valid across a variety of MMUs, OS releases, etc. A number of - alternatives exist for using the collector in spite of this. See the - discussion in gcconfig.h immediately preceding the various - definitions of STACKBOTTOM. - -2. mach_dep.c. - The most important routine here is one to mark from registers. - The distributed file includes a generic hack (based on setjmp) that - happens to work on many machines, and may work on yours. Try - compiling and running setjmp_t.c to see whether it has a chance of - working. (This is not correct C, so don't blame your compiler if it - doesn't work. Based on limited experience, register window machines - are likely to cause trouble. If your version of setjmp claims that - all accessible variables, including registers, have the value they - had at the time of the longjmp, it also will not work. Vanilla 4.2 BSD - on Vaxen makes such a claim. SunOS does not.) - If your compiler does not allow in-line assembly code, or if you prefer - not to use such a facility, mach_dep.c may be replaced by a .s file - (as we did for the MIPS machine and the PC/RT). - At this point enough architectures are supported by mach_dep.c - that you will rarely need to do more than adjust for assembler - syntax. - -3. os_dep.c (and gc_priv.h). - Several kinds of operating system dependent routines reside here. - Many are optional. Several are invoked only through corresponding - macros in gc_priv.h, which may also be redefined as appropriate. - The routine GC_register_data_segments is crucial. It registers static - data areas that must be traversed by the collector. (User calls to - GC_add_roots may sometimes be used for similar effect.) - Routines to obtain memory from the OS also reside here. - Alternatively this can be done entirely by the macro GET_MEM - defined in gc_priv.h. Routines to disable and reenable signals - also reside here if they are need by the macros DISABLE_SIGNALS - and ENABLE_SIGNALS defined in gc_priv.h. - In a multithreaded environment, the macros LOCK and UNLOCK - in gc_priv.h will need to be suitably redefined. - The incremental collector requires page dirty information, which - is acquired through routines defined in os_dep.c. Unless directed - otherwise by gcconfig.h, these are implemented as stubs that simply - treat all pages as dirty. (This of course makes the incremental - collector much less useful.) - -4. dyn_load.c - This provides a routine that allows the collector to scan data - segments associated with dynamic libraries. Often it is not - necessary to provide this routine unless user-written dynamic - libraries are used. - - For a different version of UN*X or different machines using the -Motorola 68000, Vax, SPARC, 80386, NS 32000, PC/RT, or MIPS architecture, -it should frequently suffice to change definitions in gcconfig.h. - - -THE C INTERFACE TO THE ALLOCATOR - - The following routines are intended to be directly called by the user. -Note that usually only GC_malloc is necessary. GC_clear_roots and GC_add_roots -calls may be required if the collector has to trace from nonstandard places -(e.g. from dynamic library data areas on a machine on which the -collector doesn't already understand them.) On some machines, it may -be desirable to set GC_stacktop to a good approximation of the stack base. -(This enhances code portability on HP PA machines, since there is no -good way for the collector to compute this value.) Client code may include -"gc.h", which defines all of the following, plus many others. - -1) GC_malloc(nbytes) - - allocate an object of size nbytes. Unlike malloc, the object is - cleared before being returned to the user. Gc_malloc will - invoke the garbage collector when it determines this to be appropriate. - GC_malloc may return 0 if it is unable to acquire sufficient - space from the operating system. This is the most probable - consequence of running out of space. Other possible consequences - are that a function call will fail due to lack of stack space, - or that the collector will fail in other ways because it cannot - maintain its internal data structures, or that a crucial system - process will fail and take down the machine. Most of these - possibilities are independent of the malloc implementation. - -2) GC_malloc_atomic(nbytes) - - allocate an object of size nbytes that is guaranteed not to contain any - pointers. The returned object is not guaranteed to be cleared. - (Can always be replaced by GC_malloc, but results in faster collection - times. The collector will probably run faster if large character - arrays, etc. are allocated with GC_malloc_atomic than if they are - statically allocated.) - -3) GC_realloc(object, new_size) - - change the size of object to be new_size. Returns a pointer to the - new object, which may, or may not, be the same as the pointer to - the old object. The new object is taken to be atomic iff the old one - was. If the new object is composite and larger than the original object, - then the newly added bytes are cleared (we hope). This is very likely - to allocate a new object, unless MERGE_SIZES is defined in gc_priv.h. - Even then, it is likely to recycle the old object only if the object - is grown in small additive increments (which, we claim, is generally bad - coding practice.) - -4) GC_free(object) - - explicitly deallocate an object returned by GC_malloc or - GC_malloc_atomic. Not necessary, but can be used to minimize - collections if performance is critical. Probably a performance - loss for very small objects (<= 8 bytes). - -5) GC_expand_hp(bytes) - - Explicitly increase the heap size. (This is normally done automatically - if a garbage collection failed to GC_reclaim enough memory. Explicit - calls to GC_expand_hp may prevent unnecessarily frequent collections at - program startup.) - -6) GC_malloc_ignore_off_page(bytes) - - identical to GC_malloc, but the client promises to keep a pointer to - the somewhere within the first 256 bytes of the object while it is - live. (This pointer should nortmally be declared volatile to prevent - interference from compiler optimizations.) This is the recommended - way to allocate anything that is likely to be larger than 100Kbytes - or so. (GC_malloc may result in failure to reclaim such objects.) - -7) GC_set_warn_proc(proc) - - Can be used to redirect warnings from the collector. Such warnings - should be rare, and should not be ignored during code development. - -8) GC_enable_incremental() - - Enables generational and incremental collection. Useful for large - heaps on machines that provide access to page dirty information. - Some dirty bit implementations may interfere with debugging - (by catching address faults) and place restrictions on heap arguments - to system calls (since write faults inside a system call may not be - handled well). - -9) Several routines to allow for registration of finalization code. - User supplied finalization code may be invoked when an object becomes - unreachable. To call (*f)(obj, x) when obj becomes inaccessible, use - GC_register_finalizer(obj, f, x, 0, 0); - For more sophisticated uses, and for finalization ordering issues, - see gc.h. - - The global variable GC_free_space_divisor may be adjusted up from its -default value of 4 to use less space and more collection time, or down for -the opposite effect. Setting it to 1 or 0 will effectively disable collections -and cause all allocations to simply grow the heap. - - The variable GC_non_gc_bytes, which is normally 0, may be changed to reflect -the amount of memory allocated by the above routines that should not be -considered as a candidate for collection. Careless use may, of course, result -in excessive memory consumption. - - Some additional tuning is possible through the parameters defined -near the top of gc_priv.h. - - If only GC_malloc is intended to be used, it might be appropriate to define: - -#define malloc(n) GC_malloc(n) -#define calloc(m,n) GC_malloc((m)*(n)) - - For small pieces of VERY allocation intensive code, gc_inl.h -includes some allocation macros that may be used in place of GC_malloc -and friends. - - All externally visible names in the garbage collector start with "GC_". -To avoid name conflicts, client code should avoid this prefix, except when -accessing garbage collector routines or variables. - - There are provisions for allocation with explicit type information. -This is rarely necessary. Details can be found in gc_typed.h. - -THE C++ INTERFACE TO THE ALLOCATOR: - - The Ellis-Hull C++ interface to the collector is included in -the collector distribution. If you intend to use this, type -"make c++" after the initial build of the collector is complete. -See gc_cpp.h for the definition of the interface. This interface -tries to approximate the Ellis-Detlefs C++ garbage collection -proposal without compiler changes. - -Cautions: -1. Arrays allocated without new placement syntax are -allocated as uncollectable objects. They are traced by the -collector, but will not be reclaimed. - -2. Failure to use "make c++" in combination with (1) will -result in arrays allocated using the default new operator. -This is likely to result in disaster without linker warnings. - -3. If your compiler supports an overloaded new[] operator, -then gc_cpp.cc and gc_cpp.h should be suitably modified. - -4. Many current C++ compilers have deficiencies that -break some of the functionality. See the comments in gc_cpp.h -for suggested workarounds. - -USE AS LEAK DETECTOR: - - The collector may be used to track down leaks in C programs that are -intended to run with malloc/free (e.g. code with extreme real-time or -portability constraints). To do so define FIND_LEAK in Makefile -This will cause the collector to invoke the report_leak -routine defined near the top of reclaim.c whenever an inaccessible -object is found that has not been explicitly freed. The collector will -no longer reclaim inaccessible memory; in this form it is purely a -debugging tool. - Productive use of this facility normally involves redefining report_leak -to do something more intelligent. This typically requires annotating -objects with additional information (e.g. creation time stack trace) that -identifies their origin. Such code is typically not very portable, and is -not included here, except on SPARC machines. - If all objects are allocated with GC_DEBUG_MALLOC (see next section), -then the default version of report_leak will report the source file -and line number at which the leaked object was allocated. This may -sometimes be sufficient. (On SPARC/SUNOS4 machines, it will also report -a cryptic stack trace. This can often be turned into a sympolic stack -trace by invoking program "foo" with "callprocs foo". Callprocs is -a short shell script that invokes adb to expand program counter values -to symbolic addresses. It was largely supplied by Scott Schwartz.) - Note that the debugging facilities described in the next section can -sometimes be slightly LESS effective in leak finding mode, since in -leak finding mode, GC_debug_free actually results in reuse of the object. -(Otherwise the object is simply marked invalid.) Also note that the test -program is not designed to run meaningfully in FIND_LEAK mode. -Use "make gc.a" to build the collector. - -DEBUGGING FACILITIES: - - The routines GC_debug_malloc, GC_debug_malloc_atomic, GC_debug_realloc, -and GC_debug_free provide an alternate interface to the collector, which -provides some help with memory overwrite errors, and the like. -Objects allocated in this way are annotated with additional -information. Some of this information is checked during garbage -collections, and detected inconsistencies are reported to stderr. - - Simple cases of writing past the end of an allocated object should -be caught if the object is explicitly deallocated, or if the -collector is invoked while the object is live. The first deallocation -of an object will clear the debugging info associated with an -object, so accidentally repeated calls to GC_debug_free will report the -deallocation of an object without debugging information. Out of -memory errors will be reported to stderr, in addition to returning -NIL. - - GC_debug_malloc checking during garbage collection is enabled -with the first call to GC_debug_malloc. This will result in some -slowdown during collections. If frequent heap checks are desired, -this can be achieved by explicitly invoking GC_gcollect, e.g. from -the debugger. - - GC_debug_malloc allocated objects should not be passed to GC_realloc -or GC_free, and conversely. It is however acceptable to allocate only -some objects with GC_debug_malloc, and to use GC_malloc for other objects, -provided the two pools are kept distinct. In this case, there is a very -low probablility that GC_malloc allocated objects may be misidentified as -having been overwritten. This should happen with probability at most -one in 2**32. This probability is zero if GC_debug_malloc is never called. - - GC_debug_malloc, GC_malloc_atomic, and GC_debug_realloc take two -additional trailing arguments, a string and an integer. These are not -interpreted by the allocator. They are stored in the object (the string is -not copied). If an error involving the object is detected, they are printed. - - The macros GC_MALLOC, GC_MALLOC_ATOMIC, GC_REALLOC, GC_FREE, and -GC_REGISTER_FINALIZER are also provided. These require the same arguments -as the corresponding (nondebugging) routines. If gc.h is included -with GC_DEBUG defined, they call the debugging versions of these -functions, passing the current file name and line number as the two -extra arguments, where appropriate. If gc.h is included without GC_DEBUG -defined, then all these macros will instead be defined to their nondebugging -equivalents. (GC_REGISTER_FINALIZER is necessary, since pointers to -objects with debugging information are really pointers to a displacement -of 16 bytes form the object beginning, and some translation is necessary -when finalization routines are invoked. For details, about what's stored -in the header, see the definition of the type oh in debug_malloc.c) - -INCREMENTAL/GENERATIONAL COLLECTION: - -The collector normally interrupts client code for the duration of -a garbage collection mark phase. This may be unacceptable if interactive -response is needed for programs with large heaps. The collector -can also run in a "generational" mode, in which it usually attempts to -collect only objects allocated since the last garbage collection. -Furthermore, in this mode, garbage collections run mostly incrementally, -with a small amount of work performed in response to each of a large number of -GC_malloc requests. - -This mode is enabled by a call to GC_enable_incremental(). - -Incremental and generational collection is effective in reducing -pause times only if the collector has some way to tell which objects -or pages have been recently modified. The collector uses two sources -of information: - -1. Information provided by the VM system. This may be provided in -one of several forms. Under Solaris 2.X (and potentially under other -similar systems) information on dirty pages can be read from the -/proc file system. Under other systems (currently SunOS4.X) it is -possible to write-protect the heap, and catch the resulting faults. -On these systems we require that system calls writing to the heap -(other than read) be handled specially by client code. -See os_dep.c for details. - -2. Information supplied by the programmer. We define "stubborn" -objects to be objects that are rarely changed. Such an object -can be allocated (and enabled for writing) with GC_malloc_stubborn. -Once it has been initialized, the collector should be informed with -a call to GC_end_stubborn_change. Subsequent writes that store -pointers into the object must be preceded by a call to -GC_change_stubborn. - -This mechanism performs best for objects that are written only for -initialization, and such that only one stubborn object is writable -at once. It is typically not worth using for short-lived -objects. Stubborn objects are treated less efficiently than pointerfree -(atomic) objects. - -A rough rule of thumb is that, in the absence of VM information, garbage -collection pauses are proportional to the amount of pointerful storage -plus the amount of modified "stubborn" storage that is reachable during -the collection. - -Initial allocation of stubborn objects takes longer than allocation -of other objects, since other data structures need to be maintained. - -We recommend against random use of stubborn objects in client -code, since bugs caused by inappropriate writes to stubborn objects -are likely to be very infrequently observed and hard to trace. -However, their use may be appropriate in a few carefully written -library routines that do not make the objects themselves available -for writing by client code. - - -BUGS: - - Any memory that does not have a recognizable pointer to it will be -reclaimed. Exclusive-or'ing forward and backward links in a list -doesn't cut it. - Some C optimizers may lose the last undisguised pointer to a memory -object as a consequence of clever optimizations. This has almost -never been observed in practice. Send mail to boehm@acm.org -for suggestions on how to fix your compiler. - This is not a real-time collector. In the standard configuration, -percentage of time required for collection should be constant across -heap sizes. But collection pauses will increase for larger heaps. -(On SPARCstation 2s collection times will be on the order of 300 msecs -per MB of accessible memory that needs to be scanned. Your mileage -may vary.) The incremental/generational collection facility helps, -but is portable only if "stubborn" allocation is used. - Please address bug reports to boehm@acm.org. If you are -contemplating a major addition, you might also send mail to ask whether -it's already been done (or whether we tried and discarded it). - -RECENT VERSIONS: - - Version 1.3 and immediately preceding versions contained spurious -assembly language assignments to TMP_SP. Only the assignment in the PC/RT -code is necessary. On other machines, with certain compiler options, -the assignments can lead to an unsaved register being overwritten. -Known to cause problems under SunOS 3.5 WITHOUT the -O option. (With --O the compiler recognizes it as dead code. It probably shouldn't, -but that's another story.) - - Version 1.4 and earlier versions used compile time determined values -for the stack base. This no longer works on Sun 3s, since Sun 3/80s use -a different stack base. We now use a straightforward heuristic on all -machines on which it is known to work (incl. Sun 3s) and compile-time -determined values for the rest. There should really be library calls -to determine such values. - - Version 1.5 and earlier did not ensure 8 byte alignment for objects -allocated on a sparc based machine. - - Version 1.8 added ULTRIX support in gc_private.h. - - Version 1.9 fixed a major bug in gc_realloc. - - Version 2.0 introduced a consistent naming convention for collector -routines and added support for registering dynamic library data segments -in the standard mark_roots.c. Most of the data structures were revamped. -The treatment of interior pointers was completely changed. Finalization -was added. Support for locking was added. Object kinds were added. -We added a black listing facility to avoid allocating at addresses known -to occur as integers somewhere in the address space. Much of this -was accomplished by adapting ideas and code from the PCR collector. -The test program was changed and expanded. - - Version 2.1 was the first stable version since 1.9, and added support -for PPCR. - - Version 2.2 added debugging allocation, and fixed various bugs. Among them: -- GC_realloc could fail to extend the size of the object for certain large object sizes. -- A blatant subscript range error in GC_printf, which unfortunately - wasn't exercised on machines with sufficient stack alignment constraints. -- GC_register_displacement did the wrong thing if it was called after - any allocation had taken place. -- The leak finding code would eventually break after 2048 byte - byte objects leaked. -- interface.c didn't compile. -- The heap size remained much too small for large stacks. -- The stack clearing code behaved badly for large stacks, and perhaps - on HP/PA machines. - - Version 2.3 added ALL_INTERIOR_POINTERS and fixed the following bugs: -- Missing declaration of etext in the A/UX version. -- Some PCR root-finding problems. -- Blacklisting was not 100% effective, because the plausible future - heap bounds were being miscalculated. -- GC_realloc didn't handle out-of-memory correctly. -- GC_base could return a nonzero value for addresses inside free blocks. -- test.c wasn't really thread safe, and could erroneously report failure - in a multithreaded environment. (The locking primitives need to be - replaced for other threads packages.) -- GC_CONS was thoroughly broken. -- On a SPARC with dynamic linking, signals stayed diabled while the - client code was running. - (Thanks to Manuel Serrano at INRIA for reporting the last two.) - - Version 2.4 added GC_free_space_divisor as a tuning knob, added - support for OS/2 and linux, and fixed the following bugs: -- On machines with unaligned pointers (e.g. Sun 3), every 128th word could - fail to be considered for marking. -- Dynamic_load.c erroneously added 4 bytes to the length of the data and - bss sections of the dynamic library. This could result in a bad memory - reference if the actual length was a multiple of a page. (Observed on - Sun 3. Can probably also happen on a Sun 4.) - (Thanks to Robert Brazile for pointing out that the Sun 3 version - was broken. Dynamic library handling is still broken on Sun 3s - under 4.1.1U1, but apparently not 4.1.1. If you have such a machine, - use -Bstatic.) - - Version 2.5 fixed the following bugs: -- Removed an explicit call to exit(1) -- Fixed calls to GC_printf and GC_err_printf, so the correct number of - arguments are always supplied. The OS/2 C compiler gets confused if - the number of actuals and the number of formals differ. (ANSI C - doesn't require this to work. The ANSI sanctioned way of doing things - causes too many compatibility problems.) - - Version 3.0 added generational/incremental collection and stubborn - objects. - - Version 3.1 added the following features: -- A workaround for a SunOS 4.X SPARC C compiler - misfeature that caused problems when the collector was turned into - a dynamic library. -- A fix for a bug in GC_base that could result in a memory fault. -- A fix for a performance bug (and several other misfeatures) pointed - out by Dave Detlefs and Al Dosser. -- Use of dirty bit information for static data under Solaris 2.X. -- DEC Alpha/OSF1 support (thanks to Al Dosser). -- Incremental collection on more platforms. -- A more refined heap expansion policy. Less space usage by default. -- Various minor enhancements to reduce space usage, and to reduce - the amount of memory scanned by the collector. -- Uncollectable allocation without per object overhead. -- More conscientious handling of out-of-memory conditions. -- Fixed a bug in debugging stubborn allocation. -- Fixed a bug that resulted in occasional erroneous reporting of smashed - objects with debugging allocation. -- Fixed bogus leak reports of size 4096 blocks with FIND_LEAK. - - Version 3.2 fixed a serious and not entirely repeatable bug in - the incremental collector. It appeared only when dirty bit info - on the roots was available, which is normally only under Solaris. - It also added GC_general_register_disappearing_link, and some - testing code. Interface.c disappeared. - - Version 3.3 fixes several bugs and adds new ports: -- PCR-specific bugs. -- Missing locking in GC_free, redundant FASTUNLOCK - in GC_malloc_stubborn, and 2 bugs in - GC_unregister_disappearing_link. - All of the above were pointed out by Neil Sharman - (neil@cs.mu.oz.au). -- Common symbols allocated by the SunOS4.X dynamic loader - were not included in the root set. -- Bug in GC_finalize (reported by Brian Beuning and Al Dosser) -- Merged Amiga port from Jesper Peterson (untested) -- Merged NeXT port from Thomas Funke (significantly - modified and untested) - - Version 3.4: -- Fixed a performance bug in GC_realloc. -- Updated the amiga port. -- Added NetBSD and 386BSD ports. -- Added cord library. -- Added trivial performance enhancement for - ALL_INTERIOR_POINTERS. (Don't scan last word.) - - Version 3.5 -- Minor collections now mark from roots only once, if that - doesn't cause an excessive pause. -- The stack clearing heuristic was refined to prevent anomalies - with very heavily recursive programs and sparse stacks. -- Fixed a bug that prevented mark stack growth in some cases. - GC_objects_are_marked should be set to TRUE after a call - to GC_push_roots and as part of GC_push_marked, since - both can now set mark bits. I think this is only a performance - bug, but I wouldn't bet on it. It's certainly very hard to argue - that the old version was correct. -- Fixed an incremental collection bug that prevented it from - working at all when HBLKSIZE != getpagesize() -- Changed dynamic_loading.c to include gc_priv.h before testing - DYNAMIC_LOADING. SunOS dynamic library scanning - must have been broken in 3.4. -- Object size rounding now adapts to program behavior. -- Added a workaround (provided by Manuel Serrano and - colleagues) to a long-standing SunOS 4.X (and 3.X?) ld bug - that I had incorrectly assumed to have been squished. - The collector was broken if the text segment size was within - 32 bytes of a multiple of 8K bytes, and if the beginning of - the data segment contained interesting roots. The workaround - assumes a demand-loadable executable. The original may have - have "worked" in some other cases. -- Added dynamic library support under IRIX5. -- Added support for EMX under OS/2 (thanks to Ari Huttunen). - -Version 3.6: -- fixed a bug in the mark stack growth code that was introduced - in 3.4. -- fixed Makefile to work around DEC AXP compiler tail recursion - bug. - -Version 3.7: -- Added a workaround for an HP/UX compiler bug. -- Fixed another stack clearing performance bug. Reworked - that code once more. - -Version 4.0: -- Added support for Solaris threads (which was possible - only by reimplementing some fraction of Solaris threads, - since Sun doesn't currently make the thread debugging - interface available). -- Added non-threads win32 and win32S support. -- (Grudgingly, with suitable muttering of obscenities) renamed - files so that the collector distribution could live on a FAT - file system. Files that are guaranteed to be useless on - a PC still have long names. Gc_inline.h and gc_private.h - still exist, but now just include gc_inl.h and gc_priv.h. -- Fixed a really obscure bug in finalization that could cause - undetected mark stack overflows. (I would be surprised if - any real code ever tickled this one.) -- Changed finalization code to dynamically resize the hash - tables it maintains. (This probably does not matter for well- - -written code. It no doubt does for C++ code that overuses - destructors.) -- Added typed allocation primitives. Rewrote the marker to - accommodate them with more reasonable efficiency. This - change should also speed up marking for GC_malloc allocated - objects a little. See gc_typed.h for new primitives. -- Improved debugging facilities slightly. Allocation time - stack traces are now kept by default on SPARC/SUNOS4. - (Thanks to Scott Schwartz.) -- Added better support for small heap applications. -- Significantly extended cord package. Fixed a bug in the - implementation of lazily read files. Printf and friends now - have cord variants. Cord traversals are a bit faster. -- Made ALL_INTERIOR_POINTERS recognition the default. -- Fixed de so that it can run in constant space, independent - of file size. Added simple string searching to cords and de. -- Added the Hull-Ellis C++ interface. -- Added dynamic library support for OSF/1. - (Thanks to Al Dosser and Tim Bingham at DEC.) -- Changed argument to GC_expand_hp to be expressed - in units of bytes instead of heap blocks. (Necessary - since the heap block size now varies depending on - configuration. The old version was never very clean.) -- Added GC_get_heap_size(). The previous "equivalent" - was broken. -- Restructured the Makefile a bit. - -Since version 4.0: -- Changed finalization implementation to guarantee that - finalization procedures are called outside of the allocation - lock, making direct use of the interface a little less dangerous. - MAY BREAK EXISTING CLIENTS that assume finalizers - are protected by a lock. Since there seem to be few multithreaded - clients that use finalization, this is hopefully not much of - a problem. -- Fixed a gross bug in CORD_prev. -- Fixed a bug in blacklst.c that could result in unbounded - heap growth during startup on machines that do not clear - memory obtained from the OS (e.g. win32S). -- Ported de editor to win32/win32S. (This is now the only - version with a mouse-sensitive UI.) -- Added GC_malloc_ignore_off_page to allocate large arrays - in the presence of ALL_INTERIOR_POINTERS. -- Changed GC_call_with_alloc_lock to not disable signals in - the single-threaded case. -- Reduced retry count in GC_collect_or_expand for garbage - collecting when out of memory. -- Made uncollectable allocations bypass black-listing, as they - should. -- Fixed a bug in typed_test in test.c that could cause (legitimate) - GC crashes. -- Fixed some potential synchronization problems in finalize.c -- Fixed a real locking problem in typd_mlc.c. -- Worked around an AIX 3.2 compiler feature that results in - out of bounds memory references. -- Partially worked around an IRIX5.2 beta problem (which may - or may not persist to the final release). -- Fixed a bug in the heap integrity checking code that could - result in explicitly deallocated objects being identified as - smashed. Fixed a bug in the dbg_mlc stack saving code - that caused old argument pointers to be considered live. -- Fixed a bug in CORD_ncmp (and hence CORD_str). -- Repaired the OS2 port, which had suffered from bit rot - in 4.0. Worked around what appears to be CSet/2 V1.0 - optimizer bug. -- Fixed a Makefile bug for target "c++". - -Since version 4.1: -- Multiple bug fixes/workarounds in the Solaris threads version. - (It occasionally failed to locate some register contents for - marking. It also turns out that thr_suspend and friends are - unreliable in Solaris 2.3. Dirty bit reads appear - to be unreliable under some weird - circumstances. My stack marking code - contained a serious performance bug. The new code is - extremely defensive, and has not failed in several cpu - hours of testing. But no guarantees ...) -- Added MacOS support (thanks to Patrick Beard.) -- Fixed several syntactic bugs in gc_c++.h and friends. (These - didn't bother g++, but did bother most other compilers.) - Fixed gc_c++.h finalization interface. (It didn't.) -- 64 bit alignment for allocated objects was not guaranteed in a - few cases in which it should have been. -- Added GC_malloc_atomic_ignore_off_page. -- Added GC_collect_a_little. -- Added some prototypes to gc.h. -- Some other minor bug fixes (notably in Makefile). -- Fixed OS/2 / EMX port (thanks to Ari Huttunen). -- Fixed AmigaDOS port. (thanks to Michel Schinz). -- Fixed the DATASTART definition under Solaris. There - was a 1 in 16K chance of the collector missing the first - 64K of static data (and thus crashing). -- Fixed some blatant anachronisms in the README file. -- Fixed PCR-Makefile for upcoming PPCR release. - -Since version 4.2: -- Fixed SPARC alignment problem with GC_DEBUG. -- Fixed Solaris threads /proc workaround. The real - problem was an interaction with mprotect. -- Incorporated fix from Patrick Beard for gc_c++.h (now gc_cpp.h). -- Slightly improved allocator space utilization by - fixing the GC_size_map mechanism. -- Integrated some Sony News and MIPS RISCos 4.51 - patches. (Thanks to Nobuyuki Hikichi of - Software Research Associates, Inc. Japan) -- Fixed HP_PA alignment problem. (Thanks to - xjam@cork.cs.berkeley.edu.) -- Added GC_same_obj and friends. Changed GC_base - to return 0 for pointers past the end of large objects. - Improved GC_base performance with ALL_INTERIOR_POINTERS - on machines with a slow integer mod operation. - Added GC_PTR_ADD, GC_PTR_STORE, etc. to prepare - for preprocessor. -- changed the default on most UNIX machines to be that - signals are not disabled during critical GC operations. - This is still ANSI-conforming, though somewhat dangerous - in the presence of signal handlers. But the performance - cost of the alternative is sometimes problematic. - Can be changed back with a minor Makefile edit. -- renamed IS_STRING in gc.h, to CORD_IS_STRING, thus - following my own naming convention. Added the function - CORD_to_const_char_star. -- Fixed a gross bug in GC_finalize. Symptom: occasional - address faults in that function. (Thanks to Anselm - Baird-Smith (Anselm.BairdSmith@inria.fr) -- Added port to ICL DRS6000 running DRS/NX. Restructured - things a bit to factor out common code, and remove obsolete - code. Collector should now run under SUNOS5 with either - mprotect or /proc dirty bits. (Thanks to Douglas Steel - (doug@wg.icl.co.uk)). -- More bug fixes and workarounds for Solaris 2.X. (These were - mostly related to putting the collector in a dynamic library, - which didn't really work before. Also SOLARIS_THREADS - didn't interact well with dl_open.) Thanks to btlewis@eng.sun.com. -- Fixed a serious performance bug on the DEC Alpha. The text - segment was getting registered as part of the root set. - (Amazingly, the result was still fast enough that the bug - was not conspicuous.) The fix works on OSF/1, version 1.3. - Hopefully it also works on other versions of OSF/1 ... -- Fixed a bug in GC_clear_roots. -- Fixed a bug in GC_generic_malloc_words_small that broke - gc_inl.h. (Reported by Antoine de Maricourt. I broke it - in trying to tweak the Mac port.) -- Fixed some problems with cord/de under Linux. -- Fixed some cord problems, notably with CORD_riter4. -- Added DG/UX port. - Thanks to Ben A. Mesander (ben@piglet.cr.usgs.gov) -- Added finalization registration routines with weaker ordering - constraints. (This is necessary for C++ finalization with - multiple inheritance, since the compiler often adds self-cycles.) -- Filled the holes in the SCO port. (Thanks to Michael Arnoldus - <chime@proinf.dk>.) -- John Ellis' additions to the C++ support: From John: - -* I completely rewrote the documentation in the interface gc_c++.h -(later renamed gc_cpp.h). I've tried to make it both clearer and more -precise. - -* The definition of accessibility now ignores pointers from an -finalizable object (an object with a clean-up function) to itself. -This allows objects with virtual base classes to be finalizable by the -collector. Compilers typically implement virtual base classes using -pointers from an object to itself, which under the old definition of -accessibility prevented objects with virtual base classes from ever -being collected or finalized. - -* gc_cleanup now includes gc as a virtual base. This was enabled by -the change in the definition of accessibility. - -* I added support for operator new[]. Since most (all?) compilers -don't yet support operator new[], it is conditionalized on --DOPERATOR_NEW_ARRAY. The code is untested, but its trivial and looks -correct. - -* The test program test_gc_c++ (later renamed test_cpp.cc) -tries to test for the C++-specific functionality not tested by the -other programs. -- Added <unistd.h> include to misc.c. (Needed for ppcr.) -- Added PowerMac port. (Thanks to Patrick Beard again.) -- Fixed "srcdir"-related Makefile problems. Changed things so - that all externally visible include files always appear in the - include subdirectory of the source. Made gc.h directly - includable from C++ code. (These were at Per - Bothner's suggestion.) -- Changed Intel code to also mark from ebp (Kevin Warne's - suggestion). -- Renamed C++ related files so they could live in a FAT - file system. (Charles Fiterman's suggestion.) -- Changed Windows NT Makefile to include C++ support in - gc.lib. Added C++ test as Makefile target. - -Since version 4.3: - - ASM_CLEAR_CODE was erroneously defined for HP - PA machines, resulting in a compile error. - - Fixed OS/2 Makefile to create a library. (Thanks to - Mark Boulter (mboulter@vnet.ibm.com)). - - Gc_cleanup objects didn't work if they were created on - the stack. Fixed. - - One copy of Gc_cpp.h in the distribution was out of - synch, and failed to document some known compiler - problems with explicit destructor invocation. Partially - fixed. There are probably other compilers on which - gc_cleanup is miscompiled. - - Fixed Makefile to pass C compiler flags to C++ compiler. - - Added Mac fixes. - - Fixed os_dep.c to work around what appears to be - a new and different VirtualQuery bug under newer - versions of win32S. - - GC_non_gc_bytes was not correctly maintained by - GC_free. Fixed. Thanks to James Clark (jjc@jclark.com). - - Added GC_set_max_heap_size. - - Changed allocation code to ignore blacklisting if it is preventing - use of a very large block of memory. This has the advantage - that naive code allocating very large objects is much more - likely to work. The downside is you might no - longer find out that such code should really use - GC_malloc_ignore_off_page. - - Changed GC_printf under win32 to close and reopen the file - between calls. FAT file systems otherwise make the log file - useless for debugging. - - Added GC_try_to_collect and GC_get_bytes_since_gc. These - allow starting an abortable collection during idle times. - This facility does not require special OS support. (Thanks to - Michael Spertus of Geodesic Systems for suggesting this. It was - actually an easy addition. Kumar Srikantan previously added a similar - facility to a now ancient version of the collector. At the time - this was much harder, and the result was less convincing.) - - Added some support for the Borland development environment. (Thanks - to John Ellis and Michael Spertus.) - - Removed a misfeature from checksums.c that caused unexpected - heap growth. (Thanks to Scott Schwartz.) - - Changed finalize.c to call WARN if it encounters a finalization cycle. - WARN is defined in gc_priv.h to write a message, usually to stdout. - In many environments, this may be inappropriate. - - Renamed NO_PARAMS in gc.h to GC_NO_PARAMS, thus adhering to my own - naming convention. - - Added GC_set_warn_proc to intercept warnings. - - Fixed Amiga port. (Thanks to Michel Schinz (schinz@alphanet.ch).) - - Fixed a bug in mark.c that could result in an access to unmapped - memory from GC_mark_from_mark_stack on machines with unaligned - pointers. - - Fixed a win32 specific performance bug that could result in scanning of - objects allocated with the system malloc. - - Added REDIRECT_MALLOC. - -Since version 4.4: - - Fixed many minor and one major README bugs. (Thanks to Franklin Chen - (chen@adi.com) for pointing out many of them.) - - Fixed ALPHA/OSF/1 dynamic library support. (Thanks to Jonathan Bachrach - (jonathan@harlequin.com)). - - Added incremental GC support (MPROTECT_VDB) for Linux (with some - help from Bruno Haible). - - Altered SPARC recognition tests in gc.h and config.h (mostly as - suggested by Fergus Henderson). - - Added basic incremental GC support for win32, as implemented by - Windows NT and Windows 95. GC_enable_incremental is a noop - under win32s, which doesn't implement enough of the VM interface. - - Added -DLARGE_CONFIG. - - Fixed GC_..._ignore_off_page to also function without - -DALL_INTERIOR_POINTERS. - - (Hopefully) fixed RS/6000 port. (Only the test was broken.) - - Fixed a performance bug in the nonincremental collector running - on machines supporting incremental collection with MPROTECT_VDB - (e.g. SunOS 4, DEC AXP). This turned into a correctness bug under - win32s with win32 incremental collection. (Not all memory protection - was disabled.) - - Fixed some ppcr related bit rot. - - Caused dynamic libraries to be unregistered before reregistering. - The old way turned out to be a performance bug on some machines. - - GC_root_size was not properly maintained under MSWIN32. - - Added -DNO_DEBUGGING and GC_dump. - - Fixed a couple of bugs arising with SOLARIS_THREADS + - REDIRECT_MALLOC. - - Added NetBSD/M68K port. (Thanks to Peter Seebach - <seebs@taniemarie.solon.com>.) - - Fixed a serious realloc bug. For certain object sizes, the collector - wouldn't scan the expanded part of the object. (Thanks to Clay Spence - (cds@peanut.sarnoff.com) for noticing the problem, and helping me to - track it down.) - -Since version 4.5: - - Added Linux ELF support. (Thanks to Arrigo Triulzi <arrigo@ic.ac.uk>.) - - GC_base crashed if it was called before any other GC_ routines. - This could happen if a gc_cleanup object was allocated outside the heap - before any heap allocation. - - The heap expansion heuristic was not stable if all objects had finalization - enabled. Fixed finalize.c to count memory in finalization queue and - avoid explicit deallocation. Changed alloc.c to also consider this count. - (This is still not recommended. It's expensive if nothing else.) Thanks - to John Ellis for pointing this out. - - GC_malloc_uncollectable(0) was broken. Thanks to Phong Vo for pointing - this out. - - The collector didn't compile under Linux 1.3.X. (Thanks to Fred Gilham for - pointing this out.) The current workaround is ugly, but expected to be - temporary. - - Fixed a formatting problem for SPARC stack traces. - - Fixed some '=='s in os_dep.c that should have been assignments. - Fortunately these were in code that should never be executed anyway. - (Thanks to Fergus Henderson.) - - Fixed the heap block allocator to only drop blacklisted blocks in small - chunks. Made BL_LIMIT self adjusting. (Both of these were in response - to heap growth observed by Paul Graham.) - - Fixed the Metrowerks/68K Mac code to also mark from a6. (Thanks - to Patrick Beard.) - - Significantly updated README.debugging. - - Fixed some problems with longjmps out of signal handlers, especially under - Solaris. Added a workaround for the fact that siglongjmp doesn't appear to - do the right thing with -lthread under Solaris. - - Added MSDOS/djgpp port. (Thanks to Mitch Harris (maharri@uiuc.edu).) - - Added "make reserved_namespace" and "make user_namespace". The - first renames ALL "GC_xxx" identifiers as "_GC_xxx". The second is the - inverse transformation. Note that doing this is guaranteed to break all - clients written for the other names. - - descriptor field for kind NORMAL in GC_obj_kinds with ADD_BYTE_AT_END - defined should be -ALIGNMENT not WORDS_TO_BYTES(-1). This is - a serious bug on machines with pointer alignment of less than a word. - - GC_ignore_self_finalize_mark_proc didn't handle pointers to very near the - end of the object correctly. Caused failures of the C++ test on a DEC Alpha - with g++. - - gc_inl.h still had problems. Partially fixed. Added warnings at the - beginning to hopefully specify the remaining dangers. - - Added DATAEND definition to config.h. - - Fixed some of the .h file organization. Fixed "make floppy". - -Since version 4.6: - - Fixed some compilation problems with -DCHECKSUMS (thanks to Ian Searle) - - Updated some Mac specific files to synchronize with Patrick Beard. - - Fixed a serious bug for machines with non-word-aligned pointers. - (Thanks to Patrick Beard for pointing out the problem. The collector - should fail almost any conceivable test immediately on such machines.) - -Since version 4.7: - - Changed a "comment" in a MacOS specific part of mach-dep.c that caused - gcc to fail on other platforms. - -Since version 4.8 - - More README.debugging fixes. - - Objects ready for finalization, but not finalized in the same GC - cycle, could be prematurely collected. This occasionally happened - in test_cpp. - - Too little memory was obtained from the system for very large - objects. That could cause a heap explosion if these objects were - not contiguous (e.g. under PCR), and too much of them was blacklisted. - - Due to an improper initialization, the collector was too hesitant to - allocate blacklisted objects immediately after system startup. - - Moved GC_arrays from the data into the bss segment by not explicitly - initializing it to zero. This significantly - reduces the size of executables, and probably avoids some disk accesses - on program startup. It's conceivable that it might break a port that I - didn't test. - - Fixed EMX_MAKEFILE to reflect the gc_c++.h to gc_cpp.h renaming which - occurred a while ago. - -Since 4.9: - - Fixed a typo around a call to GC_collect_or_expand in alloc.c. It broke - handling of out of memory. (Thanks to Patrick Beard for noticing.) - -Since 4.10: - - Rationalized (hopefully) GC_try_to_collect in an incremental collection - environment. It appeared to not handle a call while a collection was in - progress, and was otherwise too conservative. - - Merged GC_reclaim_or_delete_all into GC_reclaim_all to get rid of some - code. - - Added Patrick Beard's Mac fixes, with substantial completely untested - modifications. - - Fixed the MPROTECT_VDB code to deal with large pages and imprecise - fault addresses (as on an UltraSPARC running Solaris 2.5). Note that this - was not a problem in the default configuration, which uses PROC_VDB. - - The DEC Alpha assembly code needed to restore $gp between calls. - Thanks to Fergus Henderson for tracking this down and supplying a - patch. - - The write command for "de" was completely broken for large files. - I used the easiest portable fix, which involved changing the semantics - so that f.new is written instead of overwriting f. That's safer anyway. - - Added README.solaris2 with a discussion of the possible problems of - mixing the collector's sbrk allocation with malloc/realloc. - - Changed the data segment starting address for SGI machines. The - old code failed under IRIX6. - - Required double word alignment for MIPS. - - Various minor fixes to remove warnings. - - Attempted to fix some Solaris threads problems reported by Zhiying Chen. - In particular, the collector could try to fork a thread with the - world stopped as part of GC_thr_init. It also failed to deal with - the case in which the original thread terminated before the whole - process did. - - Added -DNO_EXECUTE_PERMISSION. This has a major performance impact - on the incremental collector under Irix, and perhaps under other - operating systems. - - Added some code to support allocating the heap with mmap. This may - be preferable under some circumstances. - - Integrated dynamic library support for HP. - (Thanks to Knut Tvedten <knuttv@ifi.uio.no>.) - - Integrated James Clark's win32 threads support, and made a number - of changes to it, many of which were suggested by Pontus Rydin. - This is still not 100% solid. - - Integrated Alistair Crooks' support for UTS4 running on an Amdahl - 370-class machine. - - Fixed a serious bug in explicitly typed allocation. Objects requiring - large descriptors where handled in a way that usually resulted in - a segmentation fault in the marker. (Thanks to Jeremy Fitzhardinge - for helping to track this down.) - - Added partial support for GNU win32 development. (Thanks to Fergus - Henderson.) - - Added optional support for Java-style finalization semantics. (Thanks - to Patrick Bridges.) This is recommended only for Java implementations. - - GC_malloc_uncollectable faulted instead of returning 0 when out of - memory. (Thanks to dan@math.uiuc.edu for noticing.) - - Calls to GC_base before the collector was initialized failed on a - DEC Alpha. (Thanks to Matthew Flatt.) - - Added base pointer checking to GC_REGISTER_FINALIZER in debugging - mode, at the suggestion of Jeremy Fitzhardinge. - - GC_debug_realloc failed for uncollectable objects. (Thanks to - Jeremy Fitzhardinge.) - - Explicitly typed allocation could crash if it ran out of memory. - (Thanks to Jeremy Fitzhardinge.) - - Added minimal support for a DEC Alpha running Linux. - - Fixed a problem with allocation of objects whose size overflowed - ptrdiff_t. (This now fails unconditionally, as it should.) - - Added the beginning of Irix pthread support. - - Integrated Xiaokun Zhu's fixes for djgpp 2.01. - - Added SGI-style STL allocator support (gc_alloc.h). - - Fixed a serious bug in README.solaris2. Multithreaded programs must include - gc.h with SOLARIS_THREADS defined. - - Changed GC_free so it actually deallocates uncollectable objects. - (Thanks to Peter Chubb for pointing out the problem.) - - Added Linux ELF support for dynamic libararies. (Thanks again to - Patrick Bridges.) - - Changed the Borland cc configuration so that the assembler is not - required. - - Fixed a bug in the C++ test that caused it to fail in 64-bit - environments. - -Since 4.11: - - Fixed ElfW definition in dyn_load.c. (Thanks to Fergus Henderson.) - This prevented the dynamic library support from compiling on some - older ELF Linux systems. - - Fixed UTS4 port (which I apparently mangled during the integration) - (Thanks to again to Alistair Crooks.) - - "Make C++" failed on Suns with SC4.0, due to a problem with "bool". - Fixed in gc_priv.h. - - Added more pieces for GNU win32. (Thanks to Timothy N. Newsham.) - The current state of things should suffice for at least some - applications. - - Changed the out of memory retry count handling as suggested by - Kenjiro Taura. (This matters only if GC_max_retries > 0, which - is no longer the default.) - - If a /proc read failed repeatedly, GC_written_pages was not updated - correctly. (Thanks to Peter Chubb for diagnosing this.) - - Under unlikely circumstances, the allocator could infinite loop in - an out of memory situation. (Thanks again to Kenjiro Taura for - identifying the problem and supplying a fix.) - - Fixed a syntactic error in the DJGPP code. (Thanks to Fergus - Henderson for finding this by inspection.) Also fixed a test program - problem with DJGPP (Thanks to Peter Monks.) - - Atomic uncollectable objects were not treated correctly by the - incremental collector. This resulted in weird log statistics and - occasional performance problems. (Thanks to Peter Chubb for pointing - this out.) - - Fixed some problems resulting from compilers that dont define - __STDC__. In this case void * and char * were used inconsistently - in some cases. (Void * should not have been used at all. If - you have an ANSI superset compiler that does not define __STDC__, - please compile with -D__STDC__=0. Thanks to Manuel Serrano and others - for pointing out the problem.) - - Fixed a compilation problem on Irix with -n32 and -DIRIX_THREADS. - Also fixed some other IRIX_THREADS problems which may or may not have - had observable symptoms. - - Fixed an HP PA compilation problem in dyn_load.c. (Thanks to - Philippe Queinnec.) - - SEGV fault handlers sometimes did not get reset correctly. (Thanks - to David Pickens.) - - Added a fix for SOLARIS_THREADS on Intel. (Thanks again to David - Pickens.) This probably needs more work to become functional. - - Fixed struct sigcontext_struct in os_dep.c for compilation under - Linux 2.1.X. (Thanks to Fergus Henderson.) - - Changed the DJGPP STACKBOTTOM and DATASTART values to those suggested - by Kristian Kristensen. These may still not be right, but it is - it is likely to work more often than what was there before. They may - even be exactly right. - - Added a #include <string.h> to test_cpp.cc. This appears to help - with HP/UX and gcc. (Thanks to assar@sics.se.) - - Version 4.11 failed to run in incremental mode on recent 64-bit Irix - kernels. This was a problem related to page unaligned heap segments. - Changed the code to page align heap sections on all platforms. - (I had mistakenly identified this as a kernel problem earlier. - It was not.) - - Version 4.11 did not make allocated storage executable, except on - one or two platforms, due to a bug in a #if test. (Thanks to Dave - Grove for pointing this out.) - - Added sparc_sunos4_mach_dep.s to support Sun's compilers under SunOS4. - - Added GC_exclude_static_roots. - - Fixed the object size mapping algorithm. This shouldn't matter, - but the old code was ugly. - - Heap checking code could die if one of the allocated objects was - larger than its base address. (Unsigned underflow problem. Thanks - to Clay Spence for isolating the problem.) - - Added RS6000 (AIX) dynamic library support and fixed STACK_BOTTOM. - (Thanks to Fred Stearns.) - - Added Fergus Henderson's patches for improved robustness with large - heaps and lots of blacklisting. - - Added Peter Chubb's changes to support Solaris Pthreads, to support - MMAP allocation in Solaris, to allow Solaris to find dynamic libraries - through /proc, to add malloc_typed_ignore_off_page, and a few other - minor features and bug fixes. - - The Solaris 2 port should not use sbrk. I received confirmation from - Sun that the use of sbrk and malloc in the same program is not - supported. The collector now defines USE_MMAP by default on Solaris. - - Replaced the djgpp makefile with Gary Leavens' version. - - Fixed MSWIN32 detection test. - - Added Fergus Henderson's patches to allow putting the collector into - a DLL under GNU win32. - - Added Ivan V. Demakov's port to Watcom C on X86. - - Added Ian Piumarta's Linux/PowerPC port. - - On Brian Burton's suggestion added PointerFreeGC to the placement - options in gc_cpp.h. This is of course unsafe, and may be controversial. - On the other hand, it seems to be needed often enough that it's worth - adding as a standard facility. - -Since 4.12: - - Fixed a crucial bug in the Watcom port. There was a redundant decl - of GC_push_one in gc_priv.h. - - Added FINALIZE_ON_DEMAND. - - Fixed some pre-ANSI cc problems in test.c. - - Removed getpagesize() use for Solaris. It seems to be missing in one - or two versions. - - Fixed bool handling for SPARCCompiler version 4.2. - - Fixed some files in include that had gotten unlinked from the main - copy. - - Some RS/6000 fixes (missing casts). Thanks to Toralf Foerster. - - Fixed several problems in GC_debug_realloc, affecting mostly the - FIND_LEAK case. - - GC_exclude_static_roots contained a buggy unsigned comparison to - terminate a loop. (Thanks to Wilson Ho.) - - CORD_str failed if the substring occurred at the last possible position. - (Only affects cord users.) - - Fixed Linux code to deal with RedHat 5.0 and integrated Peter Bigot's - os_dep.c code for dealing with various Linux versions. - - Added workaround for Irix pthreads sigaction bug and possible signal - misdirection problems. -Since alpha1: - - Changed RS6000 STACKBOTTOM. - - Integrated Patrick Beard's Mac changes. - - Alpha1 didn't compile on Irix m.n, m < 6. - - Replaced Makefile.dj with a new one from Gary Leavens. - - Added Andrew Stitcher's changes to support SCO OpenServer. - - Added PRINT_BLACK_LIST, to allow debugging of high densities of false - pointers. - - Added code to debug allocator to keep track of return address - in GC_malloc caller, thus giving a bit more context. - - Changed default behavior of large block allocator to more - aggressively avoid fragmentation. This is likely to slow down the - collector when it succeeds at reducing space cost. - - Integrated Fergus Henderson's CYGWIN32 changes. They are untested, - but needed for newer versions. - - USE_MMAP had some serious bugs. This caused the collector to fail - consistently on Solaris with -DSMALL_CONFIG. - - Added Linux threads support, thanks largely to Fergus Henderson. -Since alpha2: - - Fixed more Linux threads problems. - - Changed default GC_free_space_divisor to 3 with new large block allocation. - (Thanks to Matthew Flatt for some measurements that suggest the old - value sometimes favors space too much over time.) - - More CYGWIN32 fixes. - - Integrated Tyson-Dowd's Linux-M68K port. - - Minor HP PA and DEC UNIX fixes from Fergus Henderson. - - Integrated Christoffe Raffali's Linux-SPARC changes. - - Allowed for one more GC fixup iteration after a full GC in incremental - mode. Some quick measurements suggested that this significantly - reduces pause times even with smaller GC_RATE values. - - Moved some more GC data structures into GC_arrays. This decreases - pause times and GC overhead, but makes debugging slightly less convenient. - - Fixed namespace pollution problem ("excl_table"). - - Made GC_incremental a constant for -DSMALL_CONFIG, hopefully shrinking - that slightly. - - Added some win32 threads fixes. - - Integrated Ivan Demakov and David Stes' Watcom fixes. - - Various other minor fixes contributed by many people. - - Renamed config.h to gcconfig.h, since config.h tends to be used for - many other things. - - Integrated Matthew Flatt's support for 68K MacOS "far globals". - - Fixed up some of the dynamic library Makefile targets for consistency - across platforms. - - Fixed a USE_MMAP typo that caused out-of-memory handling to fail - on Solaris. - - Added code to test.c to test thread creation a bit more. - - Integrated GC_win32_free_heap, as suggested by Ivan Demakov. - - Fixed Solaris 2.7 stack base finding problem. (This may actually - have been done in an earlier alpha release.) -Since alpha3: - - Fixed MSWIN32 recognition test, which interfered with cygwin. - - Removed unnecessary gc_watcom.asm from distribution. Removed - some obsolete README.win32 text. - - Added Alpha Linux incremental GC support. (Thanks to Philipp Tomsich - for code for retrieving the fault address in a signal handler.) - Changed Linux signal handler context argument to be a pointer. - - Took care of some new warnings generated by the 7.3 SGI compiler. - - Integrated Phillip Musumeci's FreeBSD/ELF fixes. - - -DIRIX_THREADS was broken with the -o32 ABI (typo in gc_priv.h> - -Since 4.13: - - Fixed GC_print_source_ptr to not use a prototype. - - generalized CYGWIN test. - - gc::new did the wrong thing with PointerFreeGC placement. - (Thanks to Rauli Ruohonen.) - - In the ALL_INTERIOR_POINTERS (default) case, some callee-save register - values could fail to be scanned if the register was saved and - reused in a GC frame. This showed up in verbose mode with gctest - compiled with an unreleased SGI compiler. I vaguely recall an old - bug report that may have been related. The bug was probably quite old. - (The problem was that the stack scanning could be deferred until - after the relevant frame was overwritten, and the new save location - might be outside the scanned area. Fixed by more eager stack scanning.) - - PRINT_BLACK_LIST had some problems. A few source addresses were garbage. - - Replaced Makefile.dj and added -I flags to cord make targets. - (Thanks to Gary Leavens.) - - GC_try_to_collect was broken with the nonincremental collector. - - gc_cleanup destructors could pass the wrong address to - GC_register_finalizer_ignore_self in the presence of multiple - inheritance. (Thanks to Darrell Schiebel.) - - Changed PowerPC Linux stack finding code. - -Since 4.14alpha1 - - -DSMALL_CONFIG did not work reliably with large (> 4K) pages. - Recycling the mark stack during expansion could result in a size - zero heap segment, which confused things. (This was probably also an - issue with the normal config and huge pages.) - - Did more work to make sure that callee-save registers were scanned - completely, even with the setjmp-based code. Added USE_GENERIC_PUSH_REGS - macro to facilitate testing on machines I have access to. - - Added code to explicitly push register contents for win32 threads. - This seems to be necessary. (Thanks to Pierre de Rop.) - -Since 4.14alpha2 - - changed STACKBOTTOM for DJGPP (Thanks to Salvador Eduardo Tropea). - -Since 4.14 - - Reworked large block allocator. Now uses multiple doubly linked free - lists to approximate best fit. - - Changed heap expansion heuristic. Entirely free blocks are no longer - counted towards the heap size. This seems to have a major impact on - heap size stability; the old version could expand the heap way too - much in the presence of large block fragmentation. - - added -DGC_ASSERTIONS and some simple assertions inside the collector. - This is mainlyt for collector debugging. - - added -DUSE_MUNMAP to allow the heap to shrink. Suupported on only - a few UNIX-like platforms for now. - - added GC_dump_regions() for debugging of fragmentation issues. - - Changed PowerPC pointer alignment under Linux to 4. (This needs - checking by someone who has one. The suggestions came to me via a - rather circuitous path.) - - Changed the Linux/Alpha port to walk the data segment backwards until - it encounters a SIGSEGV. The old way to find the start of the data - segment broke with a recent release. - - cordxtra.c needed to call GC_REGISTER_FINALIZER instead of - GC_register_finalizer, so that it would continue to work with GC_DEBUG. - - allochblk sometimes cleared the wrong block for debugging purposes - when it dropped blacklisted blocks. This could result in spurious - error reports with GC_DEBUG. - - added MACOS X Server support. (Thanks to Andrew Stone.) - - Changed the Solaris threads code to ignore stack limits > 8 MB with - a warning. Empirically, it is not safe to access arbitrary pages - in such large stacks. And the dirty bit implementation does not - guarantee that none of them will be accessed. - - Integrated Martin Tauchmann's Amiga changes. - - Integrated James Dominy's OpenBSD/SPARC port. - -Since 5.0alpha1 - - Fixed bugs introduced in alpha1 (OpenBSD & large block initialization). - - Added -DKEEP_BACK_PTRS and backptr.h interface. (The implementation - idea came from Al Demers.) - -Since 5.0alpha2 - - Added some highly incomplete code to support a copied young generation. - Comments on nursery.h are appreciated. - - Changed -DFIND_LEAK, -DJAVA_FINALIZATION, and -DFINALIZE_ON_DEMAND, - so the same effect could be obtained with a runtime switch. This is - a step towards standardizing on a single dynamic GC library. - - Significantly changed the way leak detection is handled, as a consequence - of the above. - -Since 5.0 alpha3 - - Added protection fault handling patch for Linux/M68K from Fergus - Henderson and Roman Hodek. - - Removed the tests for SGI_SOURCE in new_gc_alloc.h. This was causing that - interface to fail on nonSGI platforms. - - Changed the Linux stack finding code to use /proc, after chnging it - to use HEURISTIC1. (Thanks to David Mossberger for pointing out the - /proc hook.) - - Added HP/UX incremental GC support and HP/UX 11 thread support. - - Added basic Linux/IA64 support. - - Integrated Anthony Green's PicoJava support. - - Integrated Scott Ananian's StrongARM/NetBSD support. - - Fixed some fairly serious performance bugs in the incremental - collector. These have probably been there essentially forever. - (Mark bits were sometimes set before scanning dirty pages. - The reclaim phase unnecessarily dirtied full small object pages.) - - Changed the reclaim phase to ignore nearly full pages to avoid - touching them. - - Limited GC_black_list_spacing to roughly the heap growth increment. - - Changed full collection triggering heuristic to decrease full GC - frequency by default, but to explicitly trigger full GCs during - heap growth. This doesn't always improve things, but on average it's - probably a win. - - GC_debug_free(0, ...) failed. Thanks to Fergus Henderson for the - bug report and fix. - -To do: - - Very large root set sizes (> 16 MB or so) could cause the collector - to abort with an unexpected mark stack overflow. (Thanks again to - Peter Chubb.) NOT YET FIXED. Workaround is to increase the initial - size. - - The SGI version of the collector marks from mmapped pages, even - if they are not part of dynamic library static data areas. This - causes performance problems with some SGI libraries that use mmap - as a bitmap allocator. NOT YET FIXED. It may be possible to turn - off DYNAMIC_LOADING in the collector as a workaround. It may also - be possible to conditionally intercept mmap and use GC_exclude_static_roots. - The real fix is to walk rld data structures, which looks possible. - - Integrate MIT and DEC pthreads ports. - - Incremental collector should handle large objects better. Currently, - it looks like the whole object is treated as dirty if any part of it - is. |