]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
1 | Copyright (c) 1988, 1989 Hans-J. Boehm, Alan J. Demers |
2 | Copyright (c) 1991-1996 by Xerox Corporation. All rights reserved. | |
3 | Copyright (c) 1996-1999 by Silicon Graphics. All rights reserved. | |
4 | Copyright (c) 1999-2005 Hewlett-Packard Development Company, L.P. | |
5 | ||
6 | The file linux_threads.c is also | |
7 | Copyright (c) 1998 by Fergus Henderson. All rights reserved. | |
8 | ||
9 | The files Makefile.am, and configure.in are | |
10 | Copyright (c) 2001 by Red Hat Inc. All rights reserved. | |
11 | ||
12 | Several files supporting GNU-style builds are copyrighted by the Free | |
13 | Software Foundation, and carry a different license from that given | |
14 | below. The files included in the libatomic_ops distribution (included | |
15 | here) use either the license below, or a similar MIT-style license, | |
16 | or, for some files not actually used by the garbage-collector library, the | |
17 | GPL. | |
18 | ||
19 | THIS MATERIAL IS PROVIDED AS IS, WITH ABSOLUTELY NO WARRANTY EXPRESSED | |
20 | OR IMPLIED. ANY USE IS AT YOUR OWN RISK. | |
21 | ||
22 | Permission is hereby granted to use or copy this program | |
23 | for any purpose, provided the above notices are retained on all copies. | |
24 | Permission to modify the code and to distribute modified code is granted, | |
25 | provided the above notices are retained, and a notice that the code was | |
26 | modified is included with the above copyright notice. | |
27 | ||
28 | A few of the files needed to use the GNU-style build procedure come with | |
29 | slightly different licenses, though they are all similar in spirit. A few | |
30 | are GPL'ed, but with an exception that should cover all uses in the | |
31 | collector. (If you are concerned about such things, I recommend you look | |
32 | at the notice in config.guess or ltmain.sh.) | |
33 | ||
34 | This is version 7.0 of a conservative garbage collector for C and C++. | |
35 | ||
36 | You might find a more recent version of this at | |
37 | ||
38 | http://www.hpl.hp.com/personal/Hans_Boehm/gc | |
39 | ||
40 | OVERVIEW | |
41 | ||
42 | This is intended to be a general purpose, garbage collecting storage | |
43 | allocator. The algorithms used are described in: | |
44 | ||
45 | Boehm, H., and M. Weiser, "Garbage Collection in an Uncooperative Environment", | |
46 | Software Practice & Experience, September 1988, pp. 807-820. | |
47 | ||
48 | Boehm, H., A. Demers, and S. Shenker, "Mostly Parallel Garbage Collection", | |
49 | Proceedings of the ACM SIGPLAN '91 Conference on Programming Language Design | |
50 | and Implementation, SIGPLAN Notices 26, 6 (June 1991), pp. 157-164. | |
51 | ||
52 | Boehm, H., "Space Efficient Conservative Garbage Collection", Proceedings | |
53 | of the ACM SIGPLAN '91 Conference on Programming Language Design and | |
54 | Implementation, SIGPLAN Notices 28, 6 (June 1993), pp. 197-206. | |
55 | ||
56 | Boehm H., "Reducing Garbage Collector Cache Misses", Proceedings of the | |
57 | 2000 International Symposium on Memory Management. | |
58 | ||
59 | Possible interactions between the collector and optimizing compilers are | |
60 | discussed in | |
61 | ||
62 | Boehm, H., and D. Chase, "A Proposal for GC-safe C Compilation", | |
63 | The Journal of C Language Translation 4, 2 (December 1992). | |
64 | ||
65 | and | |
66 | ||
67 | Boehm H., "Simple GC-safe Compilation", Proceedings | |
68 | of the ACM SIGPLAN '96 Conference on Programming Language Design and | |
69 | Implementation. | |
70 | ||
71 | (Some of these are also available from | |
72 | http://www.hpl.hp.com/personal/Hans_Boehm/papers/, among other places.) | |
73 | ||
74 | Unlike the collector described in the second reference, this collector | |
75 | operates either with the mutator stopped during the entire collection | |
76 | (default) or incrementally during allocations. (The latter is supported | |
77 | on fewer machines.) On the most common platforms, it can be built | |
78 | with or without thread support. On a few platforms, it can take advantage | |
79 | of a multiprocessor to speed up garbage collection. | |
80 | ||
81 | Many of the ideas underlying the collector have previously been explored | |
82 | by others. Notably, some of the run-time systems developed at Xerox PARC | |
83 | in the early 1980s conservatively scanned thread stacks to locate possible | |
84 | pointers (cf. Paul Rovner, "On Adding Garbage Collection and Runtime Types | |
85 | to a Strongly-Typed Statically Checked, Concurrent Language" Xerox PARC | |
86 | CSL 84-7). Doug McIlroy wrote a simpler fully conservative collector that | |
87 | was part of version 8 UNIX (tm), but appears to not have received | |
88 | widespread use. | |
89 | ||
90 | Rudimentary tools for use of the collector as a leak detector are included | |
91 | (see http://www.hpl.hp.com/personal/Hans_Boehm/gc/leak.html), | |
92 | as is a fairly sophisticated string package "cord" that makes use of the | |
93 | collector. (See doc/README.cords and H.-J. Boehm, R. Atkinson, and M. Plass, | |
94 | "Ropes: An Alternative to Strings", Software Practice and Experience 25, 12 | |
95 | (December 1995), pp. 1315-1330. This is very similar to the "rope" package | |
96 | in Xerox Cedar, or the "rope" package in the SGI STL or the g++ distribution.) | |
97 | ||
98 | Further collector documantation can be found at | |
99 | ||
100 | http://www.hpl.hp.com/personal/Hans_Boehm/gc | |
101 | ||
102 | ||
103 | GENERAL DESCRIPTION | |
104 | ||
105 | This is a garbage collecting storage allocator that is intended to be | |
106 | used as a plug-in replacement for C's malloc. | |
107 | ||
108 | Since the collector does not require pointers to be tagged, it does not | |
109 | attempt to ensure that all inaccessible storage is reclaimed. However, | |
110 | in our experience, it is typically more successful at reclaiming unused | |
111 | memory than most C programs using explicit deallocation. Unlike manually | |
112 | introduced leaks, the amount of unreclaimed memory typically stays | |
113 | bounded. | |
114 | ||
115 | In the following, an "object" is defined to be a region of memory allocated | |
116 | by the routines described below. | |
117 | ||
118 | Any objects not intended to be collected must be pointed to either | |
119 | from other such accessible objects, or from the registers, | |
120 | stack, data, or statically allocated bss segments. Pointers from | |
121 | the stack or registers may point to anywhere inside an object. | |
122 | The same is true for heap pointers if the collector is compiled with | |
123 | ALL_INTERIOR_POINTERS defined, or GC_all_interior_pointers is otherwise | |
124 | set, as is now the default. | |
125 | ||
126 | Compiling without ALL_INTERIOR_POINTERS may reduce accidental retention | |
127 | of garbage objects, by requiring pointers from the heap to to the beginning | |
128 | of an object. But this no longer appears to be a significant | |
129 | issue for most programs occupying a small fraction of the possible | |
130 | address space. | |
131 | ||
132 | There are a number of routines which modify the pointer recognition | |
133 | algorithm. GC_register_displacement allows certain interior pointers | |
134 | to be recognized even if ALL_INTERIOR_POINTERS is nor defined. | |
135 | GC_malloc_ignore_off_page allows some pointers into the middle of large objects | |
136 | to be disregarded, greatly reducing the probablility of accidental | |
137 | retention of large objects. For most purposes it seems best to compile | |
138 | with ALL_INTERIOR_POINTERS and to use GC_malloc_ignore_off_page if | |
139 | you get collector warnings from allocations of very large objects. | |
140 | See README.debugging for details. | |
141 | ||
142 | WARNING: pointers inside memory allocated by the standard "malloc" are not | |
143 | seen by the garbage collector. Thus objects pointed to only from such a | |
144 | region may be prematurely deallocated. It is thus suggested that the | |
145 | standard "malloc" be used only for memory regions, such as I/O buffers, that | |
146 | are guaranteed not to contain pointers to garbage collectable memory. | |
147 | Pointers in C language automatic, static, or register variables, | |
148 | are correctly recognized. (Note that GC_malloc_uncollectable has semantics | |
149 | similar to standard malloc, but allocates objects that are traced by the | |
150 | collector.) | |
151 | ||
152 | WARNING: the collector does not always know how to find pointers in data | |
153 | areas that are associated with dynamic libraries. This is easy to | |
154 | remedy IF you know how to find those data areas on your operating | |
155 | system (see GC_add_roots). Code for doing this under SunOS, IRIX 5.X and 6.X, | |
156 | HP/UX, Alpha OSF/1, Linux, and win32 is included and used by default. (See | |
157 | README.win32 for win32 details.) On other systems pointers from dynamic | |
158 | library data areas may not be considered by the collector. | |
159 | If you're writing a program that depends on the collector scanning | |
160 | dynamic library data areas, it may be a good idea to include at least | |
161 | one call to GC_is_visible() to ensure that those areas are visible | |
162 | to the collector. | |
163 | ||
164 | Note that the garbage collector does not need to be informed of shared | |
165 | read-only data. However if the shared library mechanism can introduce | |
166 | discontiguous data areas that may contain pointers, then the collector does | |
167 | need to be informed. | |
168 | ||
169 | Signal processing for most signals may be deferred during collection, | |
170 | and during uninterruptible parts of the allocation process. | |
171 | Like standard ANSI C mallocs, by default it is unsafe to invoke | |
172 | malloc (and other GC routines) from a signal handler while another | |
173 | malloc call may be in progress. Removing -DNO_SIGNALS from Makefile | |
174 | attempts to remedy that. But that may not be reliable with a compiler that | |
175 | substantially reorders memory operations inside GC_malloc. | |
176 | ||
177 | The allocator/collector can also be configured for thread-safe operation. | |
178 | (Full signal safety can also be achieved, but only at the cost of two system | |
179 | calls per malloc, which is usually unacceptable.) | |
180 | WARNING: the collector does not guarantee to scan thread-local storage | |
181 | (e.g. of the kind accessed with pthread_getspecific()). The collector | |
182 | does scan thread stacks, though, so generally the best solution is to | |
183 | ensure that any pointers stored in thread-local storage are also | |
184 | stored on the thread's stack for the duration of their lifetime. | |
185 | (This is arguably a longstanding bug, but it hasn't been fixed yet.) | |
186 | ||
187 | INSTALLATION AND PORTABILITY | |
188 | ||
189 | As distributed, the collector operates silently | |
190 | In the event of problems, this can usually be changed by defining the | |
191 | GC_PRINT_STATS or GC_PRINT_VERBOSE_STATS environment variables. This | |
192 | will result in a few lines of descriptive output for each collection. | |
193 | (The given statistics exhibit a few peculiarities. | |
194 | Things don't appear to add up for a variety of reasons, most notably | |
195 | fragmentation losses. These are probably much more significant for the | |
196 | contrived program "test.c" than for your application.) | |
197 | ||
198 | On most Un*x-like platforms, the collector can be built either using a | |
199 | GNU autoconf-based build infrastructure (type "configure; make" in the | |
200 | simplest case), or with a classic makefile by itself (type | |
201 | "cp Makefile.direct Makefile; make"). Here we focus on the latter option. | |
202 | On other platforms, typically only the latter option is available, though | |
203 | with a different supplied Makefile.) | |
204 | ||
205 | Typing "make test" nstead of "make" will automatically build the collector | |
206 | and then run setjmp_test and gctest. Setjmp_test will give you information | |
207 | about configuring the collector, which is useful primarily if you have | |
208 | a machine that's not already supported. Gctest is a somewhat superficial | |
209 | test of collector functionality. Failure is indicated by a core dump or | |
210 | a message to the effect that the collector is broken. Gctest takes about | |
211 | a second to two to run on reasonable 2007 vintage desktops. | |
212 | It may use up to about 30MB of memory. (The | |
213 | multi-threaded version will use more. 64-bit versions may use more.) | |
214 | "Make test" will also, as its last step, attempt to build and test the | |
215 | "cord" string library.) | |
216 | ||
217 | The Makefile will generate a library gc.a which you should link against. | |
218 | Typing "make cords" will add the cord library to gc.a. | |
219 | Note that this requires an ANSI C compiler. | |
220 | ||
221 | It is suggested that if you need to replace a piece of the collector | |
222 | (e.g. GC_mark_rts.c) you simply list your version ahead of gc.a on the | |
223 | ld command line, rather than replacing the one in gc.a. (This will | |
224 | generate numerous warnings under some versions of AIX, but it still | |
225 | works.) | |
226 | ||
227 | All include files that need to be used by clients will be put in the | |
228 | include subdirectory. (Normally this is just gc.h. "Make cords" adds | |
229 | "cord.h" and "ec.h".) | |
230 | ||
231 | The collector currently is designed to run essentially unmodified on | |
232 | machines that use a flat 32-bit or 64-bit address space. | |
233 | That includes the vast majority of Workstations and X86 (X >= 3) PCs. | |
234 | (The list here was deleted because it was getting too long and constantly | |
235 | out of date.) | |
236 | ||
237 | In a few cases (Amiga, OS/2, Win32, MacOS) a separate makefile | |
238 | or equivalent is supplied. Many of these have separate README.system | |
239 | files. | |
240 | ||
241 | Dynamic libraries are completely supported only under SunOS/Solaris, | |
242 | (and even that support is not functional on the last Sun 3 release), | |
243 | Linux, FreeBSD, NetBSD, IRIX 5&6, HP/UX, Win32 (not Win32S) and OSF/1 | |
244 | on DEC AXP machines plus perhaps a few others listed near the top | |
245 | of dyn_load.c. On other machines we recommend that you do one of | |
246 | the following: | |
247 | ||
248 | 1) Add dynamic library support (and send us the code). | |
249 | 2) Use static versions of the libraries. | |
250 | 3) Arrange for dynamic libraries to use the standard malloc. | |
251 | This is still dangerous if the library stores a pointer to a | |
252 | garbage collected object. But nearly all standard interfaces | |
253 | prohibit this, because they deal correctly with pointers | |
254 | to stack allocated objects. (Strtok is an exception. Don't | |
255 | use it.) | |
256 | ||
257 | In all cases we assume that pointer alignment is consistent with that | |
258 | enforced by the standard C compilers. If you use a nonstandard compiler | |
259 | you may have to adjust the alignment parameters defined in gc_priv.h. | |
260 | Note that this may also be an issue with packed records/structs, if those | |
261 | enforce less alignment for pointers. | |
262 | ||
263 | A port to a machine that is not byte addressed, or does not use 32 bit | |
264 | or 64 bit addresses will require a major effort. A port to plain MSDOS | |
265 | or win16 is hard. | |
266 | ||
267 | For machines not already mentioned, or for nonstandard compilers, | |
268 | some porting suggestions are provided in the "porting.html" file. | |
269 | ||
270 | THE C INTERFACE TO THE ALLOCATOR | |
271 | ||
272 | The following routines are intended to be directly called by the user. | |
273 | Note that usually only GC_malloc is necessary. GC_clear_roots and GC_add_roots | |
274 | calls may be required if the collector has to trace from nonstandard places | |
275 | (e.g. from dynamic library data areas on a machine on which the | |
276 | collector doesn't already understand them.) On some machines, it may | |
277 | be desirable to set GC_stacktop to a good approximation of the stack base. | |
278 | (This enhances code portability on HP PA machines, since there is no | |
279 | good way for the collector to compute this value.) Client code may include | |
280 | "gc.h", which defines all of the following, plus many others. | |
281 | ||
282 | 1) GC_malloc(nbytes) | |
283 | - allocate an object of size nbytes. Unlike malloc, the object is | |
284 | cleared before being returned to the user. Gc_malloc will | |
285 | invoke the garbage collector when it determines this to be appropriate. | |
286 | GC_malloc may return 0 if it is unable to acquire sufficient | |
287 | space from the operating system. This is the most probable | |
288 | consequence of running out of space. Other possible consequences | |
289 | are that a function call will fail due to lack of stack space, | |
290 | or that the collector will fail in other ways because it cannot | |
291 | maintain its internal data structures, or that a crucial system | |
292 | process will fail and take down the machine. Most of these | |
293 | possibilities are independent of the malloc implementation. | |
294 | ||
295 | 2) GC_malloc_atomic(nbytes) | |
296 | - allocate an object of size nbytes that is guaranteed not to contain any | |
297 | pointers. The returned object is not guaranteed to be cleared. | |
298 | (Can always be replaced by GC_malloc, but results in faster collection | |
299 | times. The collector will probably run faster if large character | |
300 | arrays, etc. are allocated with GC_malloc_atomic than if they are | |
301 | statically allocated.) | |
302 | ||
303 | 3) GC_realloc(object, new_size) | |
304 | - change the size of object to be new_size. Returns a pointer to the | |
305 | new object, which may, or may not, be the same as the pointer to | |
306 | the old object. The new object is taken to be atomic iff the old one | |
307 | was. If the new object is composite and larger than the original object, | |
308 | then the newly added bytes are cleared (we hope). This is very likely | |
309 | to allocate a new object, unless MERGE_SIZES is defined in gc_priv.h. | |
310 | Even then, it is likely to recycle the old object only if the object | |
311 | is grown in small additive increments (which, we claim, is generally bad | |
312 | coding practice.) | |
313 | ||
314 | 4) GC_free(object) | |
315 | - explicitly deallocate an object returned by GC_malloc or | |
316 | GC_malloc_atomic. Not necessary, but can be used to minimize | |
317 | collections if performance is critical. Probably a performance | |
318 | loss for very small objects (<= 8 bytes). | |
319 | ||
320 | 5) GC_expand_hp(bytes) | |
321 | - Explicitly increase the heap size. (This is normally done automatically | |
322 | if a garbage collection failed to GC_reclaim enough memory. Explicit | |
323 | calls to GC_expand_hp may prevent unnecessarily frequent collections at | |
324 | program startup.) | |
325 | ||
326 | 6) GC_malloc_ignore_off_page(bytes) | |
327 | - identical to GC_malloc, but the client promises to keep a pointer to | |
328 | the somewhere within the first 256 bytes of the object while it is | |
329 | live. (This pointer should nortmally be declared volatile to prevent | |
330 | interference from compiler optimizations.) This is the recommended | |
331 | way to allocate anything that is likely to be larger than 100Kbytes | |
332 | or so. (GC_malloc may result in failure to reclaim such objects.) | |
333 | ||
334 | 7) GC_set_warn_proc(proc) | |
335 | - Can be used to redirect warnings from the collector. Such warnings | |
336 | should be rare, and should not be ignored during code development. | |
337 | ||
338 | 8) GC_enable_incremental() | |
339 | - Enables generational and incremental collection. Useful for large | |
340 | heaps on machines that provide access to page dirty information. | |
341 | Some dirty bit implementations may interfere with debugging | |
342 | (by catching address faults) and place restrictions on heap arguments | |
343 | to system calls (since write faults inside a system call may not be | |
344 | handled well). | |
345 | ||
346 | 9) Several routines to allow for registration of finalization code. | |
347 | User supplied finalization code may be invoked when an object becomes | |
348 | unreachable. To call (*f)(obj, x) when obj becomes inaccessible, use | |
349 | GC_register_finalizer(obj, f, x, 0, 0); | |
350 | For more sophisticated uses, and for finalization ordering issues, | |
351 | see gc.h. | |
352 | ||
353 | The global variable GC_free_space_divisor may be adjusted up from its | |
354 | default value of 4 to use less space and more collection time, or down for | |
355 | the opposite effect. Setting it to 1 or 0 will effectively disable collections | |
356 | and cause all allocations to simply grow the heap. | |
357 | ||
358 | The variable GC_non_gc_bytes, which is normally 0, may be changed to reflect | |
359 | the amount of memory allocated by the above routines that should not be | |
360 | considered as a candidate for collection. Careless use may, of course, result | |
361 | in excessive memory consumption. | |
362 | ||
363 | Some additional tuning is possible through the parameters defined | |
364 | near the top of gc_priv.h. | |
365 | ||
366 | If only GC_malloc is intended to be used, it might be appropriate to define: | |
367 | ||
368 | #define malloc(n) GC_malloc(n) | |
369 | #define calloc(m,n) GC_malloc((m)*(n)) | |
370 | ||
371 | For small pieces of VERY allocation intensive code, gc_inl.h | |
372 | includes some allocation macros that may be used in place of GC_malloc | |
373 | and friends. | |
374 | ||
375 | All externally visible names in the garbage collector start with "GC_". | |
376 | To avoid name conflicts, client code should avoid this prefix, except when | |
377 | accessing garbage collector routines or variables. | |
378 | ||
379 | There are provisions for allocation with explicit type information. | |
380 | This is rarely necessary. Details can be found in gc_typed.h. | |
381 | ||
382 | THE C++ INTERFACE TO THE ALLOCATOR: | |
383 | ||
384 | The Ellis-Hull C++ interface to the collector is included in | |
385 | the collector distribution. If you intend to use this, type | |
386 | "make c++" after the initial build of the collector is complete. | |
387 | See gc_cpp.h for the definition of the interface. This interface | |
388 | tries to approximate the Ellis-Detlefs C++ garbage collection | |
389 | proposal without compiler changes. | |
390 | ||
391 | Very often it will also be necessary to use gc_allocator.h and the | |
392 | allocator declared there to construct STL data structures. Otherwise | |
393 | subobjects of STL data structures wil be allcoated using a system | |
394 | allocator, and objects they refer to may be prematurely collected. | |
395 | ||
396 | USE AS LEAK DETECTOR: | |
397 | ||
398 | The collector may be used to track down leaks in C programs that are | |
399 | intended to run with malloc/free (e.g. code with extreme real-time or | |
400 | portability constraints). To do so define FIND_LEAK in Makefile | |
401 | This will cause the collector to invoke the report_leak | |
402 | routine defined near the top of reclaim.c whenever an inaccessible | |
403 | object is found that has not been explicitly freed. Such objects will | |
404 | also be automatically reclaimed. | |
405 | If all objects are allocated with GC_DEBUG_MALLOC (see next section), then | |
406 | the default version of report_leak will report at least the source file and | |
407 | line number at which the leaked object was allocated. This may sometimes be | |
408 | sufficient. (On a few machines, it will also report a cryptic stack trace. | |
409 | If this is not symbolic, it can somethimes be called into a sympolic stack | |
410 | trace by invoking program "foo" with "callprocs foo". Callprocs is a short | |
411 | shell script that invokes adb to expand program counter values to symbolic | |
412 | addresses. It was largely supplied by Scott Schwartz.) | |
413 | Note that the debugging facilities described in the next section can | |
414 | sometimes be slightly LESS effective in leak finding mode, since in | |
415 | leak finding mode, GC_debug_free actually results in reuse of the object. | |
416 | (Otherwise the object is simply marked invalid.) Also note that the test | |
417 | program is not designed to run meaningfully in FIND_LEAK mode. | |
418 | Use "make gc.a" to build the collector. | |
419 | ||
420 | DEBUGGING FACILITIES: | |
421 | ||
422 | The routines GC_debug_malloc, GC_debug_malloc_atomic, GC_debug_realloc, | |
423 | and GC_debug_free provide an alternate interface to the collector, which | |
424 | provides some help with memory overwrite errors, and the like. | |
425 | Objects allocated in this way are annotated with additional | |
426 | information. Some of this information is checked during garbage | |
427 | collections, and detected inconsistencies are reported to stderr. | |
428 | ||
429 | Simple cases of writing past the end of an allocated object should | |
430 | be caught if the object is explicitly deallocated, or if the | |
431 | collector is invoked while the object is live. The first deallocation | |
432 | of an object will clear the debugging info associated with an | |
433 | object, so accidentally repeated calls to GC_debug_free will report the | |
434 | deallocation of an object without debugging information. Out of | |
435 | memory errors will be reported to stderr, in addition to returning | |
436 | NIL. | |
437 | ||
438 | GC_debug_malloc checking during garbage collection is enabled | |
439 | with the first call to GC_debug_malloc. This will result in some | |
440 | slowdown during collections. If frequent heap checks are desired, | |
441 | this can be achieved by explicitly invoking GC_gcollect, e.g. from | |
442 | the debugger. | |
443 | ||
444 | GC_debug_malloc allocated objects should not be passed to GC_realloc | |
445 | or GC_free, and conversely. It is however acceptable to allocate only | |
446 | some objects with GC_debug_malloc, and to use GC_malloc for other objects, | |
447 | provided the two pools are kept distinct. In this case, there is a very | |
448 | low probablility that GC_malloc allocated objects may be misidentified as | |
449 | having been overwritten. This should happen with probability at most | |
450 | one in 2**32. This probability is zero if GC_debug_malloc is never called. | |
451 | ||
452 | GC_debug_malloc, GC_malloc_atomic, and GC_debug_realloc take two | |
453 | additional trailing arguments, a string and an integer. These are not | |
454 | interpreted by the allocator. They are stored in the object (the string is | |
455 | not copied). If an error involving the object is detected, they are printed. | |
456 | ||
457 | The macros GC_MALLOC, GC_MALLOC_ATOMIC, GC_REALLOC, GC_FREE, and | |
458 | GC_REGISTER_FINALIZER are also provided. These require the same arguments | |
459 | as the corresponding (nondebugging) routines. If gc.h is included | |
460 | with GC_DEBUG defined, they call the debugging versions of these | |
461 | functions, passing the current file name and line number as the two | |
462 | extra arguments, where appropriate. If gc.h is included without GC_DEBUG | |
463 | defined, then all these macros will instead be defined to their nondebugging | |
464 | equivalents. (GC_REGISTER_FINALIZER is necessary, since pointers to | |
465 | objects with debugging information are really pointers to a displacement | |
466 | of 16 bytes form the object beginning, and some translation is necessary | |
467 | when finalization routines are invoked. For details, about what's stored | |
468 | in the header, see the definition of the type oh in debug_malloc.c) | |
469 | ||
470 | INCREMENTAL/GENERATIONAL COLLECTION: | |
471 | ||
472 | The collector normally interrupts client code for the duration of | |
473 | a garbage collection mark phase. This may be unacceptable if interactive | |
474 | response is needed for programs with large heaps. The collector | |
475 | can also run in a "generational" mode, in which it usually attempts to | |
476 | collect only objects allocated since the last garbage collection. | |
477 | Furthermore, in this mode, garbage collections run mostly incrementally, | |
478 | with a small amount of work performed in response to each of a large number of | |
479 | GC_malloc requests. | |
480 | ||
481 | This mode is enabled by a call to GC_enable_incremental(). | |
482 | ||
483 | Incremental and generational collection is effective in reducing | |
484 | pause times only if the collector has some way to tell which objects | |
485 | or pages have been recently modified. The collector uses two sources | |
486 | of information: | |
487 | ||
488 | 1. Information provided by the VM system. This may be provided in | |
489 | one of several forms. Under Solaris 2.X (and potentially under other | |
490 | similar systems) information on dirty pages can be read from the | |
491 | /proc file system. Under other systems (currently SunOS4.X) it is | |
492 | possible to write-protect the heap, and catch the resulting faults. | |
493 | On these systems we require that system calls writing to the heap | |
494 | (other than read) be handled specially by client code. | |
495 | See os_dep.c for details. | |
496 | ||
497 | 2. Information supplied by the programmer. We define "stubborn" | |
498 | objects to be objects that are rarely changed. Such an object | |
499 | can be allocated (and enabled for writing) with GC_malloc_stubborn. | |
500 | Once it has been initialized, the collector should be informed with | |
501 | a call to GC_end_stubborn_change. Subsequent writes that store | |
502 | pointers into the object must be preceded by a call to | |
503 | GC_change_stubborn. | |
504 | ||
505 | This mechanism performs best for objects that are written only for | |
506 | initialization, and such that only one stubborn object is writable | |
507 | at once. It is typically not worth using for short-lived | |
508 | objects. Stubborn objects are treated less efficiently than pointerfree | |
509 | (atomic) objects. | |
510 | ||
511 | A rough rule of thumb is that, in the absence of VM information, garbage | |
512 | collection pauses are proportional to the amount of pointerful storage | |
513 | plus the amount of modified "stubborn" storage that is reachable during | |
514 | the collection. | |
515 | ||
516 | Initial allocation of stubborn objects takes longer than allocation | |
517 | of other objects, since other data structures need to be maintained. | |
518 | ||
519 | We recommend against random use of stubborn objects in client | |
520 | code, since bugs caused by inappropriate writes to stubborn objects | |
521 | are likely to be very infrequently observed and hard to trace. | |
522 | However, their use may be appropriate in a few carefully written | |
523 | library routines that do not make the objects themselves available | |
524 | for writing by client code. | |
525 | ||
526 | ||
527 | BUGS: | |
528 | ||
529 | Any memory that does not have a recognizable pointer to it will be | |
530 | reclaimed. Exclusive-or'ing forward and backward links in a list | |
531 | doesn't cut it. | |
532 | Some C optimizers may lose the last undisguised pointer to a memory | |
533 | object as a consequence of clever optimizations. This has almost | |
534 | never been observed in practice. Send mail to boehm@acm.org | |
535 | for suggestions on how to fix your compiler. | |
536 | This is not a real-time collector. In the standard configuration, | |
537 | percentage of time required for collection should be constant across | |
538 | heap sizes. But collection pauses will increase for larger heaps. | |
539 | They will decrease with the number of processors if parallel marking | |
540 | is enabled. | |
541 | (On 2007 vintage machines, GC times may be on the order of 5 msecs | |
542 | per MB of accessible memory that needs to be scanned and processor. | |
543 | Your mileage may vary.) The incremental/generational collection facility | |
544 | may help in some cases. | |
545 | Please address bug reports to boehm@acm.org. If you are | |
546 | contemplating a major addition, you might also send mail to ask whether | |
547 | it's already been done (or whether we tried and discarded it). | |
548 |