From 87a4de2207e4b297a1a7fc6ff663e8d607726955 Mon Sep 17 00:00:00 2001 From: Ivan Maidanski Date: Thu, 21 Mar 2019 10:43:12 +0300 Subject: [PATCH] Remove documentation specific to particular old BDWGC releases * doc/README.Mac: Remove mentioning of particular GC versions; adjust the information (if needed) to match the current GC functionality. * doc/README.amiga: Likewise. * doc/README.arm.cross: Likewise. * doc/README.autoconf: Likewise. * doc/README.linux: Likewise. * doc/README.macros (FINALIZE_ON_DEMAND, JAVA_FINALIZATION): Likewise. * doc/README.sgi: Likewise. * doc/README.solaris2 (SOLARIS THREADS): Likewise. * doc/README.symbian: Likewise. * doc/README.win32 (Threads): Likewise. * doc/README.win64: Likewise. * doc/gcdescr.md (Allocation, Thread support, Thread-local allocation): Likewise. * doc/gcinterface.md (GC_INIT): Likewise. * doc/leak.md: Likewise. * doc/porting.md (Additional requirements for a basic port, Thread support): Likewise. * doc/scale.md (Options for enhanced scalability, Performance): Likewise. * doc/simple_example.md (Debugging): Do not mention removed `--enable-full-debug` option of configure. * include/gc.h (GC_parallel, GC_dont_gc, GC_use_entire_heap, GC_set_handle_fork): Remove comment that the behavior has changed in a particular GC version. * include/gc_inline.h (GC_MALLOC_WORDS_KIND): Likewise. * include/gc.h (GC_set_free_space_divisor, GC_warn_proc): Reword comment about ABI incompatible change in some GC version. * include/gc.h (GC_get_heap_usage_safe): Remove comment that the API was introduced in a particular GC version. * include/gc_cpp.h (UseGC): Likewise. * os_dep.c [LINUX_STACKBOTTOM && IA64] (GC_get_register_stack_base): Remove mentioning of a particular GC version (and of an old behavior on an ancient kernel) in a comment. * win32_threads.c [!GC_PTHREADS && !GC_NO_THREADS_DISCOVERY] (GC_DllMain): Likewise. * OS2_MAKEFILE: Likewise. --- OS2_MAKEFILE | 2 +- doc/README.Mac | 11 +++-------- doc/README.amiga | 22 ++++++++++------------ doc/README.arm.cross | 8 ++++---- doc/README.autoconf | 5 ++--- doc/README.linux | 6 +++--- doc/README.macros | 9 ++++----- doc/README.sgi | 3 +-- doc/README.solaris2 | 14 ++++++-------- doc/README.symbian | 10 ++++------ doc/README.win32 | 18 +++++++++--------- doc/README.win64 | 5 ++--- doc/gcdescr.md | 38 +++++++++++++++++++------------------- doc/gcinterface.md | 3 +-- doc/leak.md | 32 +++++++++++++------------------- doc/porting.md | 10 ++++------ doc/scale.md | 12 +++++------- doc/simple_example.md | 4 ++-- include/gc.h | 30 +++++++++++++----------------- include/gc_cpp.h | 2 +- include/gc_inline.h | 7 +++---- os_dep.c | 4 +--- win32_threads.c | 2 +- 23 files changed, 112 insertions(+), 145 deletions(-) diff --git a/OS2_MAKEFILE b/OS2_MAKEFILE index 470b9ab..60d8025 100644 --- a/OS2_MAKEFILE +++ b/OS2_MAKEFILE @@ -3,7 +3,7 @@ # Adding thread support may be nontrivial, since we haven't yet figured out how to # look at another thread's registers. -# Significantly revised for GC version 4.4 by Mark Boulter (Jan 1994). +# Significantly revised by Mark Boulter (Jan 1994). OBJS= alloc.obj reclaim.obj allchblk.obj misc.obj mach_dep.obj os_dep.obj mark_rts.obj headers.obj mark.obj obj_map.obj blacklst.obj finalize.obj new_hblk.obj dbg_mlc.obj fnlz_mlc.obj malloc.obj typd_mlc.obj ptr_chck.obj mallocx.obj gcj_mlc.obj diff --git a/doc/README.Mac b/doc/README.Mac index 848c1bc..3c840d9 100644 --- a/doc/README.Mac +++ b/doc/README.Mac @@ -3,7 +3,7 @@ You probably really wanted README.darwin. --------------------------------------------- -Patrick Beard's Notes for building GC v4.12 with CodeWarrior Pro 2: +Patrick Beard's Notes for building GC 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) @@ -24,15 +24,10 @@ 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. +The notes may or may not apply to earlier or later versions of the CWPro. 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 @@ -291,7 +286,7 @@ __datastart__, __data_end__ that wraps all globals. Patrick Beard's instructions (may be dated): -v4.3 of the collector now runs under Symantec C++/THINK C v7.0.4, and +The collector should run 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. diff --git a/doc/README.amiga b/doc/README.amiga index d97251f..8229980 100644 --- a/doc/README.amiga +++ b/doc/README.amiga @@ -187,18 +187,16 @@ 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 +- gctest checks to see if the code segment is added to the root set or not, + and complains if it is. 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. diff --git a/doc/README.arm.cross b/doc/README.arm.cross index 0ededbd..0d20839 100644 --- a/doc/README.arm.cross +++ b/doc/README.arm.cross @@ -7,21 +7,21 @@ There may well be better ways to do some of this, but .... The badge4 has a StrongArm-1110 processor and a StrongArm-1111 coprocessor. -Assume that the garbage collector distribution is unpacked into /home/arm/gc6.0, +Assume that the garbage collector distribution is unpacked into /home/arm/gc, which is visible to both the ARM machine and a linux desktop (e.g. via NFS mounting). Assume that you have a file /home/arm/config.site with contents something like the example attached below. Notice that our local ARM toolchain lives in /skiff/local. -Go to /home/arm/gc6.0 directory. Do +Go to /home/arm/gc directory. Do CONFIG_SITE=/home/arm/config.site ./configure --target=arm-linux ---prefix=/home/arm/gc6.0 +--prefix=/home/arm/gc On your desktop, do: make make install -The main garbage collector library should now be in ../gc6.0/lib/libgc.so. +The main garbage collector library should now be in ../gc/lib/libgc.so. To test the garbage collector, first do the following on your desktop make gctest diff --git a/doc/README.autoconf b/doc/README.autoconf index 5719075..7f9de22 100644 --- a/doc/README.autoconf +++ b/doc/README.autoconf @@ -1,6 +1,5 @@ -Starting from GC v6.0, we support GNU-style builds based on automake, -autoconf and libtool. This is based almost entirely on Tom Tromey's work -with gcj. +We 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 diff --git a/doc/README.linux b/doc/README.linux index fa2cd22..7f23c2c 100644 --- a/doc/README.linux +++ b/doc/README.linux @@ -60,9 +60,9 @@ To use threads, you need to abide by the following requirements: collector. This probably depends on the linuxthreads version. For the time being, any collectible memory referenced by thread local storage should also be referenced from elsewhere, or be allocated as uncollectible. - (This is really a bug that should be fixed somehow. The current GC - version probably gets things right if there are not too many tls locations - and if dlopen is not used.) + (This is really a bug that should be fixed somehow. Actually, the + collector probably gets things right, on Linux at least, if there are not + too many tls locations and if dlopen is not used.) M68K LINUX: diff --git a/doc/README.macros b/doc/README.macros index a6b96ee..94596e9 100644 --- a/doc/README.macros +++ b/doc/README.macros @@ -258,17 +258,16 @@ GC_COLLECT_AT_MALLOC= Force garbage collection at every (Might be useful for application debugging or in find-leak mode.) JAVA_FINALIZATION Makes it somewhat safer to finalize objects out of - order by specifying a nonstandard finalization mark procedure (see + order by specifying a nonstandard finalization mark procedure (see finalize.c). Objects reachable from finalizable objects will be marked in a separate post-pass, and hence their memory won't be reclaimed. Not recommended unless you are implementing a language that specifies - these semantics. Since 5.0, determines only the initial value + these semantics. Actually, the macro determines only the initial value of GC_java_finalization variable. FINALIZE_ON_DEMAND Causes finalizers to be run only in response - to explicit GC_invoke_finalizers() calls. - In 5.0 this became runtime adjustable, and this only determines the - initial value of GC_finalize_on_demand. + to explicit GC_invoke_finalizers() calls. Actually, the macro only + determines the initial value of GC_finalize_on_demand. GC_NO_FINALIZATION Exclude finalization support (for smaller code size). diff --git a/doc/README.sgi b/doc/README.sgi index e423033..88182d8 100644 --- a/doc/README.sgi +++ b/doc/README.sgi @@ -8,8 +8,7 @@ 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. +Sproc threads are not supported. Pthreads support is provided. This requires that: diff --git a/doc/README.solaris2 b/doc/README.solaris2 index b150f9c..90962da 100644 --- a/doc/README.solaris2 +++ b/doc/README.solaris2 @@ -27,10 +27,9 @@ SOLARIS THREADS: Unless --disable-threads option is given, threads support is on by default in configure. This causes the collector to be compiled with -D GC_THREADS ensuring thread safety. This assumes use of the pthread_ interface; old-style -Solaris threads are no longer supported. -Thread-local allocation is now on by default. Parallel marking is on by -default starting from GC v7.3 but it could be disabled manually -by configure --disable-parallel-mark option. +Solaris threads are no longer supported. Thread-local allocation is on by +default. Parallel marking is on by default (it could be disabled manually +by configure --disable-parallel-mark option). It is also essential that gc.h be included in files that call pthread_create, pthread_join, pthread_detach, or dlopen. gc.h macro defines these to also do @@ -38,10 +37,9 @@ 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. -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. +Unless USE_PROC_FOR_LIBRARIES is defined, dlopen disables collection +temporarily. In some unlikely cases, this can result in unpleasant heap +growth. But it seems better than the race/deadlock issues we had before. If threads are used on an X86 processor with malloc redirected to GC_malloc, it is necessary to call GC_INIT explicitly before forking the diff --git a/doc/README.symbian b/doc/README.symbian index 50658c3..515a9cc 100644 --- a/doc/README.symbian +++ b/doc/README.symbian @@ -1,10 +1,8 @@ Instructions for Symbian: -1. base version: libgc 7.1 -2. Build: use libgc.mmp -3. Limitations -3.1.No multi-threaded support - -3.2. Be careful with limitation that emulator introduces: Static roots are not +1. Build: use libgc.mmp +2. Limitations +2.1. No multi-threaded support yet +2.2. Be careful with limitation that emulator introduces: Static roots are not dynamically accessible (there are Symbian APIs for this purpose but are just stubs, returning irrelevant values). Consequently, on emulator, you can only use dlls or exe, and retrieve static diff --git a/doc/README.win32 b/doc/README.win32 index aa81e66..19038c4 100644 --- a/doc/README.win32 +++ b/doc/README.win32 @@ -165,9 +165,9 @@ Note that incremental collection is disabled with -DSMALL_CONFIG. Threads ------- -This version of the collector by default handles threads similarly -to other platforms. James Clark's code which tracks threads attached -to the collector DLL still exists, but requires that both +The collector by default handles threads similarly to other platforms. +James Clark's code which tracks threads attached to the collector DLL still +exists, but requires that both - the collector is built in a DLL with GC_DLL defined, and - GC_use_threads_discovery() is called before GC initialization, which in turn must happen before creating additional threads. @@ -189,13 +189,13 @@ 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 currently supports incremental collection only if it is -enabled before any additional threads are created. +The incremental collection is supported only if it is enabled before any +additional threads are created. -Since 6.3alpha2, threads are also better supported in static library builds -with Microsoft tools (e.g., NT_MAKEFILE) and with the GNU -tools. The collector must be built with GC_THREADS defined (this is the -default in NT_MAKEFILE, ./configure and CMakeLists.txt). +Threads are also supported in static library builds with Microsoft tools +(e.g., NT_MAKEFILE) and with the GNU tools. The collector must be built with +GC_THREADS defined (this is the default in NT_MAKEFILE, ./configure and +CMakeLists.txt). For the normal, non-dll-based thread tracking to work properly, threads should be created with GC_CreateThread or GC_beginthreadex, diff --git a/doc/README.win64 b/doc/README.win64 index 7714b5b..127db4a 100644 --- a/doc/README.win64 +++ b/doc/README.win64 @@ -1,6 +1,5 @@ -64-bit Windows on AMD64/Intel EM64T is somewhat supported in the 7.0 -and later release. A collector can be built with Microsoft Visual C++ 2005 -or with mingw-w64 gcc. +64-bit Windows on AMD64/Intel EM64T is supported. A collector can be built +with Microsoft Visual C++ 2005 or with mingw-w64 gcc. NT_MAKEFILE has been used in this environment. Type "nmake -f NT_MAKEFILE cpu=AMD64 nodebug=1" in a Visual C++ command line diff --git a/doc/gcdescr.md b/doc/gcdescr.md index 2c1a1ad..28c6eab 100644 --- a/doc/gcdescr.md +++ b/doc/gcdescr.md @@ -78,20 +78,20 @@ larger than half of `HBLKSIZE`, which is a power of 2, typically on the order of the page size. Large block sizes are rounded up to the next multiple of `HBLKSIZE` and then -allocated by `GC_allochblk`. Recent versions of the collector use an -approximate best fit algorithm by keeping free lists for several large block -sizes. The actual implementation of `GC_allochblk` is significantly -complicated by black-listing issues (see below). +allocated by `GC_allochblk`. The collector use an approximate best fit +algorithm by keeping free lists for several large block sizes. The actual +implementation of `GC_allochblk` is significantly complicated by black-listing +issues (see below). Small blocks are allocated in chunks of size `HBLKSIZE`. Each chunk is dedicated to only one object size and kind. The allocator maintains separate free lists for each size and kind of object. Associated with each kind is an array of free list pointers, with entry -`freelist[i]` pointing to a free list of size 'i' objects. In recent versions -of the collector, index `i` is expressed in granules, which are the minimum -allocatable unit, typically 8 or 16 bytes. The free lists themselves are -linked through the first word in each object (see `obj_link` macro). +`freelist[i]` pointing to a free list of size 'i' objects. Index `i` is +expressed in granules, which are the minimum allocatable unit, typically 8 or +16 bytes. The free lists themselves are linked through the first word in each +object (see `obj_link` macro). Once a large block is split for use in smaller objects, it can only be used for objects of that size, unless the collector discovers a completely empty @@ -132,14 +132,13 @@ of fragmentation. In particular: * Programs with a large root set size and little live heap memory will expand the heap to amortize the cost of scanning the roots. - * GC v5 actually collect more frequently in non-incremental mode. The large + * GC actually collect more frequently in non-incremental mode. The large block allocator usually refuses to split large heap blocks once the garbage collection threshold is reached. This often has the effect of collecting well before the heap fills up, thus reducing fragmentation and working set - size at the expense of GC time. GC v6 chooses an intermediate strategy - depending on how much large object allocation has taken place in the past. - (If the collector is configured to unmap unused pages, GC v6 uses the - strategy of GC v5.) + size at the expense of GC time. (If the collector is configured not to unmap + unused pages, GC chooses an intermediate strategy depending on how much + large object allocation has taken place in the past.) * In calculating the amount of allocation since the last collection we give partial credit for objects we expect to be explicitly deallocated. Even if all objects are explicitly managed, it is often desirable to collect @@ -466,10 +465,10 @@ stacks. This is current accomplished with `#define`'s in `gc.h` (really `gc_pthread_redirects.h`), or optionally by using `ld`'s function call wrapping mechanism under Linux. -Recent versions of the collector support several facilities to enhance the -processor-scalability and thread performance of the collector. These are -discussed in more detail [here](scale.md). We briefly outline the data -approach to thread-local allocation in the next section. +The collector support several facilities to enhance the processor-scalability +and thread performance of the collector. These are discussed in more detail +[here](scale.md). We briefly outline the data approach to thread-local +allocation in the next section. ## Thread-local allocation @@ -514,8 +513,9 @@ is required to mark all objects on pointer-free and gcj local free lists. On thread exit, any remaining thread-local free list entries are transferred back to the global free list. -Note that if the collector is configured for thread-local allocation, -`GC_malloc` only uses thread-local allocation (starting from GC v7). +Note that if the collector is configured for thread-local allocation (the +default for most platforms), `GC_malloc` and friends only use thread-local +allocation. For some more details see [here](scale.md), and the technical report entitled ["Fast Multiprocessor Memory Allocation and Garbage Collection"](http://www.hpl.hp.com/techreports/2000/HPL-2000-165.html). diff --git a/doc/gcinterface.md b/doc/gcinterface.md index 4e7d309..4bb311d 100644 --- a/doc/gcinterface.md +++ b/doc/gcinterface.md @@ -81,8 +81,7 @@ be significantly reduced. the main executable_, _not from a dynamic library_, before the initial invocation of a GC routine. It is recommended that this be done in portable code, though we try to ensure that it expands to a no-op on as many platforms -as possible. In GC v7.0, it was required if thread-local allocation is enabled -in the collector build, and `malloc` is not redirected to `GC_malloc`. +as possible. **void `GC_gcollect`(void)** - Explicitly force a garbage collection. diff --git a/doc/leak.md b/doc/leak.md index 7d62af7..4d16c1f 100644 --- a/doc/leak.md +++ b/doc/leak.md @@ -16,16 +16,13 @@ structures. Thus it does not require all objects to be deallocated at process exit time, a potentially useless activity that often triggers large amounts of paging. -All non-ancient versions of the garbage collector provide leak detection -support. Version 5.3 adds the following features: +The garbage collector provide leak detection support. This includes the +following features: 1. Leak detection mode can be initiated at run-time by setting `GC_find_leak` instead of building the collector with `FIND_LEAK` defined. This variable should be set to a nonzero value at program startup. 2. Leaked objects should be reported and then correctly garbage collected. - Prior versions either reported leaks or functioned as a garbage collector. - For the rest of this description we will give instructions that work with - any reasonable version of the collector. To use the collector as a leak detector, follow the following steps: @@ -54,8 +51,8 @@ useful in this context, and are not fully supported. Their use will usually generate additional bogus leak reports, since the collector itself drops some associated objects. -The same is generally true of thread support. However, as of 6.0alpha4, -correct leak reports should be generated with linuxthreads. +The same is generally true of thread support. However, the correct leak +reports should be generated with linuxthreads, at least. On a few platforms (currently Solaris/SPARC, Irix, and, with -DSAVE_CALL_CHAIN, Linux/X86), `GC_MALLOC` also causes some more information @@ -68,9 +65,8 @@ the aid of a debugger. The `leak_detector.h` file is included in the "include" subdirectory of the distribution. -Assume the collector has been built with `-DFIND_LEAK`. (For newer versions -of the collector, we could instead add the statement `GC_set_find_leak(1)` as -the first statement in `main`. +Assume the collector has been built with `-DFIND_LEAK` or +`GC_set_find_leak(1)` exists as the first statement in `main`. The program to be tested for leaks can then look like "leak_test.c" file in the "tests" subdirectory of the distribution. @@ -116,19 +112,17 @@ In the Irix case, only the address inside the caller to main is given. In many cases, a debugger is needed to interpret the additional information. On systems supporting the "adb" debugger, the `tools/callprocs.sh` script can -be used to replace program counter values with symbolic names. As of version -6.1, the collector tries to generate symbolic names for call stacks if it -knows how to do so on the platform. This is true on Linux/X86, but not on most -other platforms. +be used to replace program counter values with symbolic names. The collector +tries to generate symbolic names for call stacks if it knows how to do so on +the platform. This is true on Linux/X86, but not on most other platforms. ## Simplified leak detection under Linux -Since version 6.1, it should be possible to run the collector in leak -detection mode on a program a.out under Linux/X86 as follows: +It should be possible to run the collector in the leak detection mode on +a program a.out under Linux/X86 as follows: - 1. _Ensure that a.out is a single-threaded executable, or you are using - a very recent (7.0alpha7+) collector version on Linux._ On most platforms - this does not work at all for the multi-threaded programs. + 1. If possible, ensure that a.out is a single-threaded executable. On some + platforms this does not work at all for the multi-threaded programs. 2. If possible, ensure that the `addr2line` program is installed in `/usr/bin`. (It comes with most Linux distributions.) 3. If possible, compile your program, which we'll call `a.out`, with full diff --git a/doc/porting.md b/doc/porting.md index bc2b253..da8856f 100644 --- a/doc/porting.md +++ b/doc/porting.md @@ -152,7 +152,7 @@ contents that the collector must trace from are copied to the stack. Typically this can be done portably, but on some platforms it may require assembly code, or just tweaking of conditional compilation tests. -For GC v7, if your platform supports `getcontext`, then defining the macro +If your platform supports `getcontext` then defining the macro `UNIX_LIKE` for your OS in `gcconfig.h` (if it is not defined there yet) is likely to solve the problem. otherwise, if you are using gcc, `_builtin_unwind_init` will be used, and should work fine. If that is not @@ -160,10 +160,8 @@ applicable either, the implementation will try to use `setjmp`. This will work if your `setjmp` implementation saves all possibly pointer-valued registers into the buffer, as opposed to trying to unwind the stack at `longjmp` time. The `setjmp_test` test tries to determine this, but often does not get it -right. - -In GC v6.x versions of the collector, tracing of registers was more commonly -handled with assembly code. In GC v7, this is generally to be avoided. +right. Registers tracing handled with an assembly code is generally to be +avoided. Most commonly `os_dep.c` will not require attention, but see below. @@ -197,7 +195,7 @@ stopped with signals. In this case, the changes involve: be automatically defined by `gc_config_macros.h` in the right cases. It should also result in a definition of `GC_PTHREADS`, as for the existing cases. - 2. For GC v7, ensuring that the `atomic_ops` package at least minimally + 2. Ensuring that the `atomic_ops` package at least minimally supports the platform. If incremental GC is needed, or if pthread locks do not perform adequately as the allocation lock, you will probably need to ensure that a sufficient `atomic_ops` port exists for the platform diff --git a/doc/scale.md b/doc/scale.md index 75fb635..309554d 100644 --- a/doc/scale.md +++ b/doc/scale.md @@ -25,11 +25,9 @@ implementations in most cases, sometimes drastically so. ## Options for enhanced scalability -Version 6.0 of the collector adds two facilities to enhance collector -scalability on multiprocessors. As of 6.0alpha1, these are supported only -under Linux on X86 and IA64 processors, though ports to other otherwise -supported Pthreads platforms should be straightforward. They are intended -to be used together. +The collector uses two facilities to enhance collector scalability on +multiprocessors. They are intended to be used together. (The following refers +to Makefile.direct again.) * Building the collector with `-DPARALLEL_MARK` allows the collector to run the mark phase in parallel in multiple threads, and thus on multiple @@ -111,8 +109,8 @@ We conducted some simple experiments with a version of modified to run multiple concurrent client threads in the same address space. Each client thread does the same work as the original benchmark, but they share a heap. This benchmark involves very little work outside of memory -allocation. This was run with GC 6.0alpha3 on a dual processor Pentium III/500 -machine under Linux 2.2.12. +allocation. This was run with an ancient GC (released in 2000) on a dual +processor Pentium III/500 machine under Linux 2.2.12. Running with a thread-unsafe collector, the benchmark ran in 9 seconds. With the simple thread-safe collector, built with `-DGC_THREADS`, the execution diff --git a/doc/simple_example.md b/doc/simple_example.md index e19d568..9b64df0 100644 --- a/doc/simple_example.md +++ b/doc/simple_example.md @@ -136,8 +136,8 @@ The collector includes some _alternate interfaces_ to make that easier. Additional debug checks can be performed by defining `GC_DEBUG` before including `gc.h`. Additional options are available if the collector is also -built with `--enable-gc-debug` (`--enable-full-debug` in some older versions) -and all allocations are performed with `GC_DEBUG` defined. +built with `--enable-gc-debug` and all allocations are performed with +`GC_DEBUG` defined. ### What if I can't rewrite/recompile my program? diff --git a/include/gc.h b/include/gc.h index df48399..5cd39f6 100644 --- a/include/gc.h +++ b/include/gc.h @@ -5,7 +5,7 @@ * Copyright 1999 by Hewlett-Packard Company. All rights reserved. * Copyright (C) 2007 Free Software Foundation, Inc * Copyright (c) 2000-2011 by Hewlett-Packard Development Company. - * Copyright (c) 2009-2018 Ivan Maidanski + * Copyright (c) 2009-2019 Ivan Maidanski * * THIS MATERIAL IS PROVIDED AS IS, WITH ABSOLUTELY NO WARRANTY EXPRESSED * OR IMPLIED. ANY USE IS AT YOUR OWN RISK. @@ -99,11 +99,10 @@ GC_API GC_word GC_CALL GC_get_gc_no(void); /* collection is only partially functional, */ /* and may not be desirable. The getter does */ /* not use or need synchronization (i.e. */ - /* acquiring the GC lock). Starting from */ - /* GC v7.3, GC_parallel value is equal to the */ - /* number of marker threads minus one (i.e. */ - /* number of existing parallel marker threads */ - /* excluding the initiating one). */ + /* acquiring the GC lock). GC_parallel value */ + /* is equal to the number of marker threads */ + /* minus one (i.e. number of existing parallel */ + /* marker threads excluding the initiating one).*/ GC_API int GC_CALL GC_get_parallel(void); #endif @@ -242,8 +241,8 @@ GC_API # ifndef GC_DONT_GC GC_ATTR_DEPRECATED # endif - int GC_dont_gc; /* != 0 ==> Don't collect. In versions 6.2a1+, */ - /* this overrides explicit GC_gcollect() calls. */ + int GC_dont_gc; /* != 0 ==> Do not collect. This overrides */ + /* explicit GC_gcollect() calls as well. */ /* Used as a counter, so that nested enabling */ /* and disabling work correctly. Should */ /* normally be updated with GC_enable() and */ @@ -261,8 +260,7 @@ GC_API int GC_CALL GC_get_dont_expand(void); GC_API GC_ATTR_DEPRECATED int GC_use_entire_heap; /* Causes the non-incremental collector to use the */ - /* entire heap before collecting. This was the only */ - /* option for GC versions < 5.0. This sometimes */ + /* entire heap before collecting. This sometimes */ /* results in more large block fragmentation, since */ /* very large blocks will tend to get broken up */ /* during each GC cycle. It is likely to result in a */ @@ -329,8 +327,8 @@ GC_API GC_ATTR_DEPRECATED GC_word GC_free_space_divisor; /* GC_call_with_alloc_lock() is required to */ /* avoid data races (if the value is modified */ /* after the GC is put to multi-threaded mode). */ - /* In version 7.1 (and before), the setter */ - /* returned the old value. */ + /* In GC v7.1 (and before), the setter returned */ + /* the old value. */ GC_API void GC_CALL GC_set_free_space_divisor(GC_word); GC_API GC_word GC_CALL GC_get_free_space_divisor(void); @@ -476,8 +474,8 @@ GC_API int GC_CALL GC_get_max_prior_attempts(void); /* activities are not fully POSIX-compliant.) GC_set_handle_fork */ /* instructs GC_init to setup GC fork handlers using pthread_atfork, */ /* the latter might fail (or, even, absent on some targets) causing */ -/* abort at GC initialization. Starting from 7.3alpha3, problems with */ -/* missing (or failed) pthread_atfork() could be avoided by invocation */ +/* abort at GC initialization. Issues with missing (or failed) */ +/* pthread_atfork() could be avoided by invocation */ /* of GC_set_handle_fork(-1) at application start-up and surrounding */ /* each fork() with the relevant GC_atfork_prepare/parent/child calls. */ GC_API void GC_CALL GC_set_handle_fork(int); @@ -735,8 +733,6 @@ GC_API size_t GC_CALL GC_get_total_bytes(void); /* the allocator lock thus preventing data racing and returning the */ /* consistent result.) Passing NULL pointer is allowed for any */ /* argument. Returned (filled in) values are of word type. */ -/* (This API function was introduced in GC v7.2alpha7 at the same time */ -/* when GC_get_heap_size and the friends were made lock-free again.) */ GC_API void GC_CALL GC_get_heap_usage_safe(GC_word * /* pheap_size */, GC_word * /* pfree_bytes */, GC_word * /* punmapped_bytes */, @@ -1359,7 +1355,7 @@ GC_API int GC_CALL GC_invoke_finalizers(void); /* GC_set_warn_proc can be used to redirect or filter warning messages. */ /* p may not be a NULL pointer. msg is printf format string (arg must */ /* match the format). Both the setter and the getter acquire the GC */ -/* lock (to avoid data races). In version 7.1 (and before), the setter */ +/* lock (to avoid data races). In GC v7.1 (and before), the setter */ /* returned the old warn_proc value. */ typedef void (GC_CALLBACK * GC_warn_proc)(char * /* msg */, GC_word /* arg */); diff --git a/include/gc_cpp.h b/include/gc_cpp.h index 3e166e6..ce8354d 100644 --- a/include/gc_cpp.h +++ b/include/gc_cpp.h @@ -135,7 +135,7 @@ uses explicit invocation. 5. GC name conflicts: Many other systems seem to use the identifier "GC" as an abbreviation -for "Graphics Context". Since version 5.0, GC placement has been replaced +for "Graphics Context". Thus, GC placement has been replaced by UseGC. GC is an alias for UseGC, unless GC_NAME_CONFLICT is defined. ****************************************************************************/ diff --git a/include/gc_inline.h b/include/gc_inline.h index 78a714a..d2d614c 100644 --- a/include/gc_inline.h +++ b/include/gc_inline.h @@ -167,10 +167,9 @@ GC_API GC_ATTR_MALLOC GC_ATTR_ALLOC_SIZE(1) void * GC_CALL /* Allocate n words (NOT BYTES). X is made to point to the result. */ /* This should really only be used if GC_all_interior_pointers is */ /* not set, or DONT_ADD_BYTE_AT_END is set. See above. */ -/* The semantics changed in version 7.0; we no longer lock, and */ -/* the caller is responsible for supplying a cleared tiny_fl */ -/* free list array. For single-threaded applications, this may be */ -/* a global array. */ +/* Does not acquire lock. The caller is responsible for supplying */ +/* a cleared tiny_fl free list array. For single-threaded */ +/* applications, this may be a global array. */ # define GC_MALLOC_WORDS_KIND(result,n,tiny_fl,kind,init) \ do { \ size_t granules = GC_WORDS_TO_WHOLE_GRANULES(n); \ diff --git a/os_dep.c b/os_dep.c index 01332ed..4f4d884 100644 --- a/os_dep.c +++ b/os_dep.c @@ -1078,9 +1078,7 @@ GC_INNER size_t GC_page_size = 0; result = backing_store_base_from_proc(); if (0 == result) { result = (ptr_t)GC_find_limit(GC_save_regs_in_stack(), FALSE); - /* Now seems to work better than constant displacement */ - /* heuristic used in 6.X versions. The latter seems to */ - /* fail for 2.6 kernels. */ + /* This works better than a constant displacement heuristic. */ } return result; } diff --git a/win32_threads.c b/win32_threads.c index cbf874c..52f8a26 100644 --- a/win32_threads.c +++ b/win32_threads.c @@ -2858,7 +2858,7 @@ GC_INNER void GC_thr_init(void) /* Note that GC_use_threads_discovery should be called by the */ /* client application at start-up to activate automatic thread */ - /* registration (it is the default GC behavior since v7.0alpha7); */ + /* registration (it is the default GC behavior); */ /* to always have automatic thread registration turned on, the GC */ /* should be compiled with -D GC_DISCOVER_TASK_THREADS. */ if (!GC_win32_dll_threads && parallel_initialized) return TRUE; -- 2.7.4