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