diff options
Diffstat (limited to '')
| -rw-r--r-- | gc/doc/README | 617 | ||||
| -rw-r--r-- | gc/doc/README.Mac | 385 | ||||
| -rw-r--r-- | gc/doc/README.MacOSX | 27 | ||||
| -rw-r--r-- | gc/doc/README.OS2 | 6 | ||||
| -rw-r--r-- | gc/doc/README.amiga | 322 | ||||
| -rw-r--r-- | gc/doc/README.autoconf | 59 | ||||
| -rw-r--r-- | gc/doc/README.changes | 1408 | ||||
| -rw-r--r-- | gc/doc/README.contributors | 57 | ||||
| -rw-r--r-- | gc/doc/README.cords | 53 | ||||
| -rw-r--r-- | gc/doc/README.dj | 12 | ||||
| -rw-r--r-- | gc/doc/README.environment | 44 | ||||
| -rw-r--r-- | gc/doc/README.hp | 18 | ||||
| -rw-r--r-- | gc/doc/README.linux | 135 | ||||
| -rw-r--r-- | gc/doc/README.macros | 78 | ||||
| -rw-r--r-- | gc/doc/README.rs6000 | 9 | ||||
| -rw-r--r-- | gc/doc/README.sgi | 41 | ||||
| -rw-r--r-- | gc/doc/README.solaris2 | 62 | ||||
| -rw-r--r-- | gc/doc/README.uts | 2 | ||||
| -rw-r--r-- | gc/doc/README.win32 | 149 |
19 files changed, 3484 insertions, 0 deletions
diff --git a/gc/doc/README b/gc/doc/README new file mode 100644 index 0000000..c6b48c3 --- /dev/null +++ b/gc/doc/README @@ -0,0 +1,617 @@ +Copyright (c) 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-2001 by Hewlett-Packard Company. All rights reserved. + +The file linux_threads.c is also +Copyright (c) 1998 by Fergus Henderson. All rights reserved. + +The files Makefile.am, and configure.in are +Copyright (c) 2001 by Red Hat Inc. All rights reserved. + +The files config.guess and a few others are copyrighted by the Free +Software Foundation. + +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. + +A few of the files needed to use the GNU-style build procedure come with +slightly different licenses, though they are all similar in spirit. A few +are GPL'ed, but with an exception that should cover all uses in the +collector. (If you are concerned about such things, I recommend you look +at the notice in config.guess or ltmain.sh.) + +This is version 6.0 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 + +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. + +Boehm H., "Reducing Garbage Collector Cache Misses", Proceedings of the +2000 International Symposium on Memory Management. + + 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. + +(Some of these are also available from +http://www.hpl.hp.com/personal/Hans_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.) On the most common platforms, it can be built +with or without thread support. On a few platforms, it can take advantage +of a multiprocessor to speed up garbage collection. + + Many of the ideas underlying the collector have previously been explored +by others. Notably, some of the run-time systems developed at Xerox PARC +in the early 1980s conservatively scanned thread stacks to locate possible +pointers (cf. Paul Rovner, "On Adding Garbage Collection and Runtime Types +to a Strongly-Typed Statically Checked, Concurrent Language" Xerox PARC +CSL 84-7). Doug McIlroy wrote a simpler fully conservative collector that +was part of version 8 UNIX (tm), but appears to not have received +widespread use. + + Rudimentary tools for use of the collector as a leak detector are included +(see http://www.hpl.hp.com/personal/Hans_Boehm/gc/leak.html), +as is a fairly sophisticated string package "cord" that makes use of the +collector. (See doc/README.cords and H.-J. Boehm, R. Atkinson, and M. Plass, +"Ropes: An Alternative to Strings", Software Practice and Experience 25, 12 +(December 1995), pp. 1315-1330. This is very similar to the "rope" package +in Xerox Cedar, or the "rope" package in the SGI STL or the g++ distribution.) + +Further collector documantation can be found at + +http://www.hpl.hp.com/personal/Hans_Boehm/gc + + +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. + + WARNING: 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.) + + WARNING: 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. +If you're writing a program that depends on the collector scanning +dynamic library data areas, it may be a good idea to include at least +one call to GC_is_visible() to ensure that those areas are visible +to 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. +Like standard ANSI C mallocs, by default it is unsafe to invoke +malloc (and other GC routines) from a signal handler while another +malloc call may be in progress. Removing -DNO_SIGNALS from Makefile +attempts to remedy that. But that may not be reliable with a compiler that +substantially reorders memory operations inside GC_malloc. + + 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.) +WARNING: the collector does not guarantee to scan thread-local storage +(e.g. of the kind accessed with pthread_getspecific()). The collector +does scan thread stacks, though, so generally the best solution is to +ensure that any pointers stored in thread-local storage are also +stored on the thread's stack for the duration of their lifetime. +(This is arguably a longstanding bug, but it hasn't been fixed yet.) + +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. It may use up to 8 MB of memory. (The +multi-threaded version will use more. 64-bit versions may 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, but +the garbage collector itself should still be usable. + + 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 +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), +Linux, 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. Such objects will +also be automatically reclaimed. + 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). + diff --git a/gc/doc/README.Mac b/gc/doc/README.Mac new file mode 100644 index 0000000..04f4682 --- /dev/null +++ b/gc/doc/README.Mac @@ -0,0 +1,385 @@ +Patrick Beard's Notes for building GC v4.12 with CodeWarrior Pro 2: +---------------------------------------------------------------------------- +The current build environment for the collector is CodeWarrior Pro 2. +Projects for CodeWarrior Pro 2 (and for quite a few older versions) +are distributed in the file Mac_projects.sit.hqx. The project file +:Mac_projects:gc.prj builds static library versions of the collector. +:Mac_projects:gctest.prj builds the GC test suite. + +Configuring the collector is still done by editing the files +:Mac_files:MacOS_config.h and :Mac_files:MacOS_Test_config.h. + +Lars Farm's suggestions on building the collector: +---------------------------------------------------------------------------- +Garbage Collection on MacOS - a manual 'MakeFile' +------------------------------------------------- + +Project files and IDE's are great on the Macintosh, but they do have +problems when used as distribution media. This note tries to provide +porting instructions in pure TEXT form to avoid those problems. A manual +'makefile' if you like. + + GC version: 4.12a2 + Codewarrior: CWPro1 + date: 18 July 1997 + +The notes may or may not apply to earlier or later versions of the +GC/CWPro. Actually, they do apply to earlier versions of both except that +until recently a project could only build one target so each target was a +separate project. The notes will most likely apply to future versions too. +Possibly with minor tweaks. + +This is just to record my experiences. These notes do not mean I now +provide a supported port of the GC to MacOS. It works for me. If it works +for you, great. If it doesn't, sorry, try again...;-) Still, if you find +errors, please let me know. + + mailto: lars.farm@ite.mh.se + + address: Lars Farm + Krönvägen 33b + 856 44 Sundsvall + Sweden + +Porting to MacOS is a bit more complex than it first seems. Which MacOS? +68K/PowerPC? Which compiler? Each supports both 68K and PowerPC and offer a +large number of (unique to each environment) compiler settings. Each +combination of compiler/68K/PPC/settings require a unique combination of +standard libraries. And the IDE's does not select them for you. They don't +even check that the library is built with compatible setting and this is +the major source of problems when porting the GC (and otherwise too). + +You will have to make choices when you configure the GC. I've made some +choices here, but there are other combinations of settings and #defines +that work too. + +As for target settings the major obstacles may be: +- 68K Processor: check "4-byte Ints". +- PPC Processor: uncheck "Store Static Data in TOC". + +What you need to do: +=================== + +1) Build the GC as a library +2) Test that the library works with 'test.c'. +3) Test that the C++ interface 'gc_cpp.cc/h' works with 'test_cpp.cc'. + +1) The Libraries: +================= +I made one project with four targets (68K/PPC tempmem or appheap). One target +will suffice if you're able to decide which one you want. I wasn't... + +Codewarrior allows a large number of compiler/linker settings. I used these: + +Settings shared by all targets: +------------------------------ +o Access Paths: + - User Paths: the GC folder + - System Paths: {Compiler}:Metrowerks Standard Library: + {Compiler}:MacOS Support:Headers: + {Compiler}:MacOS Support:MacHeaders: +o C/C++ language: + - inlining: normal + - direct to SOM: off + - enable/check: exceptions, RTTI, bool (and if you like pool strings) + +PowerPC target settings +----------------------- +o Target Settings: + - name of target + - MacOS PPC Linker +o PPC Target + - name of library +o C/C++ language + - prefix file as described below +o PPC Processor + - Struct Alignment: PowerPC + - uncheck "Store Static Data in TOC" -- important! + I don't think the others matter, I use full optimization and its ok +o PPC Linker + - Factory Settings (SYM file with full paths, faster linking, dead-strip + static init, Main: __start) + + +68K target settings +------------------- +o Target Settings: + - name of target + - MacOS 68K Linker +o 68K Target + - name of library + - A5 relative data +o C/C++ language + - prefix file as described below +o 68K Processor + - Code model: smart + - Struct alignment: 68K + - FP: SANE + - enable 4-Byte Ints -- important! + I don't think the others matter. I selected... + - enable: 68020 + - enable: global register allocation +o IR Optimizer + - enable: Optimize Space, Optimize Speed + I suppose the others would work too, but haven't tried... +o 68K Linker + - Factory Settings (New Style MacsBug,SYM file with full paths, + A6 Frames, fast link, Merge compiler glue into segment 1, + dead-strip static init) + +Prefix Files to configure the GC sources +---------------------------------------- +The Codewarrior equivalent of commandline compilers -DNAME=X is to use +prefix-files. A TEXT file that is automatically #included before the first byte +of every source file. I used these: + +---- ( cut here ) ---- gc_prefix_tempmem.h -- 68K and PPC ----- + #include "gc_prefix_common.h" + #undef USE_TEMPORARY_MEMORY + #define USE_TEMPORARY_MEMORY +---- ( cut here ) ---- gc_prefix_appmem.h -- 68K and PPC ----- + #include "gc_prefix_common.h" + #undef USE_TEMPORARY_MEMORY +// #define USE_TEMPORARY_MEMORY + +---- ( cut here ) ---- gc_prefix_common.h -------------------- +// gc_prefix_common.h +// ------------------ +// Codewarrior prefix file to configure the GC libraries +// +// prefix files are the Codewarrior equivalent of the +// command line option -Dname=x frequently seen in makefiles + +#if !__MWERKS__ + #error only tried this with Codewarrior +#endif + +#if macintosh + #define MSL_USE_PRECOMPILED_HEADERS 0 + #include <ansi_prefix.mac.h> + #ifndef __STDC__ + #define __STDC__ 0 + #endif + + // See list of #defines to configure the library in: 'MakeFile' + // see also README + + #define SILENT // no collection messages. In case + // of trouble you might want this off + #define ALL_INTERIOR_POINTERS // follows interior pointers. +//#define DONT_ADD_BYTE_AT_END // disables the padding if defined. +//#define SMALL_CONFIG // whether to use a smaller heap. + #define NO_SIGNALS // signals aren't real on the Macintosh. + #define ATOMIC_UNCOLLECTABLE // GC_malloc_atomic_uncollectable() + + // define either or none as per personal preference + // used in malloc.c + #define REDIRECT_MALLOC GC_malloc +//#define REDIRECT_MALLOC GC_malloc_uncollectable + // if REDIRECT_MALLOC is #defined make sure that the GC library + // is listed before the ANSI/ISO libs in the Codewarrior + // 'Link order' panel +//#define IGNORE_FREE + + // mac specific configs +//#define USE_TEMPORARY_MEMORY // use Macintosh temporary memory. +//#define SHARED_LIBRARY_BUILD // build for use in a shared library. + +#else + // could build Win32 here too, or in the future + // Rhapsody PPC-mach, Rhapsody PPC-MacOS, + // Rhapsody Intel-mach, Rhapsody Intel-Win32,... + // ... ugh this will get messy ... +#endif + +// make sure ints are at least 32-bit +// ( could be set to 16-bit by compiler settings (68K) ) + +struct gc_private_assert_intsize_{ char x[ sizeof(int)>=4 ? 1 : 0 ]; }; + +#if __powerc + #if __option(toc_data) + #error turn off "store static data in TOC" when using GC + // ... or find a way to add TOC to the root set...(?) + #endif +#endif +---- ( cut here ) ---- end of gc_prefix_common.h ----------------- + +Files to build the GC libraries: +-------------------------------- + allchblk.c + alloc.c + blacklst.c + checksums.c + dbg_mlc.c + finalize.c + headers.c + mach_dep.c + MacOS.c -- contains MacOS code + malloc.c + mallocx.c + mark.c + mark_rts.c + misc.c + new_hblk.c + obj_map.c + os_dep.c -- contains MacOS code + ptr_chck.c + reclaim.c + stubborn.c + typd_mlc.c + gc++.cc -- this is 'gc_cpp.cc' with less 'inline' and + -- throw std::bad_alloc when out of memory + -- gc_cpp.cc works just fine too + +2) Test that the library works with 'test.c'. +============================================= + +The test app is just an ordinary ANSI-C console app. Make sure settings +match the library you're testing. + +Files +----- + test.c + the GC library to test -- link order before ANSI libs + suitable Mac+ANSI libraries + +prefix: +------ +---- ( cut here ) ---- gc_prefix_testlib.h -- all libs ----- +#define MSL_USE_PRECOMPILED_HEADERS 0 +#include <ansi_prefix.mac.h> +#undef NDEBUG + +#define ALL_INTERIOR_POINTERS /* for GC_priv.h */ +---- ( cut here ) ---- + +3) Test that the C++ interface 'gc_cpp.cc/h' works with 'test_cpp.cc'. + +The test app is just an ordinary ANSI-C console app. Make sure settings match +the library you're testing. + +Files +----- + test_cpp.cc + the GC library to test -- link order before ANSI libs + suitable Mac+ANSI libraries + +prefix: +------ +same as for test.c + +For convenience I used one test-project with several targets so that all +test apps are build at once. Two for each library to test: test.c and +gc_app.cc. When I was satisfied that the libraries were ok. I put the +libraries + gc.h + the c++ interface-file in a folder that I then put into +the MSL hierarchy so that I don't have to alter access-paths in projects +that use the GC. + +After that, just add the proper GC library to your project and the GC is in +action! malloc will call GC_malloc and free GC_free, new/delete too. You +don't have to call free or delete. You may have to be a bit cautious about +delete if you're freeing other resources than RAM. See gc_cpp.h. You can +also keep coding as always with delete/free. That works too. If you want, +"include <gc.h> and tweak it's use a bit. + +Symantec SPM +============ +It has been a while since I tried the GC in SPM, but I think that the above +instructions should be sufficient to guide you through in SPM too. SPM +needs to know where the global data is. Use the files 'datastart.c' and +'dataend.c'. Put 'datastart.c' at the top of your project and 'dataend.c' +at the bottom of your project so that all data is surrounded. This is not +needed in Codewarrior because it provides intrinsic variables +__datastart__, __data_end__ that wraps all globals. + +Source Changes (GC 4.12a2) +========================== +Very few. Just one tiny in the GC, not strictly needed. +- MacOS.c line 131 in routine GC_MacFreeTemporaryMemory() + change # if !defined(SHARED_LIBRARY_BUILD) + to # if !defined(SILENT) && !defined(SHARED_LIBRARY_BUILD) + To turn off a message when the application quits (actually, I faked + this change by #defining SHARED_LIBRARY_BUILD in a statically linked + library for more than a year without ill effects but perhaps this is + better). + +- test_cpp.cc + made the first lines of main() look like this: + ------------ + int main( int argc, char* argv[] ) { + #endif + #if macintosh // MacOS + char* argv_[] = {"test_cpp","10"}; // doesn't + argv=argv_; // have a + argc = sizeof(argv_)/sizeof(argv_[0]); // commandline + #endif // + + int i, iters, n; + # ifndef __GNUC__ + alloc dummy_to_fool_the_compiler_into_doing_things_it_currently_cant_handle; + ------------ + +- config.h [now gcconfig.h] + __MWERKS__ does not have to mean MACOS. You can use Codewarrior to + build a Win32 or BeOS library and soon a Rhapsody library. You may + have to change that #if... + + + + It worked for me, hope it works for you. + + Lars Farm + 18 July 1997 +---------------------------------------------------------------------------- + + +Patrick Beard's instructions (may be dated): + +v4.3 of the collector now runs under Symantec C++/THINK C v7.0.4, and +Metrowerks C/C++ v4.5 both 68K and PowerPC. Project files are provided +to build and test the collector under both development systems. + +Configuration +------------- + +To configure the collector, under both development systems, a prefix file +is used to set preprocessor directives. This file is called "MacOS_config.h". +Also to test the collector, "MacOS_Test_config.h" is provided. + +Testing +------- + +To test the collector (always a good idea), build one of the gctest projects, +gctest.¹ (Symantec C++/THINK C), mw/gctest.68K.¹, or mw/gctest.PPC.¹. The +test will ask you how many times to run; 1 should be sufficient. + +Building +-------- + +For your convenience project files for the major Macintosh development +systems are provided. + +For Symantec C++/THINK C, you must build the two projects gclib-1.¹ and +gclib-2.¹. It has to be split up because the collector has more than 32k +of static data and no library can have more than this in the Symantec +environment. (Future versions will probably fix this.) + +For Metrowerks C/C++ 4.5 you build gc.68K.¹/gc.PPC.¹ and the result will +be a library called gc.68K.lib/gc.PPC.lib. + +Using +----- + +Under Symantec C++/THINK C, you can just add the gclib-1.¹ and gclib-2.¹ +projects to your own project. Under Metrowerks, you add gc.68K.lib or +gc.PPC.lib and two additional files. You add the files called datastart.c +and dataend.c to your project, bracketing all files that use the collector. +See mw/gctest.¹ for an example. + +Include the projects/libraries you built above into your own project, +#include "gc.h", and call GC_malloc. You don't have to call GC_free. + + +Patrick C. Beard +January 4, 1995 diff --git a/gc/doc/README.MacOSX b/gc/doc/README.MacOSX new file mode 100644 index 0000000..2abf0b4 --- /dev/null +++ b/gc/doc/README.MacOSX @@ -0,0 +1,27 @@ +While the GC should work on MacOS X Server, MacOS X and Darwin, I only tested +it on MacOS X Server. +I've added a PPC assembly version of GC_push_regs(), thus the setjmp() hack is +no longer necessary. Incremental collection is supported via mprotect/signal. +The current solution isn't really optimal because the signal handler must decode +the faulting PPC machine instruction in order to find the correct heap address. +Further, it must poke around in the register state which the kernel saved away +in some obscure register state structure before it calls the signal handler - +needless to say the layout of this structure is no where documented. +Threads and dynamic libraries are not yet supported (adding dynamic library +support via the low-level dyld API shouldn't be that hard). + +The original MacOS X port was brought to you by Andrew Stone. + + +June, 1 2000 + +Dietmar Planitzer +dave.pl@ping.at + +Note from Andrew Begel: + +One more fix to enable gc.a to link successfully into a shared library for +MacOS X. You have to add -fno-common to the CFLAGS in the Makefile. MacOSX +disallows common symbols in anything that eventually finds its way into a +shared library. (I don't completely understand why, but -fno-common seems to +work and doesn't mess up the garbage collector's functionality). diff --git a/gc/doc/README.OS2 b/gc/doc/README.OS2 new file mode 100644 index 0000000..5345bbd --- /dev/null +++ b/gc/doc/README.OS2 @@ -0,0 +1,6 @@ +The code assumes static linking, and a single thread. The editor de has +not been ported. The cord test program has. The supplied OS2_MAKEFILE +assumes the IBM C Set/2 environment, but the code shouldn't. + +Since we haven't figured out hoe to do perform partial links or to build static +libraries, clients currently need to link against a long list of executables. diff --git a/gc/doc/README.amiga b/gc/doc/README.amiga new file mode 100644 index 0000000..730dce3 --- /dev/null +++ b/gc/doc/README.amiga @@ -0,0 +1,322 @@ +=========================================================================== + Kjetil S. Matheussen's notes (28-11-2000) +=========================================================================== +Compiles under SAS/C again. Should allso still compile under other +amiga compilers without big changes. I haven't checked if it still +works under gcc, because I don't have gcc for amiga. But I have +updated 'Makefile', and hope it compiles fine. + + +WHATS NEW: + +1. + Made a pretty big effort in preventing GCs allocating-functions from returning + chip-mem. + + The lower part of the new file AmigaOS.c does this in various ways, mainly by + wrapping GC_malloc, GC_malloc_atomic, GC_malloc_uncollectable, + GC_malloc_atomic_uncollectable, GC_malloc_stubborn, GC_malloc_ignore_off_page + and GC_malloc_atomic_ignore_off_page. GC_realloc is allso wrapped, but + doesn't do the same effort in preventing to return chip-mem. + Other allocating-functions (f.ex. GC_*_typed_) can probably be + used without any problems, but beware that the warn hook will not be called. + In case of problems, don't define GC_AMIGA_FASTALLOC. + + Programs using more time actually using the memory allocated + (instead of just allocate and free rapidly) have + the most to earn on this, but even gctest now normally runs twice + as fast and uses less memory, on my poor 8MB machine. + + The changes have only effect when there is no more + fast-mem left. But with the way GC works, it + could happen quite often. Beware that an atexit handler had to be added, + so using the abort() function will make a big memory-loss. + If you absolutely must call abort() instead of exit(), try calling + the GC_amiga_free_all_mem function before abort(). + + New amiga-spesific compilation flags: + + GC_AMIGA_FASTALLOC - By NOT defining this option, GC will work like before, + it will not try to force fast-mem out of the OS, and + it will use normal calloc for allocation, and the rest + of the following flags will have no effect. + + GC_AMIGA_ONLYFAST - Makes GC never to return chip-mem. GC_AMIGA_RETRY have + no effect if this flag is set. + + GC_AMIGA_GC - If gc returns NULL, do a GC_gcollect, and try again. This + usually is a success with the standard GC configuration. + It is allso the most important flag to set to prevent + GC from returning chip-mem. Beware that it slows down a lot + when a program is rapidly allocating/deallocating when + theres either very little fast-memory left or verly little + chip-memory left. Its not a very common situation, but gctest + sometimes (very rare) use many minutes because of this. + + GC_AMIGA_RETRY - If gc succeed allocating memory, but it is chip-mem, + try again and see if it is fast-mem. Most of the time, + it will actually return fast-mem for the second try. + I have set max number of retries to 9 or size/5000. You + can change this if you like. (see GC_amiga_rec_alloc()) + + GC_AMIGA_PRINTSTATS - Gather some statistics during the execution of a + program, and prints out the info when the atexit-handler + is called. + + My reccomendation is to set all this flags, except GC_AMIGA_PRINTSTATS and + GC_AMIGA_ONLYFAST. + + If your program demands high response-time, you should + not define GC_AMIGA_GC, and possible allso define GC_AMIGA_ONLYFAST. + GC_AMIGA_RETRY does not seem to slow down much. + + Allso, when compiling up programs, and GC_AMIGA_FASTALLOC was not defined when + compilling gc, you can define GC_AMIGA_MAKINGLIB to avoid having these allocation- + functions wrapped. (see gc.h) + + Note that GC_realloc must not be called before any of + the other above mentioned allocating-functions have been called. (shouldn't be + any programs doing so either, I hope). + + Another note. The allocation-function is wrapped when defining + GC_AMIGA_FASTALLOC by letting the function go thru the new + GC_amiga_allocwrapper_do function-pointer (see gc.h). Means that + sending function-pointers, such as GC_malloc, GC_malloc_atomic, etc., + for later to be called like f.ex this, (*GC_malloc_functionpointer)(size), + will not wrap the function. This is normally not a big problem, unless + all allocation function is called like this, which will cause the + atexit un-allocating function never to be called. Then you either + have to manually add the atexit handler, or call the allocation- + functions function-pointer functions like this; + (*GC_amiga_allocwrapper_do)(size,GC_malloc_functionpointer). + There are probably better ways this problem could be handled, unfortunately, + I didn't find any without rewriting or replacing a lot of the GC-code, which + I really didn't want to. (Making new GC_malloc_* functions, and just + define f.ex GC_malloc as GC_amiga_malloc should allso work). + + + New amiga-spesific function: + + void GC_amiga_set_toany(void (*func)(void)); + + 'func' is a function that will be called right before gc has to change + allocation-method from MEMF_FAST to MEMF_ANY. Ie. when it is likely + it will return chip-mem. + + +2. A few small compiler-spesific additions to make it compile with SAS/C again. + +3. Updated and rewritten the smakefile, so that it works again and that + the "unnecesarry" 'SCOPTIONS' files could be removed. Allso included + the cord-smakefile stuff in the main smakefile, so that the cord smakefile + could be removed too. By writing smake -f Smakefile.smk, both gc.lib and + cord.lib will be made. + + + +STILL MISSING: + +Programs can not be started from workbench, at least not for SAS/C. (Martin +Tauchmanns note about that it now works with workbench is definitely wrong +when concerning SAS/C). I guess it works if you use the old "#if 0'ed"-code, +but I haven't tested it. I think the reason for MT to replace the +"#if 0'ed"-code was only because it was a bit to SAS/C-spesific. But I +don't know. An iconx-script solves this problem anyway. + + +BEWARE! + +-To run gctest, set the stack to around 200000 bytes first. +-SAS/C-spesific: cord will crash if you compile gc.lib with + either parm=reg or parm=both. (missing legal prototypes for + function-pointers someplace is the reason I guess.). + + +tested with software: Radium, http://www.stud.ifi.uio.no/~ksvalast/radium/ + +tested with hardware: MC68060 + + +-ksvalast@ifi.uio.no + + +=========================================================================== + Martin Tauchmann's notes (1-Apr-99) +=========================================================================== + +Works now, also with the GNU-C compiler V2.7.2.1. <ftp://ftp.unina.it/pub/amiga/geekgadgets/amiga/m68k/snapshots/971125/amiga-bin/> +Modify the `Makefile` +CC=cc $(ABI_FLAG) +to +CC=gcc $(ABI_FLAG) + +TECHNICAL NOTES + +- `GC_get_stack_base()`, `GC_register_data_segments()` works now with every + C compiler; also Workbench. + +- Removed AMIGA_SKIP_SEG, but the Code-Segment must not be scanned by GC. + + +PROBLEMS +- When the Linker, does`t merge all Code-Segments to an single one. LD of GCC + do it always. + +- With ixemul.library V47.3, when an GC program launched from another program + (example: `Make` or `if_mach M68K AMIGA gctest`), `GC_register_data_segments()` + found the Segment-List of the caller program. + Can be fixed, if the run-time initialization code (for C programs, usually *crt0*) + support `__data` and `__bss`. + +- PowerPC Amiga currently not supported. + +- Dynamic libraries (dyn_load.c) not supported. + + +TESTED WITH SOFTWARE + +`Optimized Oberon 2 C` (oo2c) <http://cognac.informatik.uni-kl.de/download/index.html> + + +TESTED WITH HARDWARE + +MC68030 + + +CONTACT + +Please, contact me at <martintauchmann@bigfoot.com>, when you change the +Amiga port. <http://martintauchmann.home.pages.de> + +=========================================================================== + Michel Schinz's notes +=========================================================================== +WHO DID WHAT + +The original Amiga port was made by Jesper Peterson. I (Michel Schinz) +modified it slightly to reflect the changes made in the new official +distributions, and to take advantage of the new SAS/C 6.x features. I also +created a makefile to compile the "cord" package (see the cord +subdirectory). + +TECHNICAL NOTES + +In addition to Jesper's notes, I have the following to say: + +- Starting with version 4.3, gctest checks to see if the code segment is + added to the root set or not, and complains if it is. Previous versions + of this Amiga port added the code segment to the root set, so I tried to + fix that. The only problem is that, as far as I know, it is impossible to + know which segments are code segments and which are data segments (there + are indeed solutions to this problem, like scanning the program on disk + or patch the LoadSeg functions, but they are rather complicated). The + solution I have chosen (see os_dep.c) is to test whether the program + counter is in the segment we are about to add to the root set, and if it + is, to skip the segment. The problems are that this solution is rather + awkward and that it works only for one code segment. This means that if + your program has more than one code segment, all of them but one will be + added to the root set. This isn't a big problem in fact, since the + collector will continue to work correctly, but it may be slower. + + Anyway, the code which decides whether to skip a segment or not can be + removed simply by not defining AMIGA_SKIP_SEG. But notice that if you do + so, gctest will complain (it will say that "GC_is_visible produced wrong + failure indication"). However, it may be useful if you happen to have + pointers stored in a code segment (you really shouldn't). + + If anyone has a good solution to the problem of finding, when a program + is loaded in memory, whether a segment is a code or a data segment, + please let me know. + +PROBLEMS + +If you have any problem with this version, please contact me at +schinz@alphanet.ch (but do *not* send long files, since we pay for +every mail!). + +=========================================================================== + Jesper Peterson's notes +=========================================================================== + +ADDITIONAL NOTES FOR AMIGA PORT + +These notes assume some familiarity with Amiga internals. + +WHY I PORTED TO THE AMIGA + +The sole reason why I made this port was as a first step in getting +the Sather(*) language on the Amiga. A port of this language will +be done as soon as the Sather 1.0 sources are made available to me. +Given this motivation, the garbage collection (GC) port is rather +minimal. + +(*) For information on Sather read the comp.lang.sather newsgroup. + +LIMITATIONS + +This port assumes that the startup code linked with target programs +is that supplied with SAS/C versions 6.0 or later. This allows +assumptions to be made about where to find the stack base pointer +and data segments when programs are run from WorkBench, as opposed +to running from the CLI. The compiler dependent code is all in the +GC_get_stack_base() and GC_register_data_segments() functions, but +may spread as I add Amiga specific features. + +Given that SAS/C was assumed, the port is set up to be built with +"smake" using the "SMakefile". Compiler options in "SCoptions" can +be set with "scopts" program. Both "smake" and "scopts" are part of +the SAS/C commercial development system. + +In keeping with the porting philosophy outlined above, this port +will not behave well with Amiga specific code. Especially not inter- +process comms via messages, and setting up public structures like +Intuition objects or anything else in the system lists. For the +time being the use of this library is limited to single threaded +ANSI/POSIX compliant or near-complient code. (ie. Stick to stdio +for now). Given this limitation there is currently no mechanism for +allocating "CHIP" or "PUBLIC" memory under the garbage collector. +I'll add this after giving it considerable thought. The major +problem is the entire physical address space may have to me scanned, +since there is no telling who we may have passed memory to. + +If you allocate your own stack in client code, you will have to +assign the pointer plus stack size to GC_stackbottom. + +The initial stack size of the target program can be compiled in by +setting the __stack symbol (see SAS documentaion). It can be over- +ridden from the CLI by running the AmigaDOS "stack" program, or from +the WorkBench by setting the stack size in the tool types window. + +SAS/C COMPILER OPTIONS (SCoptions) + +You may wish to check the "CPU" code option is appropriate for your +intended target system. + +Under no circumstances set the "StackExtend" code option in either +compiling the library or *ANY* client code. + +All benign compiler warnings have been suppressed. These mainly +involve lack of prototypes in the code, and dead assignments +detected by the optimizer. + +THE GOOD NEWS + +The library as it stands is compatible with the GigaMem commercial +virtual memory software, and probably similar PD software. + +The performance of "gctest" on an Amiga 2630 (68030 @ 25Mhz) +compares favourably with an HP9000 with similar architecture (a 325 +with a 68030 I think). + +----------------------------------------------------------------------- + +The Amiga port has been brought to you by: + +Jesper Peterson. + +jep@mtiame.mtia.oz.au (preferred, but 1 week turnaround) +jep@orca1.vic.design.telecom.au (that's orca<one>, 1 day turnaround) + +At least one of these addresses should be around for a while, even +though I don't work for either of the companies involved. + diff --git a/gc/doc/README.autoconf b/gc/doc/README.autoconf new file mode 100644 index 0000000..53fcf5a --- /dev/null +++ b/gc/doc/README.autoconf @@ -0,0 +1,59 @@ +As of GC6.0alpha8, we attempt to support GNU-style builds based on automake, +autoconf and libtool. This is based almost entirely on Tom Tromey's work +with gcj. + +To build and install libraries use + +configure; make; make install + +The advantages of this process are: + +1) It should eventually do a better job of automatically determining the +right compiler to use, etc. It probably already does in some cases. + +2) It tries to automatically set a good set of default GC parameters for +the platform (e.g. thread support). It provides an easier way to configure +some of the others. + +3) It integrates better with other projects using a GNU-style build process. + +4) It builds both dynamic and static libraries. + +The known disadvantages are: + +1) The build scripts are much more complex and harder to debug (though largely +standard). I don't understand them all, and there's probably lots of redundant +stuff. + +2) It probably doesn't work on all Un*x-like platforms yet. It probably will +never work on the rest. + +3) The scripts are not yet complete. Some of the standard GNU targets don't +yet work. (Corrections/additions are very welcome.) + +The distribution should contain all files needed to run "configure" and "make", +as well as the sources needed to regenerate the derived files. (If I missed +some, please let me know.) + +Note that the distribution comes with a "Makefile" which will be overwritten +by "configure" with one that is not at all equiavelent to the original. The +distribution contains a copy of the original "Makefile" in "Makefile.direct". + +Important options to configure: + + --prefix=PREFIX install architecture-independent files in PREFIX + [/usr/local] + --exec-prefix=EPREFIX install architecture-dependent files in EPREFIX + [same as prefix] + --enable-threads=TYPE choose threading package + --enable-parallel-mark parallelize marking and free list construction + --enable-full-debug include full support for pointer backtracing etc. + +Unless --prefix is set (or --exec-prefix or one of the more obscure options), +make install will install libgc.a and libgc.so in /usr/local/bin, which +would typically require the "make install" to be run as root. + +Most commonly --enable-threads=posix or will be needed. --enable-parallel-mark +is recommended for multiprocessors if it is supported on the platform. + + diff --git a/gc/doc/README.changes b/gc/doc/README.changes new file mode 100644 index 0000000..c018c8b --- /dev/null +++ b/gc/doc/README.changes @@ -0,0 +1,1408 @@ +This is a rough history of garbage collector bugs and versions. + +This has been maintained with varying diligence over the years. + +I made an attempt to include recent contributors here. I apologize for any +omissions. + +------------------------- + + 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 changing 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. + Thread support is currently still flakey. + - 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. + +Since 5.0 alpha4 + - GC_malloc_explicitly_typed and friends sometimes failed to + initialize first word. + - Added allocation routines and support in the marker for mark descriptors + in a type structure referenced by the first word of an object. This was + introduced to support gcj, but hopefully in a way that makes it + generically useful. + - Added GC_requested_heapsize, and inhibited collections in nonincremental + mode if the actual used heap size is less than what was explicitly + requested. + - The Solaris pthreads version of GC_pthread_create didn't handle a NULL + attribute pointer. Solaris thread support used the wrong default thread + stack size. (Thanks to Melissa O'Neill for the patch.) + - Changed PUSH_CONTENTS macro to no longer modify first parameter. + This usually doesn't matter, but it was certainly an accident waiting + to happen ... + - Added GC_register_finalizer_no_order and friends to gc.h. They're + needed by Java implementations. + - Integrated a fix for a win32 deadlock resulting from clock() calling + malloc. (Thanks to Chris Dodd.) + - Integrated Hiroshi Kawashima's port to Linux/MIPS. This was designed + for a handheld platform, and may or may not be sufficient for other + machines. + - Fixed a va_arg problem with the %c specifier in cordprnt.c. It appears + that this was always broken, but recent versions of gcc are the first to + report the (statically detectable) bug. + - Added an attempt at a more general solution to dlopen races/deadlocks. + GC_dlopen now temporarily disables collection. Still not ideal, but ... + - Added -DUSE_I686_PREFETCH, -DUSE_3DNOW_PREFETCH, and support for IA64 + prefetch instructions. May improve performance measurably, but I'm not + sure the code will run correctly on processors that don't support the + instruction. Won't build except with very recent gcc. + - Added caching for header lookups in the marker. This seems to result + in a barely measurable performance gain. Added support for interleaved + lookups of two pointers, but unconfigured that since the performance + gain is currently near zero, and it adds to code size. + - Changed Linux DATA_START definition to check both data_start and + __data_start, since nothing else seems to be portable. + - Added -DUSE_LD_WRAP to optionally take advantage of the GNU ld function + wrapping mechanism. Probably currently useful only on Linux. + - Moved some variables for the scratch allocator into GC_arrays, on + Martin Hirzel's suggestion. + - Fixed a win32 threads bug that caused the collector to not look for + interior pointers from one of the thread stacks without + ALL_INTERIOR_POINTERS. (Thanks to Jeff Sturm.) + - Added Mingw32 support. (Thanks again to Jeff Sturm for the patch.) + - Changed the alpha port to use the generic register scanning code instead + of alpha_mach_dep.s. Alpha_mach_dep.s doesn't look for pointers in fp + registers, but gcc sometimes spills pointers there. (Thanks to Manuel + Serrano for helping me debug this by email.) Changed the IA64 code to + do something similar for similar reasons. + +[5.0alpha5 doesn't really exist, but it may have escaped.] + +Since 5.0alpha6: + - -DREDIRECT_MALLOC was broken in alpha6. Fixed. + - Cleaned up gc_ccp.h slightly, thus also causing the HP C++ compiler to + accept it. + - Removed accidental reference to dbg_mlc.c, which caused dbg_mlc.o to be + linked into every executable. + - Added PREFETCH to bitmap marker. Changed it to use the header cache. + - GC_push_marked sometimes pushed one object too many, resulting in a + segmentation fault in GC_mark_from_mark_stack. This was probably an old + bug. It finally showed up in gctest on win32. + - Gc_priv.h erroneously #defined GC_incremental to be TRUE instead of FALSE + when SMALL_CONFIG was defined. This was no doubt a major performance bug for + the default win32 configuration. + - Removed -DSMALL_CONFIG from NT_MAKEFILE. It seemed like an anchronism now + that the average PC has 64MB or so. + - Integrated Bryce McKinley's patches for linux threads and dynamic loading + from the libgcj tree. Turned on dynamic loading support for Linux/PPC. + - Changed the stack finding code to use environ on HP/UX. (Thanks + to Gustavo Rodriguez-Rivera for the suggestion.) This should probably + be done on other platforms, too. Since I can't test those, that'll + wait until after 5.0. + +Since 5.0alpha7: + - Fixed threadlibs.c for linux threads. -DUSE_LD_WRAP was broken and + -ldl was omitted. Fixed Linux stack finding code to handle + -DUSE_LD_WRAP correctly. + - Added MSWIN32 exception handler around marker, so that the collector + can recover from root segments that are unmapped during the collection. + This caused occasional failures under Windows 98, and may also be + an issue under Windows NT/2000. + +Since 5.0 + - Fixed a gc.h header bug which showed up under Irix. (Thanks to + Dan Sullivan.) + - Fixed a typo in GC_double_descr in typd_mlc.c. + This probably could result in objects described by array descriptors not + getting traced correctly. (Thanks to Ben Hutchings for pointing this out.) + - The block nearly full tests in reclaim.c were not correct for 64 bit + environments. This could result in unnecessary heap growth under unlikely + conditions. + +Since 5.1 + - dyn_load.c declared GC_scratch_last_end_ptr as an extern even if it + was defined as a macro. This prevented the collector from building on + Irix. + - We quietly assumed that indirect mark descriptors were never 0. + Our own typed allocation interface violated that. This could result + in segmentation faults in the marker with typed allocation. + - Fixed a _DUSE_MUNMAP bug in the heap block allocation code. + (Thanks to Ben Hutchings for the patch.) + - Taught the collector about VC++ handling array operator new. + (Thanks again to Ben Hutchings for the patch.) + - The two copies of gc_hdrs.h had diverged. Made one a link to the other + again. + +Since 5.2 (A few 5.2 patches are not in 6.0alpha1) + - Fixed _end declaration for OSF1. + - There were lots of spurious leak reports in leak detection mode, caused + by the fact that some pages were not being swept, and hence unmarked + objects weren't making it onto free lists. (This bug dated back to 5.0.) + - Fixed a typo in the liblinuxgc.so Makefile rule. + - Added the GetExitCodeThread to Win32 GC_stop_world to (mostly) work + around a Windows 95 GetOpenFileName problem. (Thanks to Jacob Navia.) + +Since 5.3 + - Fixed a typo that prevented compilation with -DUSE_3DNOW_PREFETCH. + (Thanks to Shawn Wagner for actually testing this.) + - Fixed GC_is_thread_stack in solaris_threads.c. It forgot to return a value + in the common case. I wonder why nobody noticed? + - Fixed another silly syntax problem in GC_double_descr. (Thanks to + Fergus Henderson for finding it.) + - Fixed a GC_gcj_malloc bug: It tended to release the allocator lock twice. + +Since 5.4 (A few 5.3 patches are not in 6.0alpha2) + - Added HP/PA prefetch support. + - Added -DDBG_HDRS_ALL and -DSHORT_DBG_HDRS to reduce the cost and improve + the reliability of generating pointer backtrace information, e.g. in + the Bigloo environment. + - Added parallel marking support (-DPARALLEL_MARK). This currently + works only under IA32 and IA64 Linux, but it shouldn't be hard to adapt + to other platforms. This is intended to be a lighter-weight (less + new code, probably not as scalable) solution than the work by Toshio Endo + et al, at the University of Tokyo. A number of their ideas were + reused, though the code wasn't, and the underlying data structure + is significantly different. In particular, we keep the global mark + stack as a single shared data structure, but most of the work is done + on smaller thread-local mark stacks. + - Changed GC_malloc_many to be cheaper, and to require less mutual exclusion + with -DPARALLEL_MARK. + - Added full support for thread local allocation under Linux + (-DTHREAD_LOCAL_ALLOC). This is a thin veneer on GC_malloc_many, and + should be easily portable to other platforms, especially those that + support pthreads. + - CLEAR_DOUBLE was not always getting invoked when it should have been. + - GC_gcj_malloc and friends used different out of memory handling than + everything else, probably because I forgot about one when I implemented + the other. They now both call GC_oom_fn(), not GC_oom_action(). + - Integrated Jakub Jelinek's fixes for Linux/SPARC. + - Moved GC_objfreelist, GC_aobjfreelist, and GC_words_allocd out of + GC_arrays, and separately registered the first two as excluded roots. + This makes code compiled with gc_inl.h less dependent on the + collector version. (It would be nice to remove the inclusion of + gc_priv.h by gc_inl.h completely, but we're not there yet. The + locking definitions in gc_priv.h are still referenced.) + This change was later coniditoned on SEPARATE_GLOBALS, which + is not defined by default, since it involves a performance hit. + - Register GC_obj_kinds separately as an excluded root region. The + attempt to register it with GC_arrays was usually failing. (This wasn't + serious, but seemed to generate some confusion.) + - Moved backptr.h to gc_backptr.h. + +Since 6.0alpha1 + - Added USE_MARK_BYTES to reduce the need for compare-and-swap on platforms + for which that's expensive. + - Fixed a locking bug ib GC_gcj_malloc and some locking assertion problems. + - Added a missing volatile to OR_WORD and renamed the parameter to + GC_compare_and_swap so it's not a C++ reserved word. (Thanks to + Toshio Endo for pointing out both of those.) + - Changed Linux dynamic library registration code to look at /proc/self/maps + instead of the rld data structures when REDIRECT_MALLOC is defined. + Otherwise some of the rld data data structures may be prematurely garbage + collected. (Thanks to Eric Benson for helping to track this down.) + - Fixed USE_LD_WRAP a bit more, so it should now work without threads. + - Renamed XXX_THREADS macros to GC_XXX_THREADS for namespace correctness. + Tomporarily added some backward compatibility definitions. Renamed + USE_LD_WRAP to GC_USE_LD_WRAP. + - Many MACOSX POWERPC changes, some additions to the gctest output, and + a few minor generic bug fixes. (Thanks to Dietmar Planitzer.) + +Since 6.0 alpha2 + - Fixed the /proc/self/maps code to not seek, since that apparently is not + reliable across all interesting kernels. + - Fixed some compilation problems in the absence of PARALLEL_MARK + (introduced in alpha2). + - Fixed an algorithmic problem with PARALLEL_MARK. If work needs to + be given back to the main mark "stack", the BOTTOM entries of the local + stack should be given away, not the top ones. This has substantial + performance impact, especially for > 2 processors, from what I can tell. + - Extracted gc_lock.h from gc_priv.h. This should eventually make it a + bit easier to avoid including gc_priv.h in clients. + - Moved all include files to include/ and removed duplicate links to the + same file. The old scheme was a bad idea because it was too easy to get the + copies out of sync, and many systems don't support hard links. + Unfortunately, it's likely that I broke some of the non-Unix Makefiles in + the process, although I tried to update them appropriately. + - Removed the partial support for a copied nursery. It's not clear that + this would be a tremendous win, since we don't consistently lose to + generational copying collectors. And it would significantly complicate + many things. May be reintroduced if/when it really turns out to win. + - Removed references to IRIX_JDK_THREADS, since I believe there never + were and never will be any clients. + - Added some code to linux_threads.c to possibly support HPUX threads + using the Linux code. Unfortunately, it doesn't work yet, and is + currently disabled. + - Added support under Linux/X86 for saving the call chain, both in (debug) + objects for client debugging, and in GC_arrays._last_stack for GC + debugging. This was previously supported only under Solaris. It is + not enabled by default under X86, since it requires that code be compiled + to explicitly dave frame pointers on the call stack. (With gcc this + currently happens by default, but is often turned off explicitly.) + To turn it on, define SAVE_CALL_CHAIN. + +Since 6.0 alpha3 + - Moved up the detection of mostly full blocks to the initiatiation of the + sweep phase. This eliminates some lock conention in the PARALLEL_MARK case, + as multiple threads try to look at mostly full blocks concurrently. + - Restored the code in GC_malloc_many that grabs a prefix of the global + free list. This avoids the case in which every GC_malloc_many call + tries and fails to allocate a new heap block, and the returns a single + object from the global free list. + - Some minor fixes in new_hblk.c. (Attempted to build free lists in order + of increasing addresses instead of decreasing addresses for cache performance + reasons. But this seems to be only a very minor gain with -DEAGER_SWEEP, + and a loss in other cases. So the change was backed out.) + - Fixed some of the documentation. (Thanks in large part to Fergus + Henderson.) + - Fixed the Linux USE_PROC_FOR_LIBRARIES code to deal with apps that perform + large numbers of mmaps. (Thanks to Eric Benson.) Also fixed that code to + deal with short reads. + - Added GC_get_total_bytes(). + - Fixed leak detection mode to avoid spurious messages under linuxthreads. + (This should also now be easy for the other supported threads packages. + But the code is tricky enough that I'm hesitant to do it without being able + to test. Everything allocated in the GC thread support itself should be + explicitly deallocated.) + - Made it possible (with luck) to redirect malloc to GC_local_malloc. + +Since 6.0 alpha4 + - Changed the definition of GC_pause in linux_threads.c to use a volatile + asm. Some versions of gcc apparently optimize away writes to local volatile + variables. This caused poor locking behaviour starting at about + 4 processors. + - Added GC_start_blocking(), GC_end_blocking() calls and wrapper for sleep + to linux_threads.c. + The first two calls could be used to generally avoid sending GC signals to + blocked threads, avoiding both premature wakeups and unnecessary overhead. + - Fixed a serious bug in thread-local allocation. At thread termination, + GC_free could get called on small integers. Changed the code for thread + termination to more efficiently return left-over free-lists. + - Integrated Kjetil Matheussen's BeOS support. + - Rearranged the directory structure to create the doc and tests + subdirectories. + - Sort of integrated Eric Benson's patch for OSF1. This provided basic + OSF1 thread support by suitably extending hpux_irix_threads.c. Based + on earlier email conversations with David Butenhof, I suspect that it + will be more reliable in the long run to base this on linux_threads.c + instead. Thus I attempted to patch up linux_threads.c based on Eric's code. + The result is almost certainly broken, but hopefully close enough that + someone with access to a machine can pick it up. + - Integrated lots of minor changes from the NetBSD distribution. (These + were supplied by David Brownlee. I'm not sure about the original + authors.) + - Hacked a bit more on the HP/UX thread-support in linux_threads.c. It + now appears to work in the absence of incremental collection. Renamed + hpux_irix_threads.c back to irix_threads.c, and removed the attempt to + support HPUX there. + - Changed gc.h to define _REENTRANT in cases in which it should already + have been defined. It is still safer to also define it on the command + line. + +Since 6.0alpha5: + - Changed the definition of DATASTART on ALPHA and IA64, where data_start + and __data_start are not defined by earlier versions of glibc. This might + need to be fixed on other platforms as well. + - Changed the way the stack base and backing store base are found on IA64. + This should now remain reliable on future kernels. But since it relies + on /proc, it will no longer work in the simulated NUE environment. + - Made the call to random() in dbg_mlc.c with -DKEEP_BACK_PTRS dependent + on the OS. On non-Unix systems, rand() should be used instead. Handled + small RAND_MAX. (Thanks to Peter Ross for pointing this out.) + - Fixed the cord make rules to create the cord subdirectory, if necessary. + (Thanks to Doug Moen.) + - Changed fo_object_size calculation in finalize.c. Turned finalization + of nonheap object into a no-op. Removed anachronism from GC_size() + implementation. + - Changed GC_push_dirty call in solaris_threads.c to GC_push_selected. + It was missed in a previous renaming. (Thanks to Vladimir Tsichevski + for pointing this out.) + - Arranged to not not mask SIGABRT in linux_threads.c. (Thanks to Bryce + McKinlay.) + - Added GC_no_dls hook for applications that want to register their own + roots. + - Integrated Kjetil Matheussen's Amiga changes. + - Added FREEBSD_STACKBOTTOM. Changed the X86/FreeBSD port to use it. + (Thanks to Matthew Flatt.) + - Added pthread_detach interception for platforms supported by linux_threads.c + and irix_threads.c. Should also be added for Solaris? + - Changed the USE_MMAP code to check for the case in which we got the + high end of the address space, i.e. mem_ptr + mem_sz == 0. It appears + that this can happen under Solaris 7. It seems to be allowed by what + I would claim is an oversight in the mmap specification. (Thanks to Toshio + Endo for pointing out the problem.) + - Cleanup of linux_threads.c. Some code was originally cloned from + irix_threads.c and now unnecessary. Some comments were obviously wrong. + - (Mostly) fixed a longstanding problem with setting of dirty bits from + a signal handler. In the presence of threads, dirty bits could get lost, + since the etting of a bit in the bit vector was not atomic with respect + to other updates. The fix is 100% correct only for platforms for which + GC_test_and_set is defined. The goal is to make that all platforms with + thread support. Matters only if incremental GC and threads are both + enabled. + - made GC_all_interior_pointers (a.k.a. ALL_INTERIOR_POINTERS) an + initialization time, instead of build-time option. This is a + nontrivial, high risk change. It should slow down the code measurably + only if MERGE_SIZES is not defined, which is a very nonstandard + configuration. + - Added doc/README.environment, and implemented what it describes. This + allows a number of additional configuration options to be set through + the environment. It documents a few previously undocumented options. + - Integrated Eric Benson's leak testing improvements. + - Removed the option to throw away the beginning of each page (DISCARD_WORDS). + This became less and less useful as processors enforce stricter alignment. + And it hadn't been tested in ages, and was thus probably broken anyway. + +Since 6.0alpha6: + - Added GC_finalizer_notifier. Fixed GC_finalize_on_demand. (The variable + actually wasn't being tested at the right points. The build-time flag + was.) + - Added Tom Tromey's S390 Linux patch. + - Added code to push GC_finalize_now in GC_push_finalizer_structures. + (Thanks to Matthew Flatt.) + - Added GC_push_gc_structures() to push all GC internal roots. + - Integrated some FreeBSD changes from Matthew Flatt. + - It looks like USRSTACK is not always correctly defined under Solaris. + Hacked gcconfig.h to attempt to work around the problem. The result + is not well tested. (Thanks again to Matthew Flatt for pointing this + out. The gross hack is mine. - HB) + - Added Ji-Yong Chung's win32 threads and C++ fixes. + - Arranged for hpux_test_and_clear.s to no longer be needed or built. + It was causing build problems with gas, and it's not clear this is + better than the pthreads alternative on this platform. + - Some MINGW32 fixes from Hubert Garavel. + - Added Initial Hitachi SH4 port from Kaz Kojima. + - Ported thread-local allocation and parallel mark code to HP/UX on PA_RISC. + - Made include/gc_mark.h more public and separated out the really private + pieces. This is probably still not quite sufficient for clients that + want to supply their own kind of type information. But it's a start. + This involved lots of identifier renaming to make it namespace clean. + - Added GC_dont_precollect for clients that need complete control over + the root set. + - GC_is_visible didn't do the right thing with gcj objects. (Not that + many people are likely to care, but ...) + - Don't redefine read with GC_USE_LD_WRAP. + - Initial port to LINUX/HP_PA. Incremental collection and threads are not + yet supported. (Incremental collection should work if you have the + right kernel. Threads may work with a sufficiently patched pthread + library.) + - Changed gcconfig.h to recognize __i386__ as an alternative to i386 in + many places. (Thanks to Benjamin Lerman.) + - Made win32_threads.c more tolerant of detaching a thread that it didn't + know about. (Thanks to Paul Nash.) + - Added Makefile.am and configure.in from gcc to the distribution, with + minimal changes. For the moment, those are just placeholders. In the + future, we're planning to switch to a GNU-style build environment for + Un*x-like systems, though the old Makefile will remain as a backup. + - Turned off STUBBORN_ALLOC by default, and added it back as a Makefile + option. + - Redistributed some functions between malloc.c and mallocx.c, so that + simple statically linked apps no longer pull in mallocx.o. + - Changed large object allocation to clear the first and last few words + of each block before releassing the lock. Otherwise the marker could see + objects with nonsensical type descriptors. + - Fixed a couple of subtle problems that could result in not recognizing + interior pointers from the stack. (I believe these were introduced + in 6.0alpha6.) + - GC_debug_free_inner called GC_free, which tried to reacquire the + allocator lock, and hence deadlocked. (DBG_HDRS_ALL probably never worked + with threads?) + - Fixed several problems with back traces. Accidental references to a free + list could cause the free list pointer to be overwritten by a back pointer. + There seemed to be some problems with the encoding of root and finalizer + references. + +Since 6.0alpha7: + - Changed GC_debug_malloc_replacement and GC_debug_realloc_replacement + so that they compile under Irix. (Thanks to Dave Love.) + - Updated powerpc_macosx_mach_dep.s so that it works if the collector + is in a dynamic library. (Thanks to Andrew Begel.) + - Transformed README.debugging into debugging.html, updating and + expanding it in the process. Added gcdescr.html and tree.html + from the web site to the GC distribution. + - Fixed several problems related to PRINT_BLACK_LIST. This involved + restructuring some of the marker macros. + - Fixed some problems with the sizing of objects with debug information. + Finalization was broken KEEP_BACK_PTRS or PRINT_BLACK_LIST. Reduced the + object size with SHORT_DEBUG_HDRS by another word. + - The "Needed to allocate blacklisted ..." warning had inadvertently + been turned off by default, due to a buggy test in allchblk.c. Turned + it back on. + - Removed the marker macros to deal with 2 pointers in interleaved fashion. + They were messy and the performance improvement seemed minimal. We'll + leave such scheduling issues to the compiler. + - Changed Linux/PowerPC test to also check for __powerpc__ in response + to a discussion on the gcc mailing list. + - On Matthew Flatt's suggestion removed the "static" from the jmp_buf + declaration in GC_generic_push_regs. This was causing problems in + systems that register all of their own roots. It looks far more correct + to me without the "static" anyway. + - Fixed several problems with thread local allocation of pointerfree or + typed objects. The collector was reclaiming thread-local free lists, since + it wasn't following the link fields. + - There was apparently a long-standing race condition related to multithreaded + incremental collection. A collection could be started and a thread stopped + between the memory unprotect system call and the setting of the + corresponding dirt bit. I believe this did not affect Solaris or PCR, which + use a different dirty-bit implementation. Fixed this by installing + signal handlers with sigaction instead of signal, and disabling the thread + suspend signal while in the write-protect handler. (It is unclear + whether this scenario ever actually occurred. I found it while tracking + down the following:) + - Incremental collection did not cooperate correctly with the PARALLEL_MARK + implementation of GC_malloc_many or the local_malloc primitves. It still + doesn't work well, but it shouldn't lose memory anymore. + - Integrated some changes from the gcc source tree that I had previously + missed. (Thanks to Bryce McKinley for the reminder/diff.) + - Added Makefile.direct as a copy of the default Makefile, which would + normally be overwritten if configure is run. + - Changed the gc.tar target in Makefile.direct to embed the version number + in the gc directory name. This will affect future tar file distributions. + - Changed the Irix dynamic library finding code to no longer try to + eliminate writable text segments under Irix6.x, since that is probably no + longer necessary, and can apparently be unsafe on occasion. (Thanks to + Shiro Kawai for pointing this out.) + - GC_cleanup with GC_DEBUG enabled passed a real object base address to + GC_debug_register_finalizer_ignore_self, which expected a pointer past the + debug header. Call GC_register_finalizer_ignore_self instead, even with + debugging enabled. (Thanks to Jean-Daniel Fekete for catching this.) + - The collector didn't build with call chain saving enabled but NARGS=0. + (Thanks to Maarten Thibaut.) + - Fixed up the GNU-style build files enough so that they work in some + obvious cases. + - Added initial port to Digital Mars compiler for win32. (Thanks to Walter + Bright.) + +Since 6.0alpha8: + - added README.macros. + - Made gc.mak a symbolic link to work around winzip's tendency to ignore + hard links. + - Simplified the setting of NEED_FIND_LIMIT in os_dep.c, possibly breaking + it on untested platforms. + - Integrated initial GNU HURD port. (Thanks to Chris Lingard and Igor + Khavkine.) + - A few more fixes for Digital Mars compiler. + - Fixed gcc version recognition. Renamed OPERATOR_NEW_ARRAY to + GC_OPERATOR_NEW_ARRAY. Changed GC_OPERATOR_NEW_ARRAY to be the default. + It can be overridden with -DGC_NO_OPERATOR_NEW_ARRAY. (Thanks to + Cesar Eduardo Barros.) + - Changed the byte size to free-list mapping in thread local allocation + so that size 0 allocations are handled correctly. + - Fixed Linux/MIPS stackbottom for new toolchain. (Thanks to Ryan Murray.) + - Changed finalization registration to invoke GC_oom_fn when it runs out + of memory. + - Removed lvalue cast in finalize.c. This caused some debug configurations + not to build with some non-gcc compilers. + +Since 6.0alpha9: + - Two more bug fixes for KEEP_BACK_PTRS and DBG_HDRS_ALL. + - Fixed a stack clearing problem that resulted in SIGILL with a + misaligned stack pointer for multithreaded SPARC builds. + - Integrated another HURD patch (thanks to Igor Khavkine). + + +To do: + - There seem to be outstanding issues on Solaris/X86, possibly with + finding the data segment starting address. Information/patches would + ne appreciated. + - New_gc_alloc.h is apparently no longer compatible with the latest C++ + standard library in gcc3.0. (This isn't technically a bug, since it only + claimed compatibility with the SGI STL. But we may need a new C++ STL + allocator interface.) + - 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. + - Incremental collector should handle large objects better. Currently, + it looks like the whole object is treated as dirty if any part of it + is. + - Cord/cordprnt.c doesn't build on a few platforms (notably PowerPC), since + we make some unwarranted assumptions about how varargs are handled. This + currently makes the cord-aware versions of printf unusable on some platforms. + Fixing this is unfortunately not trivial. diff --git a/gc/doc/README.contributors b/gc/doc/README.contributors new file mode 100644 index 0000000..fd5c95f --- /dev/null +++ b/gc/doc/README.contributors @@ -0,0 +1,57 @@ +This is an attempt to acknowledge early contributions to the garbage +collector. Later contributions should instead be mentioned in +README.changes. + +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. + +The garbage collector originated as part of the run-time system for +the Russell programming language implementation. The first version of the +garbage collector was written primarily by Al Demers. It was then refined +and mostly rewritten, primarily by Hans-J. Boehm, at Cornell U., +the University of Washington, Rice University (where it was first used for +C and assembly code), Xerox PARC, SGI, and HP Labs. However, significant +contributions have also been made by many others. + +Some other contributors: + +More recent contributors are mentioned in the modification history in +README.changes. My apologies for any omissions. + +The SPARC specific code was originally contributed by Mark Weiser. +The Encore Multimax modifications were supplied by +Kevin Kenny (kenny@m.cs.uiuc.edu). The adaptation to the IBM PC/RT is largely +due to Vernon Lee, on machines made available to Rice by IBM. +Much of the HP specific code and a number of good suggestions for improving the +generic code are due to Walter Underwood. +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.) + diff --git a/gc/doc/README.cords b/gc/doc/README.cords new file mode 100644 index 0000000..3485e01 --- /dev/null +++ b/gc/doc/README.cords @@ -0,0 +1,53 @@ +Copyright (c) 1993-1994 by Xerox Corporation. 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. + +Please send bug reports to Hans-J. Boehm (Hans_Boehm@hp.com or +boehm@acm.org). + +This is a string packages that uses a tree-based representation. +See cord.h for a description of the functions provided. Ec.h describes +"extensible cords", which are essentially output streams that write +to a cord. These allow for efficient construction of cords without +requiring a bound on the size of a cord. + +More details on the data structure can be found in + +Boehm, Atkinson, and Plass, "Ropes: An Alternative to Strings", +Software Practice and Experience 25, 12, December 1995, pp. 1315-1330. + +A fundamentally similar "rope" data structure is also part of SGI's standard +template library implementation, and its descendents, which include the +GNU C++ library. That uses reference counting by default. +There is a short description of that data structure at +http://reality.sgi.com/boehm/ropeimpl.html . (The more official location +http://www.sgi.com/tech/stl/ropeimpl.html is missing a figure.) + +All of these are descendents of the "ropes" in Xerox Cedar. + +de.c is a very dumb text editor that illustrates the use of cords. +It maintains a list of file versions. Each version is simply a +cord representing the file contents. Nonetheless, standard +editing operations are efficient, even on very large files. +(Its 3 line "user manual" can be obtained by invoking it without +arguments. Note that ^R^N and ^R^P move the cursor by +almost a screen. It does not understand tabs, which will show +up as highlighred "I"s. Use the UNIX "expand" program first.) +To build the editor, type "make cord/de" in the gc directory. + +This package assumes an ANSI C compiler such as gcc. It will +not compile with an old-style K&R compiler. + +Note that CORD_printf iand friends use C functions with variable numbers +of arguments in non-standard-conforming ways. This code is known to +break on some platforms, notably PowerPC. It should be possible to +build the remainder of the library (everything but cordprnt.c) on +any platform that supports the collector. + diff --git a/gc/doc/README.dj b/gc/doc/README.dj new file mode 100644 index 0000000..613bc42 --- /dev/null +++ b/gc/doc/README.dj @@ -0,0 +1,12 @@ +[Original version supplied by Xiaokun Zhu <xiaokun@aero.gla.ac.uk>] +[This version came mostly from Gary Leavens. ] + +Look first at Makefile.dj, and possibly change the definitions of +RM and MV if you don't have rm and mv installed. +Then use Makefile.dj to compile the garbage collector. +For example, you can do: + + make -f Makefile.dj test + +All the tests should work fine. + diff --git a/gc/doc/README.environment b/gc/doc/README.environment new file mode 100644 index 0000000..5760342 --- /dev/null +++ b/gc/doc/README.environment @@ -0,0 +1,44 @@ +The garbage collector looks at a number of environment variables which are +the used to affect its operation. These are examined only on Un*x-like +platforms. + +GC_INITIAL_HEAP_SIZE=<bytes> - Initial heap size in bytes. May speed up + process start-up. + +GC_LOOP_ON_ABORT - Causes the collector abort routine to enter a tight loop. + This may make it easier to debug, such a process, especially + for multithreaded platforms that don't produce usable core + files, or if a core file would be too large. On some + platforms, this also causes SIGSEGV to be caught and + result in an infinite loop in a handler, allowing + similar debugging techniques. + +GC_PRINT_STATS - Turn on as much logging as is easily feasible without + adding signifcant runtime overhead. Doesn't work if + the collector is built with SMALL_CONFIG. Overridden + by setting GC_quiet. On by default if the collector + was built without -DSILENT. + +GC_PRINT_ADDRESS_MAP - Linux only. Dump /proc/self/maps, i.e. various address + maps for the process, to stderr on every GC. Useful for + mapping root addresses to source for deciphering leak + reports. + +GC_NPROCS=<n> - Linux w/threads only. Explicitly sets the number of processors + that the GC should expect to use. Note that setting this to 1 + when multiple processors are available will preserve + correctness, but may lead to really horrible performance. + +GC_NO_BLACKLIST_WARNING - Prevents the collector from issuing + "Needed to allocate blacklisted block at ..." warnings. + +The following turn on runtime flags that are also program settable. Checked +only during initialization. We expect that they will usually be set through +other means, but this may help with debugging and testing: + +GC_FIND_LEAK - Turns on GC_find_leak and thus leak detection. + +GC_ALL_INTERIOR_POINTERS - Turns on GC_all_interior_pointers and thus interior + pointer recognition. + +GC_DONT_GC - Turns off garbage collection. Use cautiously. diff --git a/gc/doc/README.hp b/gc/doc/README.hp new file mode 100644 index 0000000..caa8bdd --- /dev/null +++ b/gc/doc/README.hp @@ -0,0 +1,18 @@ +Dynamic loading support requires that executables be linked with -ldld. +The alternative is to build the collector without defining DYNAMIC_LOADING +in gcconfig.h and ensuring that all garbage collectable objects are +accessible without considering statically allocated variables in dynamic +libraries. + +The collector should compile with either plain cc or cc -Ae. Cc -Aa +fails to define _HPUX_SOURCE and thus will not configure the collector +correctly. + +Incremental collection support was reccently added, and should now work. + +In spite of past claims, pthread support under HP/UX 11 should now work. +Define GC_HPUX_THREADS for the build. Incremental collection still does not +work in combination with it. + +The stack finding code can be confused by putenv calls before collector +initialization. Call GC_malloc or GC_init before any putenv calls. diff --git a/gc/doc/README.linux b/gc/doc/README.linux new file mode 100644 index 0000000..efd0a26 --- /dev/null +++ b/gc/doc/README.linux @@ -0,0 +1,135 @@ +See README.alpha for Linux on DEC AXP info. + +This file applies mostly to Linux/Intel IA32. Ports to Linux on an M68K +and PowerPC are also integrated. They should behave similarly, except that +the PowerPC port lacks incremental GC support, and it is unknown to what +extent the Linux threads code is functional. See below for M68K specific +notes. + +Incremental GC is supported on Intel IA32 and M68K. + +Dynamic libraries are supported on an ELF system. A static executable +should be linked with the gcc option "-Wl,-defsym,_DYNAMIC=0". + +The collector appears to work with Linux threads. We have seen +intermittent hangs in sem_wait. So far we have been unable to reproduce +these unless the process was being debugged or traced. Thus it's +possible that the only real issue is that the debugger loses +signals on rare occasions. + +The garbage collector uses SIGPWR and SIGXCPU if it is used with +Linux threads. These should not be touched by the client program. + +To use threads, you need to abide by the following requirements: + +1) You need to use LinuxThreads (which are included in libc6). + + The collector relies on some implementation details of the LinuxThreads + package. It is unlikely that this code will work on other + pthread implementations (in particular it will *not* work with + MIT pthreads). + +2) You must compile the collector with -DGC_LINUX_THREADS and -D_REENTRANT + specified in the Makefile. + +3a) Every file that makes thread calls should define GC_LINUX_THREADS and + _REENTRANT and then include gc.h. Gc.h redefines some of the + pthread primitives as macros which also provide the collector with + information it requires. + +3b) A new alternative to (3a) is to build the collector and compile GC clients + with -DGC_USE_LD_WRAP, and to link the final program with + + (for ld) --wrap read --wrap dlopen --wrap pthread_create \ + --wrap pthread_join --wrap pthread_detach \ + --wrap pthread_sigmask --wrap sleep + + (for gcc) -Wl,--wrap -Wl,read -Wl,--wrap -Wl,dlopen -Wl,--wrap \ + -Wl,pthread_create -Wl,--wrap -Wl,pthread_join -Wl,--wrap \ + -Wl,pthread_detach -Wl,--wrap -Wl,pthread_sigmask \ + -Wl,--wrap -Wl,sleep + + In any case, _REENTRANT should be defined during compilation. + +4) Dlopen() disables collection during its execution. (It can't run + concurrently with the collector, since the collector looks at its + data structures. It can't acquire the allocator lock, since arbitrary + user startup code may run as part of dlopen().) Under unusual + conditions, this may cause unexpected heap growth. + +5) The combination of GC_LINUX_THREADS, REDIRECT_MALLOC, and incremental + collection fails in seemingly random places. This hasn't been tracked + down yet, but is perhaps not completely astonishing. The thread package + uses malloc, and thus can presumably get SIGSEGVs while inside the + package. There is no real guarantee that signals are handled properly + at that point. + +6) Thread local storage may not be viewed as part of the root set by the + collector. This probably depends on the linuxthreads version. For the + time being, any collectable memory referenced by thread local storage should + also be referenced from elsewhere, or be allocated as uncollectable. + (This is really a bug that should be fixed somehow.) + + +M68K LINUX: +(From Richard Zidlicky) +The bad news is that it can crash every linux-m68k kernel on a 68040, +so an additional test is needed somewhere on startup. I have meanwhile +patches to correct the problem in 68040 buserror handler but it is not +yet in any standard kernel. + +Here is a simple test program to detect whether the kernel has the +problem. It could be run as a separate check in configure or tested +upon startup. If it fails (return !0) than mprotect can't be used +on that system. + +/* + * test for bug that may crash 68040 based Linux + */ + +#include <sys/mman.h> +#include <signal.h> +#include <unistd.h> +#include <stdio.h> +#include <stdlib.h> + + +char *membase; +int pagesize=4096; +int pageshift=12; +int x_taken=0; + +int sighandler(int sig) +{ + mprotect(membase,pagesize,PROT_READ|PROT_WRITE); + x_taken=1; +} + +main() +{ + long l; + + signal(SIGSEGV,sighandler); + l=(long)mmap(NULL,pagesize,PROT_READ,MAP_PRIVATE | MAP_ANON,-1,0); + if (l==-1) + { + perror("mmap/malloc"); + abort(); + } + membase=(char*)l; + *(long*)(membase+sizeof(long))=123456789; + if (*(long*)(membase+sizeof(long)) != 123456789 ) + { + fprintf(stderr,"writeback failed !\n"); + exit(1); + } + if (!x_taken) + { + fprintf(stderr,"exception not taken !\n"); + exit(1); + } + fprintf(stderr,"vmtest Ok\n"); + exit(0); +} + + diff --git a/gc/doc/README.macros b/gc/doc/README.macros new file mode 100644 index 0000000..d9df8dd --- /dev/null +++ b/gc/doc/README.macros @@ -0,0 +1,78 @@ +The collector uses a large amount of conditional compilation in order to +deal with platform dependencies. This violates a number of known coding +standards. On the other hand, it seems to be the only practical way to +support this many platforms without excessive code duplication. + +A few guidelines have mostly been followed in order to keep this manageable: + +1) #if and #ifdef directives are properly indented whenever easily possible. +All known C compilers allow whitespace between the "#" and the "if" to make +this possible. ANSI C also allows white space before the "#", though we +avoid that. It has the known disadvantages that it differs from the normal +GNU conventions, and that it makes patches larger than otherwise necessary. +In my opinion, it's still well worth it, for the same reason that we indent +ordinary "if" statements. + +2) Whenever possible, tests are performed on the macros defined in gcconfig.h +instead of directly testing patform-specific predefined macros. This makes it +relatively easy to adapt to new compilers with a different set of predefined +macros. Currently these macros generally identify platforms instead of +features. In many cases, this is a mistake. + +3) The code currently avoids #elif, eventhough that would make it more +readable. This was done since #elif would need to be understood by ALL +compilers used to build the collector, and that hasn't always been the case. +It makes sense to reconsider this decision at some point, since #elif has been +standardized at least since 1989. + +Many of the tested configuration macros are at least somewhat defined in +either include/private/gcconfig.h or in Makefile.direct. Here is an attempt +at defining some of the remainder: (Thanks to Walter Bright for suggesting +this. This is a work in progress) + +MACRO EXPLANATION +----- ----------- + +__DMC__ Always #define'd by the Digital Mars compiler. Expands + to the compiler version number in hex, i.e. 0x810 is + version 8.1b0 + +_ENABLE_ARRAYNEW + #define'd by the Digital Mars C++ compiler when + operator new[] and delete[] are separately + overloadable. Used in gc_cpp.h. + +_MSC_VER Expands to the Visual C++ compiler version. Assumed to + not be defined for other compilers (at least if they behave + appreciably differently). + +_DLL Defined by Visual C++ if dynamic libraries are being built + or used. Used to test whether __declspec(dllimport) or + __declspec(dllexport) needs to be added to declarations + to support the case in which the collector is in a dll. + +GC_DLL User-settable macro that forces the effect of _DLL. + +GC_NOT_DLL User-settable macro that overrides _DLL, e.g. if dynamic + libraries are used, but the collector is in a static library. + +__STDC__ Assumed to be defined only by compilers that understand + prototypes and other C89 features. Its value is generally + not used, since we are fine with most nonconforming extensions. + +SUNOS5SIGS Solaris-like signal handling. This is probably misnamed, + since it really doesn't guarantee much more than Posix. + Currently set only for Solaris2.X, HPUX, and DRSNX. Should + probably be set for some other platforms. + +PCR Set if the collector is being built as part of the Xerox + Portable Common Runtime. + +SRC_M3 Set if the collector is being built as a replacement of the + one in the DEC/Compaq SRC Modula-3 runtime. I suspect this + was last used around 1994, and no doubt broke a long time ago. + It's there primarily incase someone wants to port to a similar + system. + + + diff --git a/gc/doc/README.rs6000 b/gc/doc/README.rs6000 new file mode 100644 index 0000000..f5630b2 --- /dev/null +++ b/gc/doc/README.rs6000 @@ -0,0 +1,9 @@ +We have so far failed to find a good way to determine the stack base. +It is highly recommended that GC_stackbottom be set explicitly on program +startup. The supplied value sometimes causes failure under AIX 4.1, though +it appears to work under 3.X. HEURISTIC2 seems to work under 4.1, but +involves a substantial performance penalty, and will fail if there is +no limit on stack size. + +There is no thread support. (I assume recent versions of AIX provide +pthreads? I no longer have access to a machine ...) diff --git a/gc/doc/README.sgi b/gc/doc/README.sgi new file mode 100644 index 0000000..7bdb50a --- /dev/null +++ b/gc/doc/README.sgi @@ -0,0 +1,41 @@ +Performance of the incremental collector can be greatly enhanced with +-DNO_EXECUTE_PERMISSION. + +The collector should run with all of the -32, -n32 and -64 ABIs. Remember to +define the AS macro in the Makefile to be "as -64", or "as -n32". + +If you use -DREDIRECT_MALLOC=GC_malloc with C++ code, your code should make +at least one explicit call to malloc instead of new to ensure that the proper +version of malloc is linked in. + +Sproc threads are not supported in this version, though there may exist other +ports. + +Pthreads support is provided. This requires that: + +1) You compile the collector with -DGC_IRIX_THREADS specified in the Makefile. + +2) You have the latest pthreads patches installed. + +(Though the collector makes only documented pthread calls, +it relies on signal/threads interactions working just right in ways +that are not required by the standard. It is unlikely that this code +will run on other pthreads platforms. But please tell me if it does.) + +3) Every file that makes thread calls should define IRIX_THREADS and then +include gc.h. Gc.h redefines some of the pthread primitives as macros which +also provide the collector with information it requires. + +4) pthread_cond_wait and pthread_cond_timed_wait should be prepared for +premature wakeups. (I believe the pthreads and realted standards require this +anyway. Irix pthreads often terminate a wait if a signal arrives. +The garbage collector uses signals to stop threads.) + +5) It is expensive to stop a thread waiting in IO at the time the request is +initiated. Applications with many such threads may not exhibit acceptable +performance with the collector. (Increasing the heap size may help.) + +6) The collector should not be compiled with -DREDIRECT_MALLOC. This +confuses some library calls made by the pthreads implementation, which +expect the standard malloc. + diff --git a/gc/doc/README.solaris2 b/gc/doc/README.solaris2 new file mode 100644 index 0000000..6ed61dc --- /dev/null +++ b/gc/doc/README.solaris2 @@ -0,0 +1,62 @@ +The collector supports both incremental collection and threads under +Solaris 2. The incremental collector normally retrieves page dirty information +through the appropriate /proc calls. But it can also be configured +(by defining MPROTECT_VDB instead of PROC_VDB in gcconfig.h) to use mprotect +and signals. This may result in shorter pause times, but it is no longer +safe to issue arbitrary system calls that write to the heap. + +Under other UNIX versions, +the collector normally obtains memory through sbrk. There is some reason +to expect that this is not safe if the client program also calls the system +malloc, or especially realloc. The sbrk man page strongly suggests this is +not safe: "Many library routines use malloc() internally, so use brk() +and sbrk() only when you know that malloc() definitely will not be used by +any library routine." This doesn't make a lot of sense to me, since there +seems to be no documentation as to which routines can transitively call malloc. +Nonetheless, under Solaris2, the collector now (since 4.12) allocates +memory using mmap by default. (It defines USE_MMAP in gcconfig.h.) +You may want to reverse this decisions if you use -DREDIRECT_MALLOC=... + + +SOLARIS THREADS: + +The collector must be compiled with -DGC_SOLARIS_THREADS (thr_ functions) +or -DGC_SOLARIS_PTHREADS (pthread_ functions) to be thread safe. +It is also essential that gc.h be included in files that call thr_create, +thr_join, thr_suspend, thr_continue, or dlopen. Gc.h macro defines +these to also do GC bookkeeping, etc. Gc.h must be included with +one or both of these macros defined, otherwise +these replacements are not visible. +A collector built in this way way only be used by programs that are +linked with the threads library. + +In this mode, the collector contains various workarounds for older Solaris +bugs. Mostly, these should not be noticeable unless you look at system +call traces. However, it cannot protect a guard page at the end of +a thread stack. If you know that you will only be running Solaris2.5 +or later, it should be possible to fix this by compiling the collector +with -DSOLARIS23_MPROTECT_BUG_FIXED. + +Since 5.0 alpha5, dlopen disables collection temporarily, +unless USE_PROC_FOR_LIBRARIES is defined. In some unlikely cases, this +can result in unpleasant heap growth. But it seems better than the +race/deadlock issues we had before. + +If solaris_threads are used on an X86 processor with malloc redirected to +GC_malloc, it is necessary to call GC_thr_init explicitly before forking the +first thread. (This avoids a deadlock arising from calling GC_thr_init +with the allocation lock held.) + +It appears that there is a problem in using gc_cpp.h in conjunction with +Solaris threads and Sun's C++ runtime. Apparently the overloaded new operator +is invoked by some iostream initialization code before threads are correctly +initialized. As a result, call to thr_self() in garbage collector +initialization segfaults. Currently the only known workaround is to not +invoke the garbage collector from a user defined global operator new, or to +have it invoke the garbage-collector's allocators only after main has started. +(Note that the latter requires a moderately expensive test in operator +delete.) + +Hans-J. Boehm +(The above contains my personal opinions, which are probably not shared +by anyone else.) diff --git a/gc/doc/README.uts b/gc/doc/README.uts new file mode 100644 index 0000000..6be4966 --- /dev/null +++ b/gc/doc/README.uts @@ -0,0 +1,2 @@ +Alistair Crooks supplied the port. He used Lexa C version 2.1.3 with +-Xa to compile. diff --git a/gc/doc/README.win32 b/gc/doc/README.win32 new file mode 100644 index 0000000..417281d --- /dev/null +++ b/gc/doc/README.win32 @@ -0,0 +1,149 @@ +The collector has at various times been compiled under Windows 95 & NT, +with the original Microsoft SDK, with Visual C++ 2.0, 4.0, and 6, with +the GNU win32 environment, with Borland 4.5, and recently with +Watcom C. It is likely that some of these have been broken in the +meantime. Patches are appreciated. + +It runs under both win32s and win32, but with different semantics. +Under win32, all writable pages outside of the heaps and stack are +scanned for roots. Thus the collector sees pointers in DLL data +segments. Under win32s, only the main data segment is scanned. +(The main data segment should always be scanned. Under some +versions of win32s, other regions may also be scanned.) +Thus all accessible objects should be accessible from local variables +or variables in the main data segment. Alternatively, other data +segments (e.g. in DLLs) may be registered with the collector by +calling GC_init() and then GC_register_root_section(a), where +a is the address of some variable inside the data segment. (Duplicate +registrations are ignored, but not terribly quickly.) + +(There are two reasons for this. We didn't want to see many 16:16 +pointers. And the VirtualQuery call has different semantics under +the two systems, and under different versions of win32s.) + +The collector test program "gctest" is linked as a GUI application, +but does not open any windows. Its output appears in the file +"gc.log". It may be started from the file manager. The hour glass +cursor may appear as long as it's running. If it is started from the +command line, it will usually run in the background. Wait a few +minutes (a few seconds on a modern machine) before you check the output. +You should see either a failure indication or a "Collector appears to +work" message. + +The cord test program has not been ported (but should port +easily). A toy editor (cord/de.exe) based on cords (heavyweight +strings represented as trees) has been ported and is included. +It runs fine under either win32 or win32S. It serves as an example +of a true Windows application, except that it was written by a +nonexpert Windows programmer. (There are some peculiarities +in the way files are displayed. The <cr> is displayed explicitly +for standard DOS text files. As in the UNIX version, control +characters are displayed explicitly, but in this case as red text. +This may be suboptimal for some tastes and/or sets of default +window colors.) + +In general -DREDIRECT_MALLOC is unlikely to work unless the +application is completely statically linked. + +For Microsoft development tools, rename NT_MAKEFILE as +MAKEFILE. (Make sure that the CPU environment variable is defined +to be i386.) In order to use the gc_cpp.h C++ interface, all +client code should include gc_cpp.h. + +Clients may need to define GC_NOT_DLL before including gc.h, if the +collector was built as a static library (as it normally is in the +absence of thread support). + +For GNU-win32, use the regular makefile, possibly after uncommenting +the line "include Makefile.DLLs". The latter should be necessary only +if you want to package the collector as a DLL. The GNU-win32 port is +believed to work only for b18, not b19, probably dues to linker changes +in b19. This is probably fixable with a different definition of +DATASTART and DATAEND in gcconfig.h. + +For Borland tools, use BCC_MAKEFILE. Note that +Borland's compiler defaults to 1 byte alignment in structures (-a1), +whereas Visual C++ appears to default to 8 byte alignment (/Zp8). +The garbage collector in its default configuration EXPECTS AT +LEAST 4 BYTE ALIGNMENT. Thus the BORLAND DEFAULT MUST +BE OVERRIDDEN. (In my opinion, it should usually be anyway. +I expect that -a1 introduces major performance penalties on a +486 or Pentium.) Note that this changes structure layouts. (As a last +resort, gcconfig.h can be changed to allow 1 byte alignment. But +this has significant negative performance implications.) +The Makefile is set up to assume Borland 4.5. If you have another +version, change the line near the top. By default, it does not +require the assembler. If you do have the assembler, I recommend +removing the -DUSE_GENERIC. + +There is some support for incremental collection. This is +currently pretty simple-minded. Pages are protected. Protection +faults are caught by a handler installed at the bottom of the handler +stack. This is both slow and interacts poorly with a debugger. +Whenever possible, I recommend adding a call to +GC_enable_incremental at the last possible moment, after most +debugging is complete. Unlike the UNIX versions, no system +calls are wrapped by the collector itself. It may be necessary +to wrap ReadFile calls that use a buffer in the heap, so that the +call does not encounter a protection fault while it's running. +(As usual, none of this is an issue unless GC_enable_incremental +is called.) + +Note that incremental collection is disabled with -DSMALL_CONFIG. + +James Clark has contributed the necessary code to support win32 threads. +Use NT_THREADS_MAKEFILE (a.k.a gc.mak) instead of NT_MAKEFILE +to build this version. Note that this requires some files whose names +are more than 8 + 3 characters long. Thus you should unpack the tar file +so that long file names are preserved. To build the garbage collector +test with VC++ from the command line, use + +nmake /F ".\gc.mak" CFG="gctest - Win32 Release" + +This requires that the subdirectory gctest\Release exist. +The test program and DLL will reside in the Release directory. + +This version relies on the collector residing in a dll. + +This version currently supports incremental collection only if it is +enabled before any additional threads are created. +Version 4.13 attempts to fix some of the earlier problems, but there +may be other issues. If you need solid support for win32 threads, you +might check with Geodesic Systems. Their collector must be licensed, +but they have invested far more time in win32-specific issues. + +Hans + +Ivan V. Demakov's README for the Watcom port: + +The collector has been compiled with Watcom C 10.6 and 11.0. +It runs under win32, win32s, and even under msdos with dos4gw +dos-extender. It should also run under OS/2, though this isn't +tested. Under win32 the collector can be built either as dll +or as static library. + +Note that all compilations were done under Windows 95 or NT. +For unknown reason compiling under Windows 3.11 for NT (one +attempt has been made) leads to broken executables. + +Incremental collection is not supported. + +cord is not ported. + +Before compiling you may need to edit WCC_MAKEFILE to set target +platform, library type (dynamic or static), calling conventions, and +optimization options. + +To compile the collector and testing programs use the command: + wmake -f WCC_MAKEFILE + +All programs using gc should be compiled with 4-byte alignment. +For further explanations on this see comments about Borland. + +If gc compiled as dll, the macro ``GC_DLL'' should be defined before +including "gc.h" (for example, with -DGC_DLL compiler option). It's +important, otherwise resulting programs will not run. + +Ivan Demakov (email: ivan@tgrad.nsk.su) + + |