GC_MALLOC(1L) GC_MALLOC(1L)
2 October 2003
NAME
GC_malloc, GC_malloc_atomic, GC_free, GC_realloc,
GC_enable_incremental, GC_register_finalizer,
GC_malloc_ignore_off_page, GC_malloc_atomic_ignore_off_page,
GC_set_warn_proc - Garbage collecting malloc replacement
SYNOPSIS
#include "gc.h"
void * GC_malloc(size_t size);
void GC_free(void *ptr);
void * GC_realloc(void *ptr, size_t size);
cc ... gc.a
DESCRIPTION
GC_malloc and GC_free are plug-in replacements for standard malloc and
free. However, GC_malloc will attempt to reclaim inaccessible space
automatically by invoking a conservative garbage collector at
appropriate points. The collector traverses all data structures
accessible by following pointers from the machines registers,
stack(s), data, and bss segments. Inaccessible structures will be
reclaimed. A machine word is considered to be a valid pointer if it
is an address inside an object allocated by GC_malloc or friends. In
most cases it is preferable to call the macros GC_MALLOC, GC_FREE,
etc. instead of calling GC_malloc and friends directly. This allows
debugging versions of the routines to be substituted by defining
GC_DEBUG before including gc.h. See the documentation in the include
file gc_cpp.h for an alternate, C++ specific interface to the garbage
collector. Unlike the standard implementations of malloc, GC_malloc
clears the newly allocated storage. GC_malloc_atomic does not.
Furthermore, it informs the collector that the resulting object will
never contain any pointers, and should therefore not be scanned by the
collector. GC_free can be used to deallocate objects, but its use is
optional, and generally discouraged. GC_realloc has the standard
realloc semantics. It preserves pointer-free-ness.
GC_register_finalizer allows for registration of functions that are
invoked when an object becomes inaccessible. The garbage collector
tries to avoid allocating memory at locations that already appear to
be referenced before allocation. (Such apparent ``pointers'' are
usually large integers and the like that just happen to look like an
address.) This may make it hard to allocate very large objects. An
attempt to do so may generate a warning. GC_malloc_ignore_off_page
and GC_malloc_atomic_ignore_off_page inform the collector that the
client code will always maintain a pointer to near the beginning of
the object (within the first 512 bytes), and that pointers beyond that
can be ignored by the collector. This makes it much easier for the
collector to place large objects. These are recommended for large
object allocation. (Objects expected to be larger than about
100KBytes should be allocated this way.) It is also possible to use
the collector to find storage leaks in programs destined to be run
with standard malloc/free. The collector can be compiled for thread-
- 1 - Formatted: February 12, 2012
GC_MALLOC(1L) GC_MALLOC(1L)
2 October 2003
safe operation. Unlike standard malloc, it is safe to call malloc
after a previous malloc call was interrupted by a signal, provided the
original malloc call is not resumed. The collector may, on rare
occasion produce warning messages. On UNIX machines these appear on
stderr. Warning messages can be filtered, redirected, or ignored with
GC_set_warn_proc This is recommended for production code. See gc.h
for details. Fully portable code should call GC_INIT from the main
program before making any other GC calls. On most platforms this does
nothing and the collector is initialized on first use. On a few
platforms explicit initialization is necessary. And it can never
hurt. Debugging versions of many of the above routines are provided as
macros. Their names are identical to the above, but consist of all
capital letters. If GC_DEBUG is defined before gc.h is included,
these routines do additional checking, and allow the leak detecting
version of the collector to produce slightly more useful output.
Without GC_DEBUG defined, they behave exactly like the lower-case
versions. On some machines, collection will be performed
incrementally after a call to GC_enable_incremental. This may
temporarily write protect pages in the heap. See the README file for
more information on how this interacts with system calls that write to
the heap. Other facilities not discussed here include limited
facilities to support incremental collection on machines without
appropriate VM support, provisions for providing more explicit object
layout information to the garbage collector, more direct support for
``weak'' pointers, support for ``abortable'' garbage collections
during idle time, etc.
SEE ALSO
The README and gc.h files in the distribution. More detailed
definitions of the functions exported by the collector are given
there. (The above list is not complete.) The web site at
http://www.hpl.hp.com/personal/Hans_Boehm/gc . Boehm, H., and M.
Weiser, "Garbage Collection in an Uncooperative Environment", Software
Practice & Experience, September 1988, pp. 807-820. The malloc(3) man
page.
AUTHOR
Hans-J. Boehm (Hans.Boehm@hp.com). Some of the code was written by
others, most notably Alan Demers.
- 2 - Formatted: February 12, 2012
|
