--- win32/gc/doc/Attic/README 2007/02/19 18:41:19 1.4 +++ win32/gc/doc/Attic/README 2009/05/16 09:21:36 1.5 @@ -1,7 +1,7 @@ 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-2004 Hewlett-Packard Development Company, L.P. +Copyright (c) 1999-2005 Hewlett-Packard Development Company, L.P. The file linux_threads.c is also Copyright (c) 1998 by Fergus Henderson. All rights reserved. @@ -11,7 +11,10 @@ Copyright (c) 2001 by Red Hat Inc. All r Several files supporting GNU-style builds are copyrighted by the Free Software Foundation, and carry a different license from that given -below. +below. The files included in the libatomic_ops distribution (included +here) use either the license below, or a similar MIT-style license, +or, for some files not actually used by the garbage-collector library, the +GPL. THIS MATERIAL IS PROVIDED AS IS, WITH ABSOLUTELY NO WARRANTY EXPRESSED OR IMPLIED. ANY USE IS AT YOUR OWN RISK. @@ -28,7 +31,7 @@ are GPL'ed, but with an exception that s 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.8 of a conservative garbage collector for C and C++. +This is version 7.1 of a conservative garbage collector for C and C++. You might find a more recent version of this at @@ -71,7 +74,7 @@ http://www.hpl.hp.com/personal/Hans_Boeh 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 +on fewer 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. @@ -117,12 +120,14 @@ from other such accessible objects, or f 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. +ALL_INTERIOR_POINTERS defined, or GC_all_interior_pointers is otherwise +set, 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. +issue for most programs occupying a small fraction of the possible +address space. There are a number of routines which modify the pointer recognition algorithm. GC_register_displacement allows certain interior pointers @@ -181,25 +186,33 @@ stored on the thread's stack for the dur 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. + As distributed, the collector operates silently +In the event of problems, this can usually be changed by defining the +GC_PRINT_STATS or GC_PRINT_VERBOSE_STATS environment variables. This +will result in a few lines 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 + On most Un*x-like platforms, the collector can be built either using a +GNU autoconf-based build infrastructure (type "configure; make" in the +simplest case), or with a classic makefile by itself (type +"cp Makefile.direct Makefile; make"). Here we focus on the latter option. +On other platforms, typically only the latter option is available, though +with a different supplied Makefile.) + + Typing "make test" nstead of "make" 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 +a second to two to run on reasonable 2007 vintage desktops. +It may use up to about 30MB 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. +"cord" string library.) The Makefile will generate a library gc.a which you should link against. Typing "make cords" will add the cord library to gc.a. @@ -220,10 +233,6 @@ machines that use a flat 32-bit or 64-bi 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 @@ -255,77 +264,8 @@ enforce less alignment for pointers. 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. - + For machines not already mentioned, or for nonstandard compilers, +some porting suggestions are provided in the "porting.html" file. THE C INTERFACE TO THE ALLOCATOR @@ -448,21 +388,10 @@ See gc_cpp.h for the definition of the i 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. + Very often it will also be necessary to use gc_allocator.h and the +allocator declared there to construct STL data structures. Otherwise +subobjects of STL data structures wil be allcoated using a system +allocator, and objects they refer to may be prematurely collected. USE AS LEAK DETECTOR: @@ -473,19 +402,14 @@ This will cause the collector to invoke 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.) + If all objects are allocated with GC_DEBUG_MALLOC (see next section), then +the default version of report_leak will report at least the source file and +line number at which the leaked object was allocated. This may sometimes be +sufficient. (On a few machines, it will also report a cryptic stack trace. +If this is not symbolic, it can somethimes be called 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. @@ -612,10 +536,12 @@ for suggestions on how to fix your compi 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. +They will decrease with the number of processors if parallel marking +is enabled. +(On 2007 vintage machines, GC times may be on the order of 5 msecs +per MB of accessible memory that needs to be scanned and processor. +Your mileage may vary.) The incremental/generational collection facility +may help in some cases. 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).