readme

linux下建立JAVA虚拟机的源码KAFFE

  The variable GC_non_gc_bytes, which is normally 0, may be changed to reflect
the amount of memory allocated by the above routines that should not be
considered as a candidate for collection.  Careless use may, of course, result
in excessive memory consumption.

  Some additional tuning is possible through the parameters defined
near the top of gc_priv.h.
  
  If only GC_malloc is intended to be used, it might be appropriate to define:

#define malloc(n) GC_malloc(n)
#define calloc(m,n) GC_malloc((m)*(n))

  For small pieces of VERY allocation intensive code, gc_inl.h
includes some allocation macros that may be used in place of GC_malloc
and friends.

  All externally visible names in the garbage collector start with "GC_".
To avoid name conflicts, client code should avoid this prefix, except when
accessing garbage collector routines or variables.

  There are provisions for allocation with explicit type information.
This is rarely necessary.  Details can be found in gc_typed.h.

THE C++ INTERFACE TO THE ALLOCATOR:

  The Ellis-Hull C++ interface to the collector is included in
the collector distribution.  If you intend to use this, type
"make c++" after the initial build of the collector is complete.
See gc_cpp.h for the definition of the interface.  This interface
tries to approximate the Ellis-Detlefs C++ garbage collection
proposal without compiler changes.

Cautions:
1. Arrays allocated without new placement syntax are
allocated as uncollectable objects.  They are traced by the
collector, but will not be reclaimed.

2. Failure to use "make c++" in combination with (1) will
result in arrays allocated using the default new operator.
This is likely to result in disaster without linker warnings.

3. If your compiler supports an overloaded new[] operator,
then gc_cpp.cc and gc_cpp.h should be suitably modified.

4. Many current C++ compilers have deficiencies that
break some of the functionality.  See the comments in gc_cpp.h
for suggested workarounds.

USE AS LEAK DETECTOR:

  The collector may be used to track down leaks in C programs that are
intended to run with malloc/free (e.g. code with extreme real-time or
portability constraints).  To do so define FIND_LEAK in Makefile
This will cause the collector to invoke the report_leak
routine defined near the top of reclaim.c whenever an inaccessible
object is found that has not been explicitly freed.  Such objects will
also be automatically reclaimed.
  Productive use of this facility normally involves redefining report_leak
to do something more intelligent.  This typically requires annotating
objects with additional information (e.g. creation time stack trace) that
identifies their origin.  Such code is typically not very portable, and is
not included here, except on SPARC machines.
  If all objects are allocated with GC_DEBUG_MALLOC (see next section),
then the default version of report_leak will report the source file
and line number at which the leaked object was allocated.  This may
sometimes be sufficient.  (On SPARC/SUNOS4 machines, it will also report
a cryptic stack trace.  This can often be turned into a sympolic stack
trace by invoking program "foo" with "callprocs foo".  Callprocs is
a short shell script that invokes adb to expand program counter values
to symbolic addresses.  It was largely supplied by Scott Schwartz.)
  Note that the debugging facilities described in the next section can
sometimes be slightly LESS effective in leak finding mode, since in
leak finding mode, GC_debug_free actually results in reuse of the object.
(Otherwise the object is simply marked invalid.)  Also note that the test
program is not designed to run meaningfully in FIND_LEAK mode.
Use "make gc.a" to build the collector.

DEBUGGING FACILITIES:

  The routines GC_debug_malloc, GC_debug_malloc_atomic, GC_debug_realloc,
and GC_debug_free provide an alternate interface to the collector, which
provides some help with memory overwrite errors, and the like.
Objects allocated in this way are annotated with additional
information.  Some of this information is checked during garbage
collections, and detected inconsistencies are reported to stderr.

  Simple cases of writing past the end of an allocated object should
be caught if the object is explicitly deallocated, or if the
collector is invoked while the object is live.  The first deallocation
of an object will clear the debugging info associated with an
object, so accidentally repeated calls to GC_debug_free will report the
deallocation of an object without debugging information.  Out of
memory errors will be reported to stderr, in addition to returning
NIL.

  GC_debug_malloc checking  during garbage collection is enabled
with the first call to GC_debug_malloc.  This will result in some
slowdown during collections.  If frequent heap checks are desired,
this can be achieved by explicitly invoking GC_gcollect, e.g. from
the debugger.

  GC_debug_malloc allocated objects should not be passed to GC_realloc
