Debian Codegraph @

external/bdwgc/doc/gcinterface.md

raw
1 # C/C++ Interface
2
3 On many platforms, a single-threaded garbage collector library can be built
4 to act as a plug-in `malloc` replacement. (Build with
5 `-DREDIRECT_MALLOC=GC_malloc -DIGNORE_FREE`.) This is often the best way to
6 deal with third-party libraries which leak or prematurely free objects.
7 `-DREDIRECT_MALLOC=GC_malloc` is intended primarily as an easy way to adapt
8 old code, not for new development.
9
10 New code should use the interface discussed below.
11
12 Code must be linked against the GC library. On most UNIX platforms, depending
13 on how the collector is built, this will be `gc.a` or `libgc.{a,so}`.
14
15 The following describes the standard C interface to the garbage collector.
16 It is not a complete definition of the interface. It describes only the most
17 commonly used functionality, approximately in decreasing order of frequency
18 of use. The full interface is described in `gc.h` file.
19
20 Clients should include `gc.h` (i.e., not `gc_config_macros.h`,
21 `gc_pthread_redirects.h`, `gc_version.h`). In the case of multi-threaded code,
22 `gc.h` should be included after the threads header file, and after defining
23 `GC_THREADS` macro. The header file `gc.h` must be included in files that use
24 either GC or threads primitives, since threads primitives will be redefined
25 to cooperate with the GC on many platforms.
26
27 Thread users should also be aware that on many platforms objects reachable
28 only from thread-local variables may be prematurely reclaimed. Thus objects
29 pointed to by thread-local variables should also be pointed to by a globally
30 visible data structure. (This is viewed as a bug, but as one that
31 is exceedingly hard to fix without some `libc` hooks.)
32
33 **void * `GC_MALLOC`(size_t _nbytes_)** - Allocates and clears _nbytes_
34 of storage. Requires (amortized) time proportional to _nbytes_. The resulting
35 object will be automatically deallocated when unreferenced. References from
36 objects allocated with the system malloc are usually not considered by the
37 collector. (See `GC_MALLOC_UNCOLLECTABLE`, however. Building the collector
38 with `-DREDIRECT_MALLOC=GC_malloc_uncollectable` is often a way around this.)
39 `GC_MALLOC` is a macro which invokes `GC_malloc` by default or, if `GC_DEBUG`
40 is defined before `gc.h` is included, a debugging version that checks
41 occasionally for overwrite errors, and the like.
42
43 **void * `GC_MALLOC_ATOMIC`(size_t _nbytes_)** - Allocates _nbytes_
44 of storage. Requires (amortized) time proportional to _nbytes_. The resulting
45 object will be automatically deallocated when unreferenced. The client
46 promises that the resulting object will never contain any pointers. The memory
47 is not cleared. This is the preferred way to allocate strings, floating point
48 arrays, bitmaps, etc. More precise information about pointer locations can be
49 communicated to the collector using the interface in `gc_typed.h`.
50
51 **void * `GC_MALLOC_UNCOLLECTABLE`(size_t _nbytes_)** - Identical
52 to `GC_MALLOC`, except that the resulting object is not automatically
53 deallocated. Unlike the system-provided `malloc`, the collector does scan the
54 object for pointers to garbage-collectible memory, even if the block itself
55 does not appear to be reachable. (Objects allocated in this way are
56 effectively treated as roots by the collector.)
57
58 **void * `GC_REALLOC`(void * _old_, size_t _new_size_)** - Allocate a new
59 object of the indicated size and copy (a prefix of) the old object into the
60 new object. The old object is reused in place if convenient. If the original
61 object was allocated with `GC_MALLOC_ATOMIC`, the new object is subject to the
62 same constraints. If it was allocated as an uncollectible object, then the new
63 object is uncollectible, and the old object (if different) is deallocated.
64
65 **void `GC_FREE`(void * _dead_)** - Explicitly deallocate an object. Typically
66 not useful for small collectible objects.
67
68 **void * `GC_MALLOC_IGNORE_OFF_PAGE`(size_t _nbytes_)** and
69 **void * `GC_MALLOC_ATOMIC_IGNORE_OFF_PAGE`(size_t _nbytes_)** - Analogous
70 to `GC_MALLOC` and `GC_MALLOC_ATOMIC`, respectively, except that the client
71 guarantees that as long as the resulting object is of use, a pointer
72 is maintained to someplace inside the first 512 bytes of the object. This
73 pointer should be declared volatile to avoid interference from compiler
74 optimizations. (Other nonvolatile pointers to the object may exist as well.)
75 This is the preferred way to allocate objects that are likely to be
76 more than 100 KB in size. It greatly reduces the risk that such objects will
77 be accidentally retained when they are no longer needed. Thus space usage may
78 be significantly reduced.
79
80 **void `GC_INIT()`** - On some platforms, it is necessary to invoke this _from
81 the main executable_, _not from a dynamic library_, before the initial
82 invocation of a GC routine. It is recommended that this be done in portable
83 code, though we try to ensure that it expands to a no-op on as many platforms
84 as possible. In GC v7.0, it was required if thread-local allocation is enabled
85 in the collector build, and `malloc` is not redirected to `GC_malloc`.
86
87 **void `GC_gcollect`(void)** - Explicitly force a garbage collection.
88
89 **void `GC_enable_incremental`(void)** - Cause the garbage collector
90 to perform a small amount of work every few invocations of `GC_MALLOC` or the
91 like, instead of performing an entire collection at once. This is likely
92 to increase total running time. It will improve response on a platform that
93 either has suitable support in the garbage collector (Linux and most Unix
94 versions, Win32 if the collector was suitably built). On many platforms this
95 interacts poorly with system calls that write to the garbage collected heap.
96
97 **void `GC_set_warn_proc`(GC_warn_proc)** - Replace the default procedure
98 used by the collector to print warnings. The collector may otherwise
99 write to `stderr`, most commonly because `GC_malloc` was used in a situation
100 in which `GC_malloc_ignore_off_page` would have been more appropriate. See
101 `gc.h` for details.
102
103 **void `GC_REGISTER_FINALIZER`(...)** - Register a function to be called when
104 an object becomes inaccessible. This is often useful as a backup method for
105 releasing system resources (e.g. closing files) when the object referencing
106 them becomes inaccessible. It is not an acceptable method to perform actions
107 that must be performed in a timely fashion. See `gc.h` for details of the
108 interface. See also [here](finalization.md) for a more detailed discussion
109 of the design.
110
111 Note that an object may become inaccessible before client code is done
112 operating on objects referenced by its fields. Suitable synchronization
113 is usually required. See
114 [here](http://portal.acm.org/citation.cfm?doid=604131.604153)
115 or [here](http://www.hpl.hp.com/techreports/2002/HPL-2002-335.html) for
116 details.
117
118 If you are concerned with multiprocessor performance and scalability, you
119 should consider enabling and using thread local allocation.
120
121 If your platform supports it, you should build the collector with parallel
122 marking support (`-DPARALLEL_MARK`); configure has it on by default.
123
124 If the collector is used in an environment in which pointer location
125 information for heap objects is easily available, this can be passed on to the
126 collector using the interfaces in either `gc_typed.h` or `gc_gcj.h`.
127
128 The collector distribution also includes a **string package** that takes
129 advantage of the collector. For details see `cord.h` file.
130
131 ## C++ Interface
132
133 The C++ interface is implemented as a thin layer on the C interface.
134 Unfortunately, this thin layer appears to be very sensitive to variations
135 in C++ implementations, particularly since it tries to replace the global
136 `::new` operator, something that appears to not be well-standardized. Your
137 platform may need minor adjustments in this layer (`gc_cpp.cc`, `gc_cpp.h`,
138 and possibly `gc_allocator.h`). Such changes do not require understanding
139 of collector internals, though they may require a good understanding of your
140 platform. (Patches enhancing portability are welcome. But it is easy to break
141 one platform by fixing another.)
142
143 Usage of the collector from C++ is also complicated by the fact that there are
144 many _standard_ ways to allocate memory in C++. The default `::new` operator,
145 default `malloc`, and default STL allocators allocate memory that is not
146 garbage collected, and is not normally _traced_ by the collector. This means
147 that any pointers in memory allocated by these default allocators will not be
148 seen by the collector. Garbage-collectible memory referenced only by pointers
149 stored in such default-allocated objects is likely to be reclaimed prematurely
150 by the collector.
151
152 It is the programmers responsibility to ensure that garbage-collectible memory
153 is referenced by pointers stored in one of
154
155 * Program variables
156 * Garbage-collected objects
157 * Uncollected but _traceable_ objects
158
159 Traceable objects are not necessarily reclaimed by the collector, but are
160 scanned for pointers to collectible objects. They are usually allocated
161 by `GC_MALLOC_UNCOLLECTABLE`, as described above, and through some interfaces
162 described below.
163
164 On most platforms, the collector may not trace correctly from in-flight
165 exception objects. Thus objects thrown as exceptions should only point
166 to otherwise reachable memory. This is another bug whose proper repair
167 requires platform hooks.
168
169 The easiest way to ensure that collectible objects are properly referenced
170 is to allocate only collectible objects. This requires that every allocation
171 go through one of the following interfaces, each one of which replaces
172 a standard C++ allocation mechanism. Note that this requires that all STL
173 containers be explicitly instantiated with `gc_allocator`.
174
175 ### STL allocators
176
177 Recent versions of the collector include a hopefully standard-conforming
178 allocator implementation in `gc_allocator.h`. It defines `traceable_allocator`
179 and `gc_allocator` which may be used either directly to allocate memory or to
180 instantiate container templates. The former allocates uncollectible but traced
181 memory. The latter allocates garbage-collected memory.
182
183 These should work with any fully standard-conforming C++ compiler.
184
185 Users of the [SGI extended STL](http://www.sgi.com/tech/stl) or its
186 derivatives (including most g++ versions) may instead be able to include
187 `new_gc_alloc.h` before including STL header files. This is increasingly
188 discouraged.
189
190 This defines SGI-style allocators
191
192 * `alloc`
193 * `single_client_alloc`
194 * `gc_alloc`
195 * `single_client_gc_alloc`
196
197 The first two allocate uncollectible but traced memory, while the second two
198 allocate collectible memory. The `single_client_...` versions are not safe for
199 concurrent access by multiple threads, but are faster.
200
201 See sample code [here](http://www.hboehm.info/gc/gc_alloc_exC.txt).
202
203 ### Class inheritance based interface for new-based allocation
204
205 Users may include `gc_cpp.h` and then cause members of classes to be allocated
206 in garbage collectible memory by having those classes inherit from class `gc`.
207 For details see `gc_cpp.h` file.
208
209 Linking against `libgccpp` in addition to the `gc` library overrides `::new`
210 (and friends) to allocate traceable memory but uncollectible memory, making
211 it safe to refer to collectible objects from the resulting memory.
212
213 ## C interface
214
215 It is also possible to use the C interface from `gc.h` directly. On platforms
216 which use `malloc` to implement `::new`, it should usually be possible to use
217 a version of the collector that has been compiled as a `malloc` replacement.
218 It is also possible to replace `::new` and other allocation functions
219 suitably, as is done by `libgccpp`.
220
221 Note that user-implemented small-block allocation often works poorly with
222 an underlying garbage-collected large block allocator, since the collector has
223 to view all objects accessible from the user's free list as reachable. This
224 is likely to cause problems if `GC_MALLOC` is used with something like the
225 original HP version of STL. This approach works well with the SGI versions
226 of the STL only if the `malloc_alloc` allocator is used.