Debian Codegraph @

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