1BDWGC(3)                   Library Functions Manual                   BDWGC(3)
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 ... -lgc
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 files gc_cpp.h and gc_allocator.h,
35       as  well  as the gcinterface.md file in the distribution, for an alter‐
36       nate, C++ specific interface to the garbage collector.  Note  that  C++
37       programs generally need to be careful to ensure that all allocated mem‐
38       ory (whether via new, malloc, or STL  allocators)  that  may  point  to
39       garbage  collected  memory  is  either  itself garbage collected, or at
40       least traced by the collector.
41
42       Unlike the standard implementations of  malloc,  GC_malloc  clears  the
43       newly  allocated  storage.  GC_malloc_atomic does not.  Furthermore, it
44       informs the collector that the resulting object will never contain  any
45       pointers, and should therefore not be scanned by the collector.
46
47       GC_free can be used to deallocate objects, but its use is optional, and
48       generally discouraged.  GC_realloc has the standard realloc  semantics.
49       It  preserves pointer-free-ness.  GC_register_finalizer allows for reg‐
50       istration of functions that are invoked when an object becomes inacces‐
51       sible.
52
53       The  garbage  collector  tries  to avoid allocating memory at locations
54       that already appear to be referenced before allocation.  (Such apparent
55       ``pointers''  are  usually large integers and the like that just happen
56       to look like an address.)  This may make it hard to allocate very large
57       objects.  An attempt to do so may generate a warning.
58
59       GC_malloc_ignore_off_page  and  GC_malloc_atomic_ignore_off_page inform
60       the collector that the client code will always maintain  a  pointer  to
61       near the beginning of the object (within the first 512 bytes), and that
62       pointers beyond that can be ignored by the collector.   This  makes  it
63       much easier for the collector to place large objects.  These are recom‐
64       mended for large object allocation.  (Objects  expected  to  be  larger
65       than about 100KBytes should be allocated this way.)
66
67       It  is also possible to use the collector to find storage leaks in pro‐
68       grams destined to be run with standard malloc/free.  The collector  can
69       be  compiled  for thread-safe operation.  Unlike standard malloc, it is
70       safe to call malloc after a previous malloc call was interrupted  by  a
71       signal, provided the original malloc call is not resumed.
72
73       The  collector may, on rare occasion produce warning messages.  On UNIX
74       machines these appear on stderr.  Warning  messages  can  be  filtered,
75       redirected,  or  ignored  with GC_set_warn_proc This is recommended for
76       production code.  See gc.h for details.
77
78       Fully portable code should call GC_INIT from the  main  program  before
79       making any other GC calls.  On most platforms this does nothing and the
80       collector is initialized on first use.  On  a  few  platforms  explicit
81       initialization is necessary.  And it can never hurt.
82
83       Debugging  versions  of  many  of  the  above  routines are provided as
84       macros.  Their names are identical to the above,  but  consist  of  all
85       capital letters.  If GC_DEBUG is defined before gc.h is included, these
86       routines do additional checking, and allow the leak  detecting  version
87       of  the  collector  to  produce  slightly  more useful output.  Without
88       GC_DEBUG defined, they behave exactly like the lower-case versions.
89
90       On some machines, collection will be performed  incrementally  after  a
91       call  to  GC_enable_incremental.   This  may  temporarily write protect
92       pages in the heap.  See the README file for  more  information  on  how
93       this interacts with system calls that write to the heap.
94
95       Other  facilities not discussed here include limited facilities to sup‐
96       port incremental collection on machines without appropriate VM support,
97       provisions for providing more explicit object layout information to the
98       garbage collector, more direct support for ``weak''  pointers,  support
99       for ``abortable'' garbage collections during idle time, etc.
100

SEE ALSO

102       The  README  and gc.h files in the distribution.  More detailed defini‐
103       tions of the functions exported by the collector are given there.  (The
104       above list is not complete.)
105
106       The      web      site      at      http://www.hboehm.info/gc/      (or
107       https://github.com/ivmai/bdwgc/).
108
109       Boehm, H., and M. Weiser, "Garbage Collection in an Uncooperative Envi‐
110       ronment",   "Software  Practice  &  Experience",  September  1988,  pp.
111       807-820.
112
113       The malloc(3) man page.
114

AUTHOR

116       Hans-J. Boehm (boehm@acm.org).  Some of the code was written by  others
117       (see  the  AUTHORS  file for the details), most notably by Alan Demers,
118       and, recently, Ivan Maidanski.
119
120
121
122                                  15 Aug 2018                         BDWGC(3)
Impressum