--- /dev/null
+Copyright 1988, 1989 Hans-J. Boehm, Alan J. Demers
+Copyright (c) 1991-1996 by Xerox Corporation. All rights reserved.
+Copyright (c) 1996-1998 by Silicon Graphics. All rights reserved.
+
+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 4.13alpha2 of a conservative garbage collector for C and C++.
+
+You might find a more recent version of this at
+
+http://reality.sgi.com/boehm/gc.html
+
+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 at Xerox PARC.
+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) and
+Michel Schinz 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.)
+
+Credits for some more recent modifications are given in the modification
+history at the end of this file.
+
+ 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/employees/boehm_mti/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 config.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 config.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 config.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 config.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@mti.sgi.com
+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@mti.sgi.com. 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.
+
+To do:
+ - I have a backlog of unintegrated contributed platform-specific changes.
+ - 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.
+
projects / thirdparty / gcc.git / commitdiff
