GC_MALLOC(1L)GC_MALLOC(1L)NAME
GC_malloc, GC_malloc_atomic, GC_free, GC_realloc,
GC_enable_incremental, GC_register_finalizer, GC_mal-
loc_ignore_off_page, GC_malloc_atomic_ignore_off_page,
GC_set_warn_proc - Garbage collecting malloc replacement
SYNOPSIS
#include "gc.h"
# define malloc(n)GC_malloc(n)
cc ... gc.a
DESCRIPTION
GC_malloc and GC_free are plug-in replacements for stan-
dard 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 fol-
lowing 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.
See the documentation in the include file gc_cpp.h for an
alternate, C++ specific interface to the garbage collec-
tor.
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 inacces-
sible.
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_mal-
loc_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 alloca-
tion. (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 mal-
loc/free. The collector can be compiled for thread-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 mes-
sages. 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.
Debugging versions of many of the above routines are pro-
vided 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 addi-
tional 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 incremen-
tally 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 facil-
ities to support incremental collection on machines with-
out appropriate VM support, provisions for providing more
explicit object layout information to the garbage collec-
tor, 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 col-
lector are given there. (The above list is not complete.)
Boehm, H., and M. Weiser, "Garbage Collection in an Unco-
operative Environment", Software Practice & Experience,
September 1988, pp. 807-820.
The malloc(3) man page.
AUTHOR
Hans-J. Boehm (boehm@parc.xerox.com). Some of the code
was written by others, most notably Alan Demers.
12 February 1996 GC_MALLOC(1L)
