117
120
stack, data, or statically allocated bss segments. Pointers from
118
121
the stack or registers may point to anywhere inside an object.
119
122
The same is true for heap pointers if the collector is compiled with
120
ALL_INTERIOR_POINTERS defined, as is now the default.
123
ALL_INTERIOR_POINTERS defined, or GC_all_interior_pointers is otherwise
124
set, as is now the default.
122
126
Compiling without ALL_INTERIOR_POINTERS may reduce accidental retention
123
127
of garbage objects, by requiring pointers from the heap to to the beginning
124
128
of an object. But this no longer appears to be a significant
125
issue for most programs.
129
issue for most programs occupying a small fraction of the possible
127
132
There are a number of routines which modify the pointer recognition
128
133
algorithm. GC_register_displacement allows certain interior pointers
182
187
INSTALLATION AND PORTABILITY
184
As distributed, the macro SILENT is defined in Makefile.
185
In the event of problems, this can be removed to obtain a moderate
186
amount of descriptive output for each collection.
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.
187
193
(The given statistics exhibit a few peculiarities.
188
194
Things don't appear to add up for a variety of reasons, most notably
189
195
fragmentation losses. These are probably much more significant for the
190
196
contrived program "test.c" than for your application.)
192
Note that typing "make test" will automatically build the collector
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.)
205
Typing "make test" nstead of "make" will automatically build the collector
193
206
and then run setjmp_test and gctest. Setjmp_test will give you information
194
207
about configuring the collector, which is useful primarily if you have
195
208
a machine that's not already supported. Gctest is a somewhat superficial
196
209
test of collector functionality. Failure is indicated by a core dump or
197
210
a message to the effect that the collector is broken. Gctest takes about
198
35 seconds to run on a SPARCstation 2. It may use up to 8 MB of memory. (The
211
a second to two to run on reasonable 2007 vintage desktops.
212
It may use up to about 30MB of memory. (The
199
213
multi-threaded version will use more. 64-bit versions may use more.)
200
214
"Make test" will also, as its last step, attempt to build and test the
201
"cord" string library. This will fail without an ANSI C compiler, but
202
the garbage collector itself should still be usable.
215
"cord" string library.)
204
217
The Makefile will generate a library gc.a which you should link against.
205
218
Typing "make cords" will add the cord library to gc.a.
255
264
or 64 bit addresses will require a major effort. A port to plain MSDOS
256
265
or win16 is hard.
258
For machines not already mentioned, or for nonstandard compilers, the
259
following are likely to require change:
261
1. The parameters in gcconfig.h.
262
The parameters that will usually require adjustment are
263
STACKBOTTOM, ALIGNMENT and DATASTART. Setjmp_test
264
prints its guesses of the first two.
265
DATASTART should be an expression for computing the
266
address of the beginning of the data segment. This can often be
267
&etext. But some memory management units require that there be
268
some unmapped space between the text and the data segment. Thus
269
it may be more complicated. On UNIX systems, this is rarely
270
documented. But the adb "$m" command may be helpful. (Note
271
that DATASTART will usually be a function of &etext. Thus a
272
single experiment is usually insufficient.)
273
STACKBOTTOM is used to initialize GC_stackbottom, which
274
should be a sufficient approximation to the coldest stack address.
275
On some machines, it is difficult to obtain such a value that is
276
valid across a variety of MMUs, OS releases, etc. A number of
277
alternatives exist for using the collector in spite of this. See the
278
discussion in gcconfig.h immediately preceding the various
279
definitions of STACKBOTTOM.
282
The most important routine here is one to mark from registers.
283
The distributed file includes a generic hack (based on setjmp) that
284
happens to work on many machines, and may work on yours. Try
285
compiling and running setjmp_t.c to see whether it has a chance of
286
working. (This is not correct C, so don't blame your compiler if it
287
doesn't work. Based on limited experience, register window machines
288
are likely to cause trouble. If your version of setjmp claims that
289
all accessible variables, including registers, have the value they
290
had at the time of the longjmp, it also will not work. Vanilla 4.2 BSD
291
on Vaxen makes such a claim. SunOS does not.)
292
If your compiler does not allow in-line assembly code, or if you prefer
293
not to use such a facility, mach_dep.c may be replaced by a .s file
294
(as we did for the MIPS machine and the PC/RT).
295
At this point enough architectures are supported by mach_dep.c
296
that you will rarely need to do more than adjust for assembler
299
3. os_dep.c (and gc_priv.h).
300
Several kinds of operating system dependent routines reside here.
301
Many are optional. Several are invoked only through corresponding
302
macros in gc_priv.h, which may also be redefined as appropriate.
303
The routine GC_register_data_segments is crucial. It registers static
304
data areas that must be traversed by the collector. (User calls to
305
GC_add_roots may sometimes be used for similar effect.)
306
Routines to obtain memory from the OS also reside here.
307
Alternatively this can be done entirely by the macro GET_MEM
308
defined in gc_priv.h. Routines to disable and reenable signals
309
also reside here if they are need by the macros DISABLE_SIGNALS
310
and ENABLE_SIGNALS defined in gc_priv.h.
311
In a multithreaded environment, the macros LOCK and UNLOCK
312
in gc_priv.h will need to be suitably redefined.
313
The incremental collector requires page dirty information, which
314
is acquired through routines defined in os_dep.c. Unless directed
315
otherwise by gcconfig.h, these are implemented as stubs that simply
316
treat all pages as dirty. (This of course makes the incremental
317
collector much less useful.)
320
This provides a routine that allows the collector to scan data
321
segments associated with dynamic libraries. Often it is not
322
necessary to provide this routine unless user-written dynamic
325
For a different version of UN*X or different machines using the
326
Motorola 68000, Vax, SPARC, 80386, NS 32000, PC/RT, or MIPS architecture,
327
it should frequently suffice to change definitions in gcconfig.h.
267
For machines not already mentioned, or for nonstandard compilers,
268
some porting suggestions are provided in the "porting.html" file.
330
270
THE C INTERFACE TO THE ALLOCATOR
448
388
tries to approximate the Ellis-Detlefs C++ garbage collection
449
389
proposal without compiler changes.
452
1. Arrays allocated without new placement syntax are
453
allocated as uncollectable objects. They are traced by the
454
collector, but will not be reclaimed.
456
2. Failure to use "make c++" in combination with (1) will
457
result in arrays allocated using the default new operator.
458
This is likely to result in disaster without linker warnings.
460
3. If your compiler supports an overloaded new[] operator,
461
then gc_cpp.cc and gc_cpp.h should be suitably modified.
463
4. Many current C++ compilers have deficiencies that
464
break some of the functionality. See the comments in gc_cpp.h
465
for suggested workarounds.
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.
467
396
USE AS LEAK DETECTOR:
473
402
routine defined near the top of reclaim.c whenever an inaccessible
474
403
object is found that has not been explicitly freed. Such objects will
475
404
also be automatically reclaimed.
476
Productive use of this facility normally involves redefining report_leak
477
to do something more intelligent. This typically requires annotating
478
objects with additional information (e.g. creation time stack trace) that
479
identifies their origin. Such code is typically not very portable, and is
480
not included here, except on SPARC machines.
481
If all objects are allocated with GC_DEBUG_MALLOC (see next section),
482
then the default version of report_leak will report the source file
483
and line number at which the leaked object was allocated. This may
484
sometimes be sufficient. (On SPARC/SUNOS4 machines, it will also report
485
a cryptic stack trace. This can often be turned into a sympolic stack
486
trace by invoking program "foo" with "callprocs foo". Callprocs is
487
a short shell script that invokes adb to expand program counter values
488
to symbolic addresses. It was largely supplied by Scott Schwartz.)
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.)
489
413
Note that the debugging facilities described in the next section can
490
414
sometimes be slightly LESS effective in leak finding mode, since in
491
415
leak finding mode, GC_debug_free actually results in reuse of the object.
612
536
This is not a real-time collector. In the standard configuration,
613
537
percentage of time required for collection should be constant across
614
538
heap sizes. But collection pauses will increase for larger heaps.
615
(On SPARCstation 2s collection times will be on the order of 300 msecs
616
per MB of accessible memory that needs to be scanned. Your mileage
617
may vary.) The incremental/generational collection facility helps,
618
but is portable only if "stubborn" allocation is used.
539
They will decrease with the number of processors if parallel marking
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.
619
545
Please address bug reports to boehm@acm.org. If you are
620
546
contemplating a major addition, you might also send mail to ask whether
621
547
it's already been done (or whether we tried and discarded it).
added
removed
doc/README
