packages icon



 GC_MALLOC(1L)                                                 GC_MALLOC(1L)
                                20 April 1994



 NAME
      GC_malloc, GC_malloc_atomic, GC_free, GC_realloc,
      GC_enable_incremental, GC_register_finalizer - Garbage collecting
      malloc replacement

 SYNOPSIS
      #include "gc.h"
      # define malloc(n) GC_malloc(n)

      cc ... gc.a

 DESCRIPTION
      GC_malloc and GC_free are plug-in replacements for standard malloc and
      free.  However, GC_malloc will attempt to reclaim inaccessible space
      automaticaly by invoking a conservative garbage collector at
      appropriate points.  The collector traverses all data structures
      accessible by following pointers from the machines registers,
      stack(s), data, and bss segments.  Inaccessible structures will be
      reclaimed.  A machine word is considered to be a valid pointer if it
      is an address inside an object allocated by GC_malloc or friends.
      Unlike the standard implementations of malloc, GC_malloc clears the
      newly allocated storage.  GC_malloc_atomic does not.  Furthermore, it
      informs the collector that the resulting object will never contain any
      pointers, and should therefore not be scanned by the collector.
      GC_free can be used to deallocate objects, but its use is optional,
      and discouraged.  GC_realloc has the standard realloc semantics.  It
      preserves pointer-free-ness.  GC_register_finalizer allows for
      registration of functions that are invoked when an object becomes
      inaccessible.  It is also possible to use the collector to find
      storage leaks in programs destined to be run with standard
      malloc/free.  The collector can be compiled for thread-safe operation.
      Unlike standard malloc, it is safe to call malloc after a previous
      malloc call was interrupted by a signal, provided the original malloc
      call is not resumed.  Debugging versions of many of the above routines
      are provided as macros.  Their names are identical to the above, but
      consist of all capital letters.  If GC_DEBUG is defined before gc.h is
      included, these routines do additional checking, and allow the leak
      detecting version of the collector to produce slightly more useful
      output.  Without GC_DEBUG defined, they behave exactly like the
      lower-case versions.  On some machines, collection will be performed
      incrementally after a call to GC_enable_incremental.  This may
      temporarily write protect pages in the heap.  See the README file for
      more information on how this interacts with system calls that write to
      the heap.  Other facilities not discussed here include a C++
      interface, limited facilities to support incremental collection on
      machines without appropriate VM support, provisions for providing more
      explicit object layout information to the garbage collector, more
      direct support for ``weak'' pointers, etc.

 SEE ALSO
      The README and gc.h files in the distribution.  More detailed



                                    - 1 -      Formatted:  November 14, 2024






 GC_MALLOC(1L)                                                 GC_MALLOC(1L)
                                20 April 1994



      definitions of the functions exported by the collector are given
      there.  (The above list is not complete.) Boehm, H., and M. Weiser,
      "Garbage Collection in an Uncooperative Environment", Software
      Practice & Experience, September 1988, pp. 807-820.  The malloc(3) man
      page.

 AUTHOR
      Hans-J. Boehm (boehm@parc.xerox.com).  Some of the code was written by
      others, most notably Alan Demers.













































                                    - 2 -      Formatted:  November 14, 2024