1GC_MALLOC(1L)                                                    GC_MALLOC(1L)
2
3
4

NAME

6       GC_malloc,  GC_malloc_atomic,  GC_free, GC_realloc, GC_enable_incremen‐
7       tal,    GC_register_finalizer,    GC_malloc_ignore_off_page,    GC_mal‐
8       loc_atomic_ignore_off_page,  GC_set_warn_proc - Garbage collecting mal‐
9       loc replacement
10

SYNOPSIS

12       #include "gc.h"
13       void * GC_malloc(size_t size);
14       void GC_free(void *ptr);
15       void * GC_realloc(void *ptr, size_t size);
16
17       cc ... gc.a
18

DESCRIPTION

20       GC_malloc and GC_free are plug-in replacements for standard malloc  and
21       free.   However,  GC_malloc  will attempt to reclaim inaccessible space
22       automatically by invoking a conservative garbage collector at appropri‐
23       ate  points.  The collector traverses all data structures accessible by
24       following pointers from the machines registers, stack(s), data, and bss
25       segments.   Inaccessible  structures will be reclaimed.  A machine word
26       is considered to be a valid pointer if  it  is  an  address  inside  an
27       object allocated by GC_malloc or friends.
28
29       In  most  cases it is preferable to call the macros GC_MALLOC, GC_FREE,
30       etc.  instead of calling GC_malloc and friends directly.   This  allows
31       debugging  versions  of  the  routines  to  be  substituted by defining
32       GC_DEBUG before including gc.h.
33
34       See the documentation in the include file gc_cpp.h  for  an  alternate,
35       C++ specific interface to the garbage collector.
36
37       Unlike  the  standard  implementations  of malloc, GC_malloc clears the
38       newly allocated storage.  GC_malloc_atomic does not.   Furthermore,  it
39       informs  the collector that the resulting object will never contain any
40       pointers, and should therefore not be scanned by the collector.
41
42       GC_free can be used to deallocate objects, but its use is optional, and
43       generally  discouraged.  GC_realloc has the standard realloc semantics.
44       It preserves pointer-free-ness.  GC_register_finalizer allows for  reg‐
45       istration of functions that are invoked when an object becomes inacces‐
46       sible.
47
48       The garbage collector tries to avoid  allocating  memory  at  locations
49       that already appear to be referenced before allocation.  (Such apparent
50       ``pointers'' are usually large integers and the like that  just  happen
51       to look like an address.)  This may make it hard to allocate very large
52       objects.  An attempt to do so may generate a warning.
53
54       GC_malloc_ignore_off_page and  GC_malloc_atomic_ignore_off_page  inform
55       the  collector  that  the client code will always maintain a pointer to
56       near the beginning of the object (within the first 512 bytes), and that
57       pointers  beyond  that  can be ignored by the collector.  This makes it
58       much easier for the collector to place large objects.  These are recom‐
59       mended  for  large  object  allocation.  (Objects expected to be larger
60       than about 100KBytes should be allocated this way.)
61
62       It is also possible to use the collector to find storage leaks in  pro‐
63       grams  destined to be run with standard malloc/free.  The collector can
64       be compiled for thread-safe operation.  Unlike standard malloc,  it  is
65       safe  to  call malloc after a previous malloc call was interrupted by a
66       signal, provided the original malloc call is not resumed.
67
68       The collector may, on rare occasion produce warning messages.  On  UNIX
69       machines  these  appear  on  stderr.  Warning messages can be filtered,
70       redirected, or ignored with GC_set_warn_proc This  is  recommended  for
71       production code.  See gc.h for details.
72
73       Fully  portable  code  should call GC_INIT from the main program before
74       making any other GC calls.  On most platforms this does nothing and the
75       collector  is  initialized  on  first use.  On a few platforms explicit
76       initialization is necessary.  And it can never hurt.
77
78       Debugging versions of many  of  the  above  routines  are  provided  as
79       macros.   Their  names  are  identical to the above, but consist of all
80       capital letters.  If GC_DEBUG is defined before gc.h is included, these
81       routines  do  additional checking, and allow the leak detecting version
82       of the collector to  produce  slightly  more  useful  output.   Without
83       GC_DEBUG defined, they behave exactly like the lower-case versions.
84
85       On  some  machines,  collection will be performed incrementally after a
86       call to GC_enable_incremental.   This  may  temporarily  write  protect
87       pages  in  the  heap.   See the README file for more information on how
88       this interacts with system calls that write to the heap.
89
90       Other facilities not discussed here include limited facilities to  sup‐
91       port incremental collection on machines without appropriate VM support,
92       provisions for providing more explicit object layout information to the
93       garbage  collector,  more direct support for ``weak'' pointers, support
94       for ``abortable'' garbage collections during idle time, etc.
95

SEE ALSO

97       The README and gc.h files in the distribution.  More  detailed  defini‐
98       tions of the functions exported by the collector are given there.  (The
99       above list is not complete.)
100
101       The web site at http://www.hpl.hp.com/personal/Hans_Boehm/gc .
102
103       Boehm, H., and M. Weiser, "Garbage Collection in an Uncooperative Envi‐
104       ronment", Software Practice & Experience, September 1988, pp. 807-820.
105
106       The malloc(3) man page.
107

AUTHOR

109       Hans-J.  Boehm  (Hans.Boehm@hp.com).   Some  of the code was written by
110       others, most notably Alan Demers.
111
112
113
114                                2 October 2003                   GC_MALLOC(1L)
Impressum