Misc. Reference Manual Pages GCMALOC(1L)
NAME
GCmalloc, GCmallocatomic, GCfree, GCrealloc,
GCenableincremental, GCregisterfinalizer,
GCmallocignoreoffpage, GCmallocatomicignoreoffpage,
GCsetwarnproc - Garbage collecting malloc replacement
SYNOPSIS
#include "gc.h"
void * GCmalloc(sizet size);
void GCfree(void *ptr);
void * GCrealloc(void *ptr, sizet size);
cc ... gc.a
DESCRIPTION
GCmalloc and GCfree are plug-in replacements for standard
malloc and free. However, GCmalloc 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 GCmalloc or friends.
In most cases it is preferable to call the macros GCMALOC,
GCFRE, etc. instead of calling GCmalloc and friends
directly. This allows debugging versions of the routines to
be substituted by defining GCDEBUG before including gc.h.
See the documentation in the include file gccpp.h for an
alternate, C] specific interface to the garbage collector.
Unlike the standard implementations of malloc, GCmalloc
clears the newly allocated storage. GCmallocatomic does
not. Furthermore, it informs the collector that the result-
ing object will never contain any pointers, and should
therefore not be scanned by the collector.
GCfree can be used to deallocate objects, but its use is
optional, and generally discouraged. GCrealloc has the
standard realloc semantics. It preserves pointer-free-ness.
GCregisterfinalizer 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 allo-
cation. (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.
SunOS 5.10 Last change: 2 October 2003 1
Misc. Reference Manual Pages GCMALOC(1L)
GCmallocignoreoffpage and
GCmallocatomicignoreoffpage 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-safe
operation. Unlike standard malloc, it is safe to call mal-
loc after a previous malloc call was interrupted by a sig-
nal, 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
GCsetwarnproc This is recommended for production code.
See gc.h for details.
Fully portable code should call GCINIT from the main pro-
gram 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 neces-
sary. And it can never hurt.
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 GCDEBUG is defined
before gc.h is included, these routines do additional check-
ing, and allow the leak detecting version of the collector
to produce slightly more useful output. Without GCDEBUG
defined, they behave exactly like the lower-case versions.
On some machines, collection will be performed incrementally
after a call to GCenableincremental. 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 facili-
ties to support incremental collection on machines without
appropriate VM support, provisions for providing more expli-
cit object layout information to the garbage collector, more
direct support for ``weak'' pointers, support for ``abort-
able'' garbage collections during idle time, etc.
SEE ALSO
The README and gc.h files in the distribution. More
SunOS 5.10 Last change: 2 October 2003 2
Misc. Reference Manual Pages GCMALOC(1L)
detailed definitions of the functions exported by the col-
lector are given there. (The above list is not complete.)
The web site at http:/www.hpl.hp.com/personal/HansBoehm/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.
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
ATRIBUTE TYPE ATRIBUTE VALUE
Availability SUNWlibgc
Interface stability Uncommitted
SunOS 5.10 Last change: 2 October 2003 3
|
