Peanuts NeXT Software Archives/Peanuts-2.iso/Unix/developer/gc.README

Text File | 1993-10-06 | 3.9 KB | 79 lines

I VERY preliminary port of the Xerox garbage collector to NeXTSTEP.
Jason Jobe
[e-mail], [e-mail]

Copyright 1988, 1989 Hans-J. Boehm, Alan J. Demers
Copyright (c) 1991-1993 by Xerox Corporation.  All rights reserved.

THIS MATERIAL IS PROVIDED AS IS, WITH ABSOLUTELY NO WARRANTY EXPRESSED
OR IMPLIED.  ANY USE IS AT YOUR OWN RISK.

Permission is hereby granted to copy this garbage collector for any purpose,
provided the above notices are retained on all copies.


This is version 3.2.  Note that functions were renamed since version 1.9
to make naming consistent with PCR collectors.


GENERAL DESCRIPTION

  This is a garbage colecting storage allocator that is intended to be
used as a plug-in replacement for C's malloc.

  Since the collector does not require pointers to be tagged, it does not
attempt to ensure that all inaccessible storage is reclaimed.  However,
in our experience, it is typically more successful at reclaiming unused
memory than most C programs using explicit deallocation.  Unlike manually
introduced leaks, the amount of unreclaimed memory typically stays
bounded.

  In the following, an "object" is defined to be a region of memory allocated
by the routines described below.

  Any objects not intended to be collected must be pointed to either
from other such accessible objects, or from the registers,
stack, data, or statically allocated bss segments.  Pointers from
the stack or registers may point to anywhere inside an object.
However, it is usually assumed that all pointers originating in the
heap point to the beginning of an object.  (This does
not disallow interior pointers; it simply requires that there must be a
pointer to the beginning of every accessible object, in addition to any
interior pointers.)  There are two facilities for altering this behavior.
The macro ALL_INTERIOR_POINTERS may be defined in gc_private.h to
cause any pointer into an object to retain the object.  A routine
GC_register_displacement is provided to allow for more controlled
interior pointer use in the heap.  Defining ALL_INTERIOR_POINTERS
is somewhat dangerous.  See gc_private.h for details.  The routine
GC_register_displacement is described in gc.h.

  Note that pointers inside memory allocated by the standard "malloc" are not
seen by the garbage collector.  Thus objects pointed to only from such a
region may be prematurely deallocated.  It is thus suggested that the
standard "malloc" be used only for memory regions, such as I/O buffers, that
are guaranteed not to contain pointers.  Pointers in C language automatic,
static, or register variables, are correctly recognized.

  The collector does not generally know how to find pointers in data
areas that are associated with dynamic libraries.  This is easy to
remedy IF you know how to find those data areas on your operating
system (see GC_add_roots).  Code for doing this under SunOS4.X only is
included (see dynamic_load.c).  (Note that it includes a special version
of dlopen, GC_dlopen, that should be called instead of the standard one.
By default, this is not compiled in, since it requires the -ldl library.)
Note that the garbage collector does not need to be informed of shared
read-only data.  However if the shared library mechanism can introduce
discontiguous data areas that may contain pointers, then the collector does
need to be informed.

  Signal processing for most signals is normally deferred during collection,
and during uninterruptible parts of the allocation process.  Unlike
standard ANSI C mallocs, it is intended to be safe to invoke malloc
from a signal handler while another malloc is in progress, provided
the original malloc is not restarted.  (Empirically, many UNIX
applications already asssume this.)  The allocator/collector can
also be configured for thread-safe operation.  (Full signal safety can
also be acheived, but only at the cost of two system calls per malloc,
which is usually unacceptable.)