1BDWGC(3) Library Functions Manual BDWGC(3)
2
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
12 #include <gc.h>
13 void * GC_malloc(size_t size);
14 void * GC_malloc_atomic(size_t size);
15 void GC_free(void *ptr);
16 void * GC_realloc(void *ptr, size_t size);
17 void GC_enable_incremental(void);
18 void * GC_malloc_ignore_off_page(size_t size);
19 void * GC_malloc_atomic_ignore_off_page(size_t size);
20 void GC_set_warn_proc(void (*proc)(char *, GC_word));
21 cc ... -lgc
23
25 GC_malloc and GC_free are plug-in replacements for standard malloc and
26 free. However, GC_malloc will attempt to reclaim inaccessible space
27 automatically by invoking a conservative garbage collector at appropri‐
28 ate points. The collector traverses all data structures accessible by
29 following pointers from the machines registers, stack(s), data, and bss
30 segments. Inaccessible structures will be reclaimed. A machine word
31 is considered to be a valid pointer if it is an address inside an ob‐
32 ject allocated by GC_malloc or friends.
33 In most cases it is preferable to call the macros GC_MALLOC, GC_FREE,
35 etc. instead of calling GC_malloc and friends directly. This allows
36 debugging versions of the routines to be substituted by defining GC_DE‐
37 BUG before including gc.h.
38 See the documentation in the include files gc_cpp.h and gc_allocator.h,
40 as well as the gcinterface.md file in the distribution, for an alter‐
41 nate, C++ specific interface to the garbage collector. Note that C++
42 programs generally need to be careful to ensure that all allocated mem‐
43 ory (whether via new, malloc, or STL allocators) that may point to
44 garbage collected memory is either itself garbage collected, or at
45 least traced by the collector.
46 Unlike the standard implementations of malloc, GC_malloc clears the
48 newly allocated storage. GC_malloc_atomic does not. Furthermore, it
49 informs the collector that the resulting object will never contain any
50 pointers, and should therefore not be scanned by the collector.
51 GC_free can be used to deallocate objects, but its use is optional, and
53 generally discouraged. GC_realloc has the standard realloc semantics.
54 It preserves pointer-free-ness. GC_register_finalizer allows for reg‐
55 istration of functions that are invoked when an object becomes inacces‐
56 sible.
57 The garbage collector tries to avoid allocating memory at locations
59 that already appear to be referenced before allocation. (Such apparent
60 ``pointers'' are usually large integers and the like that just happen
61 to look like an address.) This may make it hard to allocate very large
62 objects. An attempt to do so may generate a warning.
63 GC_malloc_ignore_off_page and GC_malloc_atomic_ignore_off_page inform
65 the collector that the client code will always maintain a pointer to
66 near the beginning of the object (within the first 512 bytes), and that
67 pointers beyond that can be ignored by the collector. This makes it
68 much easier for the collector to place large objects. These are recom‐
69 mended for large object allocation. (Objects expected to be > ~100 KB
70 should be allocated this way.)
71 It is also possible to use the collector to find storage leaks in pro‐
73 grams destined to be run with standard malloc/free. The collector can
74 be compiled for thread-safe operation. Unlike standard malloc, it is
75 safe to call malloc after a previous malloc call was interrupted by a
76 signal, provided the original malloc call is not resumed.
77 The collector may, on rare occasion, produce warning messages. On UNIX
79 machines these appear on stderr. Warning messages can be filtered,
80 redirected, or ignored with GC_set_warn_proc This is recommended for
81 production code. See gc.h for details.
82 Fully portable code should call GC_INIT from the primordial thread of
84 the main program before making any other GC calls. On most platforms
85 this does nothing and the collector is initialized on first use. On a
86 few platforms explicit initialization is necessary. And it can never
87 hurt.
88 Debugging versions of many of the above routines are provided as
90 macros. Their names are identical to the above, but consist of all
91 capital letters. If GC_DEBUG is defined before gc.h is included, these
92 routines do additional checking, and allow the leak detecting version
93 of the collector to produce slightly more useful output. Without
94 GC_DEBUG defined, they behave exactly like the lower-case versions.
95 On some machines, collection will be performed incrementally after a
97 call to GC_enable_incremental. This may temporarily write protect
98 pages in the heap. See the README file for more information on how
99 this interacts with system calls that write to the heap.
100 Other facilities not discussed here include limited facilities to sup‐
102 port incremental collection on machines without appropriate VM support,
103 provisions for providing more explicit object layout information to the
104 garbage collector, more direct support for ``weak'' pointers, support
105 for ``abortable'' garbage collections during idle time, etc.
106
108 The README and gc.h files in the distribution. More detailed defini‐
109 tions of the functions exported by the collector are given there. (The
110 above list is not complete.)
111 The web site at http://www.hboehm.info/gc/ (or https://github.com/iv‐
113 mai/bdwgc/).
114 Boehm, H., and M. Weiser, "Garbage Collection in an Uncooperative Envi‐
116 ronment", "Software Practice & Experience", September 1988, pp.
117 807-820.
118 The malloc(3) man page.
120
122 Hans-J. Boehm (boehm@acm.org). Some of the code was written by others
123 (see the AUTHORS file for the details), most notably by Alan Demers,
124 and, recently, Ivan Maidanski.
125 26 Mar 2019 BDWGC(3)