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