+ storage. Set automatically for thread-local allocation with
+ the HP/UX vendor compiler. Usable with gcc on sufficiently
+ up-to-date ELF platforms.
+
+IMPORTANT: Any of the _THREADS options must normally also be defined in
+ the client before including gc.h. This redefines thread primitives to
+ invoke the GC_ versions instead. Alternatively, linker-based symbol
+ interception can be used on a few platforms.
+
+GC_THREADS Should set the appropriate one of the below macros,
+ except GC_WIN32_PTHREADS, which must be set explicitly. Tested by gc.h.
+
+GC_SOLARIS_THREADS Enables support for Solaris pthreads.
+ Must also define _REENTRANT.
+
+GC_IRIX_THREADS Enables support for Irix pthreads. See README.sgi.
+
+GC_HPUX_THREADS Enables support for HP/UX 11 pthreads.
+ Also requires _REENTRANT or _POSIX_C_SOURCE=199506L. See README.hp.
+
+GC_LINUX_THREADS Enables support for Xavier Leroy's Linux threads
+ or NPTL threads. See README.linux. _REENTRANT may also be required.
+
+GC_OSF1_THREADS Enables support for Tru64 pthreads.
+
+GC_FREEBSD_THREADS Enables support for FreeBSD pthreads.
+ Appeared to run into some underlying thread problems.
+
+GC_NETBSD_THREADS Enables support for NetBSD pthreads.
+
+GC_OPENBSD_THREADS Enables support for OpenBSD pthreads.
+
+GC_DARWIN_THREADS Enables support for Mac OS X pthreads.
+
+GC_AIX_THREADS Enables support for IBM AIX threads.
+
+GC_DGUX386_THREADS Enables support for DB/UX on I386 threads.
+ See README.DGUX386. (Probably has not been tested recently.)
+
+GC_WIN32_THREADS Enables support for win32 threads. That makes sense
+ for this Makefile only under Cygwin.
+
+GC_WIN32_PTHREADS Enables support for Ming32 pthreads. This cannot be
+ enabled automatically by GC_THREADS, which would assume Win32 native
+ threads.
+
+PTW32_STATIC_LIB Causes the static version of the Mingw pthreads
+ library to be used. Requires GC_WIN32_PTHREADS.
+
+GC_PTHREADS_PARAMARK Causes pthread-based parallel mark implementation
+ to be used even if GC_WIN32_PTHREADS is undefined. (Useful for WinCE.)
+
+ALL_INTERIOR_POINTERS Allows all pointers to the interior of objects to be
+ recognized. (See gc_priv.h for consequences.) Alternatively,
+ GC_all_interior_pointers can be set at process initialization time.
+
+SMALL_CONFIG Tries to tune the collector for small heap sizes,
+ usually causing it to use less space in such situations.
+ Incremental collection no longer works in this case.
+
+GC_DISABLE_INCREMENTAL Turn off the incremental collection support.
+
+NO_INCREMENTAL Causes the gctest program to not invoke the incremental
+ collector. This has no impact on the generated library, only on the test
+ program. (This is often useful for debugging failures unrelated to
+ incremental GC.)
+
+LARGE_CONFIG Tunes the collector for unusually large heaps.
+ Necessary for heaps larger than about 4 GiB on most (64-bit) machines.
+ Recommended for heaps larger than about 500 MiB. Not recommended for
+ embedded systems.
+
+DONT_ADD_BYTE_AT_END Meaningful only with ALL_INTERIOR_POINTERS or
+ GC_all_interior_pointers = 1. Normally ALL_INTERIOR_POINTERS
+ causes all objects to be padded so that pointers just past the end of
+ an object can be recognized. This can be expensive. (The padding
+ is normally more than one byte due to alignment constraints.)
+ DONT_ADD_BYTE_AT_END disables the padding.
+
+NO_EXECUTE_PERMISSION May cause some or all of the heap to not
+ have execute permission, i.e. it may be impossible to execute
+ code from the heap. Currently this only affects the incremental
+ collector on UNIX machines. It may greatly improve its performance,
+ since this may avoid some expensive cache synchronization.
+
+GC_NO_OPERATOR_NEW_ARRAY Declares that the C++ compiler does not
+ support the new syntax "operator new[]" for allocating and deleting arrays.
+ See gc_cpp.h for details. No effect on the C part of the collector.
+ This is defined implicitly in a few environments. Must also be defined
+ by clients that use gc_cpp.h.
+
+REDIRECT_MALLOC=<X> Causes malloc to be defined as alias for X.
+ Unless the following macros are defined, realloc is also redirected
+ to GC_realloc, and free is redirected to GC_free.
+ Calloc and strdup are redefined in terms of the new malloc. X should
+ be either GC_malloc or GC_malloc_uncollectable, or
+ GC_debug_malloc_replacement. (The latter invokes GC_debug_malloc
+ with dummy source location information, but still results in
+ properly remembered call stacks on Linux/X86 and Solaris/SPARC.
+ It requires that the following two macros also be used.)
+ The former is occasionally useful for working around leaks in code
+ you don't want to (or can't) look at. It may not work for
+ existing code, but it often does. Neither works on all platforms,
+ since some ports use malloc or calloc to obtain system memory.
+ (Probably works for UNIX, and win32.) If you build with DBG_HDRS_ALL,
+ you should only use GC_debug_malloc_replacement as a malloc
+ replacement.
+
+REDIRECT_REALLOC=<X> Causes GC_realloc to be redirected to X.
+ The canonical use is REDIRECT_REALLOC=GC_debug_realloc_replacement,
+ together with REDIRECT_MALLOC=GC_debug_malloc_replacement to
+ generate leak reports with call stacks for both malloc and realloc.
+ This also requires REDIRECT_FREE.
+
+REDIRECT_FREE=<X> Causes free to be redirected to X. The canonical use
+ is REDIRECT_FREE=GC_debug_free.
+
+IGNORE_FREE Turns calls to free into a no-op. Only useful with
+ REDIRECT_MALLOC.
+
+NO_DEBUGGING Removes GC_dump and the debugging routines it calls.
+ Reduces code size slightly at the expense of debuggability.
+
+DEBUG_THREADS Turn on printing additional thread-support debugging
+ information.
+
+JAVA_FINALIZATION Makes it somewhat safer to finalize objects out of
+ 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
+ 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.
+
+ATOMIC_UNCOLLECTABLE Includes code for GC_malloc_atomic_uncollectable.
+ This is useful if either the vendor malloc implementation is poor,
+ or if REDIRECT_MALLOC is used.
+
+MARK_BIT_PER_GRANULE Requests that a mark bit (or often byte)
+ be allocated for each allocation granule, as opposed to each object.
+ This often improves speed, possibly at some cost in space and/or
+ cache footprint. Normally it is best to let this decision be
+ made automatically depending on platform.
+
+MARK_BIT_PER_OBJ Requests that a mark bit be allocated for each
+ object instead of allocation granule. The opposite of
+ MARK_BIT_PER_GRANULE.
+
+HBLKSIZE=<ddd> Explicitly sets the heap block size (where ddd is a power of
+ 2 between 512 and 16384). Each heap block is devoted to a single size and
+ kind of object. For the incremental collector it makes sense to match
+ the most likely page size. Otherwise large values result in more
+ fragmentation, but generally better performance for large heaps.
+
+USE_MMAP Use MMAP instead of sbrk to get new memory.
+ Works for Linux, FreeBSD, Cygwin, Solaris and Irix.
+
+USE_MUNMAP Causes memory to be returned to the OS under the right
+ circumstances. This currently disables VM-based incremental collection
+ (except for Win32 with GetWriteWatch() available).
+ Works under some Unix, Linux and Windows versions.
+ Requires USE_MMAP except for Windows.
+
+MUNMAP_THRESHOLD=<value> Set the desired memory blocks unmapping
+ threshold (the number of sequential garbage collections for which
+ a candidate block for unmapping should remain free).
+
+GC_FORCE_UNMAP_ON_GCOLLECT Set "unmap as much as possible on explicit GC"
+ mode on by default. The mode could be changed at run-time. Has no effect
+ unless unmapping is turned on. Has no effect on implicitly-initiated
+ garbage collections.
+
+MMAP_STACKS (for Solaris threads) Use mmap from /dev/zero rather than
+ GC_scratch_alloc() to get stack memory.
+
+PRINT_BLACK_LIST Whenever a black list entry is added, i.e. whenever
+ the garbage collector detects a value that looks almost, but not quite,
+ like a pointer, print both the address containing the value, and the
+ value of the near-bogus-pointer. Can be used to identify regions of
+ memory that are likely to contribute misidentified pointers.
+
+KEEP_BACK_PTRS Add code to save back pointers in debugging headers
+ for objects allocated with the debugging allocator. If all objects
+ through GC_MALLOC with GC_DEBUG defined, this allows the client
+ to determine how particular or randomly chosen objects are reachable
+ for debugging/profiling purposes. The gc_backptr.h interface is
+ implemented only if this is defined.
+
+GC_ASSERTIONS Enable some internal GC assertion checking. Currently
+ this facility is only used in a few places. It is intended primarily
+ for debugging of the garbage collector itself, but could also...
+
+DBG_HDRS_ALL Make sure that all objects have debug headers. Increases
+ the reliability (from 99.9999% to 100% mod. bugs) of some of the debugging
+ code (especially KEEP_BACK_PTRS). Makes SHORT_DBG_HDRS possible.
+ Assumes that all client allocation is done through debugging allocators.
+
+SHORT_DBG_HDRS Assume that all objects have debug headers. Shorten
+ the headers to minimize object size, at the expense of checking for
+ writes past the end of an object. This is intended for environments
+ in which most client code is written in a "safe" language, such as
+ Scheme or Java. Assumes that all client allocation is done using
+ the GC_debug_ functions, or through the macros that expand to these,
+ or by redirecting malloc to GC_debug_malloc_replacement.
+ (Also eliminates the field for the requested object size.)
+ Occasionally could be useful for debugging of client code. Slows down the
+ collector somewhat, but not drastically.
+
+SAVE_CALL_COUNT=<n> Set the number of call frames saved with objects
+ allocated through the debugging interface. Affects the amount of
+ information generated in leak reports. Only matters on platforms
+ on which we can quickly generate call stacks, currently Linux/(X86 & SPARC)
+ and Solaris/SPARC and platforms that provide execinfo.h.
+ Default is zero. On X86, client
+ code should NOT be compiled with -fomit-frame-pointer.
+
+SAVE_CALL_NARGS=<n> Set the number of functions arguments to be saved
+ with each call frame. Default is zero. Ignored if we don't know how to
+ retrieve arguments on the platform.
+
+CHECKSUMS Reports on erroneously clear dirty bits, and unexpectedly
+ altered stubborn objects, at substantial performance cost. Use only for
+ debugging of the incremental collector. Not compatible with USE_MUNMAP
+ or threads.
+
+GC_GCJ_SUPPORT Includes support for gcj (and possibly other systems
+ that include a pointer to a type descriptor in each allocated object).
+ Building this way requires an ANSI C compiler.
+
+USE_I686_PREFETCH Causes the collector to issue Pentium III style
+ prefetch instructions. No effect except on X86 Linux platforms.
+ Assumes a very recent gcc-compatible compiler and assembler.
+ (Gas prefetcht0 support was added around May 1999.)
+ Empirically the code appears to still run correctly on Pentium II
+ processors, though with no performance benefit. May not run on other
+ X86 processors? In some cases this improves performance by
+ 15% or so.
+
+USE_3DNOW_PREFETCH Causes the collector to issue AMD 3DNow style
+ prefetch instructions. Same restrictions as USE_I686_PREFETCH.
+ Minimally tested. Didn't appear to be an obvious win on a K6-2/500.
+
+USE_PPC_PREFETCH Causes the collector to issue PowerPC style
+ prefetch instructions. No effect except on PowerPC OS X platforms.
+ Performance impact untested.
+
+GC_USE_LD_WRAP In combination with the old flags listed in README.linux
+ causes the collector some system and pthread calls in a more transparent
+ fashion than the usual macro-based approach. Requires GNU ld, and
+ currently probably works only with Linux.
+
+GC_USE_DLOPEN_WRAP Causes the collector to redefine malloc and
+ intercepted pthread routines with their real names, and causes it to use
+ dlopen and dlsym to refer to the original versions. This makes it possible
+ to build an LD_PRELOADable malloc replacement library.
+
+THREAD_LOCAL_ALLOC Defines GC_malloc(), GC_malloc_atomic() and
+ GC_gcj_malloc() to use a per-thread set of free-lists. These then allocate
+ in a way that usually does not involve acquisition of a global lock.
+ Recommended for multiprocessors. Requires explicit GC_INIT() call, unless
+ REDIRECT_MALLOC is defined and GC_malloc is used first.
+
+USE_COMPILER_TLS Causes thread local allocation to use
+ the compiler-supported "__thread" thread-local variables. This is the
+ default in HP/UX. It may help performance on recent Linux installations.
+ (It failed for me on RedHat 8, but appears to work on RedHat 9.)
+
+PARALLEL_MARK Allows the marker to run in multiple threads. Recommended
+ for multiprocessors.
+
+DONT_USE_SIGNALANDWAIT (Win32 only) Use an alternate implementation for
+ marker threads (if PARALLEL_MARK defined) synchronization routines based
+ on InterlockedExchange() (instead of AO_fetch_and_add()) and on multiple
+ event objects (one per each marker instead of that based on Win32
+ SignalObjectAndWait() using a single event object). This is the default
+ for WinCE.
+
+GC_WINMAIN_REDIRECT (Win32 only) Redirect (rename) an application
+ WinMain to GC_WinMain; implement the "real" WinMain which starts a new
+ thread to call GC_WinMain after initializing the GC. Useful for WinCE.
+ Incompatible with GC_DLL.
+
+GC_REGISTER_MEM_PRIVATE (Win32 only) Force to register MEM_PRIVATE R/W
+ sections as data roots. Might be needed for some WinCE 6.0+ custom builds.
+ (May result in numerous "Data Abort" messages logged to WinCE debugging
+ console.) Incompatible with GCC toolchains for WinCE.
+
+NO_GETENV Prevents the collector from looking at environment variables.
+ These may otherwise alter its configuration, or turn off GC altogether.
+ I don't know of a reason to disable this, except possibly if the resulting
+ process runs as a privileged user. (This is on by default for WinCE.)
+
+EMPTY_GETENV_RESULTS Define to workaround a reputed Wine bug in getenv
+ (getenv() may return an empty string instead of NULL for a missing entry).
+
+USE_GLOBAL_ALLOC (Win32 only) Use GlobalAlloc() instead of VirtualAlloc()
+ to allocate the heap. May be needed to work around a Windows NT/2000 issue.
+ Incompatible with USE_MUNMAP. See README.win32 for details.
+
+MAKE_BACK_GRAPH Enable GC_PRINT_BACK_HEIGHT environment variable.
+ See README.environment for details. Experimental. Limited platform
+ support. Implies DBG_HDRS_ALL. All allocation should be done using
+ the debug interface.
+
+STUBBORN_ALLOC Allows allocation of "hard to change" objects, and thus
+ makes incremental collection easier. Was enabled by default until 6.0.
+ Rarely used, to my knowledge.
+
+HANDLE_FORK Attempts to make GC_malloc() work in a child process fork()'ed
+ from a multithreaded parent. Currently only supported by pthread_support.c.
+ (Similar code should work on Solaris or Irix, but it hasn't been tried.)
+
+TEST_WITH_SYSTEM_MALLOC Causes gctest to allocate (and leak) large
+ chunks of memory with the standard system malloc. This will cause the root
+ set and collected heap to grow significantly if malloc'ed memory is somehow
+ getting traced by the collector. This has no impact on the generated
+ library; it only affects the test.
+
+POINTER_MASK=<0x...> Causes candidate pointers to be AND'ed with the given
+ mask before being considered. If either this or the following macro is
+ defined, it will be assumed that all pointers stored in the heap need to be
+ processed this way. Stack and register pointers will be considered both
+ with and without processing. These macros are normally needed only to
+ support systems that use high-order pointer tags. EXPERIMENTAL.
+
+POINTER_SHIFT=<n> Causes the collector to left shift candidate pointers
+ by the indicated amount before trying to interpret them. Applied after
+ POINTER_MASK. EXPERIMENTAL. See also the preceding macro.
+
+ENABLE_TRACE Enables the GC_TRACE=addr environment setting to do its job.
+ By default this is not supported in order to keep the marker as fast as
+ possible.
+
+DARWIN_DONT_PARSE_STACK Causes the Darwin port to discover thread
+ stack bounds in the same way as other pthread ports, without trying to
+ walk the frames onthe stack. This is recommended only as a fallback for
+ applications that don't support proper stack unwinding.
+
+USE_PROC_FOR_LIBRARIES Causes the Linux collector to treat writable
+ memory mappings (as reported by /proc) as roots, if it doesn't have
+ other information about them. It no longer traverses dynamic loader
+ data structures to find dynamic library static data. This may be
+ required for applications that store pointers in mmapped segments without
+ informing the collector. But it typically performs poorly, especially
+ since it will scan inactive but cached NPTL thread stacks completely.
+
+NO_PROC_STAT Causes the collector to avoid relying on Linux
+ "/proc/self/stat".
+
+NO_GETCONTEXT Causes the collector to not assume the existence of the
+ getcontext() function on linux-like platforms. This currently happens
+ implicitly on Darwin, Hurd, or ARM or MIPS hardware. It is explicitly
+ needed for some old versions of FreeBSD.
+
+STATIC=static Causes various GC_ symbols that could logically be declared
+ static to be declared (this is the default if NO_DEBUGGING is specified).
+ Reduces the number of visible symbols (letting the optimizer do its work
+ better), which is probably cleaner, but may make some kinds of debugging
+ and profiling harder.
+
+GC_DLL Build dynamic-link library (or dynamic shared object). For Unix this
+ causes the exported symbols to have 'default' visibility (ignored unless
+ GCC v4+) and the internal ones to have 'hidden' visibility.
+
+DONT_USE_USER32_DLL (Win32 only) Don't use "user32" DLL import library
+ (containing MessageBox() entry); useful for a static GC library.
+
+GC_PREFER_MPROTECT_VDB Choose MPROTECT_VDB manually in case of multiple
+ virtual dirty bit strategies are implemented (at present useful on Win32
+ to force MPROTECT_VDB strategy instead of the default GWW_VDB one).
+
+GC_NO_DLLMAIN (Win32+DLL only) Exclude DllMain-based thread registration
+ support.
+
+GC_IGNORE_GCJ_INFO Disable GCJ-style type information (useful for
+ debugging on WinCE).
+
+GC_PRINT_VERBOSE_STATS Permanently turn on verbose logging (useful for
+ debugging and profiling on WinCE).
+
+GC_DONT_EXPAND Don't expand the heap unless explicitly requested or forced to.
+
+GC_INITIAL_HEAP_SIZE=<value> Set the desired default initial heap size
+ in bytes.
+
+GC_FREE_SPACE_DIVISOR=<value> Set alternate default GC_free_space_divisor
+ value.
projects / cacao.git / blobdiff