or GC_free, and conversely.  It is however acceptable to allocate only
some objects with GC_debug_malloc, and to use GC_malloc for other objects,
provided the two pools are kept distinct.  In this case, there is a very
low probablility that GC_malloc allocated objects may be misidentified as
having been overwritten.  This should happen with probability at most
one in 2**32.  This probability is zero if GC_debug_malloc is never called.

  GC_debug_malloc, GC_malloc_atomic, and GC_debug_realloc take two
additional trailing arguments, a string and an integer.  These are not
interpreted by the allocator.  They are stored in the object (the string is
not copied).  If an error involving the object is detected, they are printed.

  The macros GC_MALLOC, GC_MALLOC_ATOMIC, GC_REALLOC, GC_FREE, and
GC_REGISTER_FINALIZER are also provided.  These require the same arguments
as the corresponding (nondebugging) routines.  If gc.h is included
with GC_DEBUG defined, they call the debugging versions of these
functions, passing the current file name and line number as the two
extra arguments, where appropriate.  If gc.h is included without GC_DEBUG
defined, then all these macros will instead be defined to their nondebugging
equivalents.  (GC_REGISTER_FINALIZER is necessary, since pointers to
objects with debugging information are really pointers to a displacement
of 16 bytes form the object beginning, and some translation is necessary
when finalization routines are invoked.  For details, about what's stored
in the header, see the definition of the type oh in debug_malloc.c)

INCREMENTAL/GENERATIONAL COLLECTION:

The collector normally interrupts client code for the duration of 
a garbage collection mark phase.  This may be unacceptable if interactive
response is needed for programs with large heaps.  The collector
can also run in a "generational" mode, in which it usually attempts to
collect only objects allocated since the last garbage collection.
Furthermore, in this mode, garbage collections run mostly incrementally,
with a small amount of work performed in response to each of a large number of
GC_malloc requests.

This mode is enabled by a call to GC_enable_incremental().

Incremental and generational collection is effective in reducing
pause times only if the collector has some way to tell which objects
or pages have been recently modified.  The collector uses two sources
of information:

1. Information provided by the VM system.  This may be provided in
one of several forms.  Under Solaris 2.X (and potentially under other
similar systems) information on dirty pages can be read from the
/proc file system.  Under other systems (currently SunOS4.X) it is
possible to write-protect the heap, and catch the resulting faults.
On these systems we require that system calls writing to the heap
(other than read) be handled specially by client code.
See os_dep.c for details.

2. Information supplied by the programmer.  We define "stubborn"
objects to be objects that are rarely changed.  Such an object
can be allocated (and enabled for writing) with GC_malloc_stubborn.
Once it has been initialized, the collector should be informed with
a call to GC_end_stubborn_change.  Subsequent writes that store
pointers into the object must be preceded by a call to
GC_change_stubborn.

This mechanism performs best for objects that are written only for
initialization, and such that only one stubborn object is writable
at once.  It is typically not worth using for short-lived
objects.  Stubborn objects are treated less efficiently than pointerfree
(atomic) objects.

A rough rule of thumb is that, in the absence of VM information, garbage
collection pauses are proportional to the amount of pointerful storage
plus the amount of modified "stubborn" storage that is reachable during
the collection.  

Initial allocation of stubborn objects takes longer than allocation
of other objects, since other data structures need to be maintained.

We recommend against random use of stubborn objects in client
code, since bugs caused by inappropriate writes to stubborn objects
are likely to be very infrequently observed and hard to trace.  
However, their use may be appropriate in a few carefully written
library routines that do not make the objects themselves available
for writing by client code.


BUGS:

  Any memory that does not have a recognizable pointer to it will be
reclaimed.  Exclusive-or'ing forward and backward links in a list
doesn't cut it.
  Some C optimizers may lose the last undisguised pointer to a memory
object as a consequence of clever optimizations.  This has almost
never been observed in practice.  Send mail to [e-mail]
for suggestions on how to fix your compiler.
  This is not a real-time collector.  In the standard configuration,
percentage of time required for collection should be constant across
heap sizes.  But collection pauses will increase for larger heaps.
(On SPARCstation 2s collection times will be on the order of 300 msecs
per MB of accessible memory that needs to be scanned.  Your mileage
may vary.)  The incremental/generational collection facility helps,
but is portable only if "stubborn" allocation is used.
  Please address bug reports to [e-mail].  If you are
contemplating a major addition, you might also send mail to ask whether
it's already been done (or whether we tried and discarded it).