Man Linux: Main Page and Category List

NAME

       GC_malloc,         GC_malloc_atomic,        GC_free,        GC_realloc,
       GC_enable_incremental,                           GC_register_finalizer,
       GC_malloc_ignore_off_page,            GC_malloc_atomic_ignore_off_page,
       GC_set_warn_proc - Garbage collecting malloc replacement

SYNOPSIS

       #include <gc.h>
       void * GC_malloc(size_t size);
       void GC_free(void *ptr);
       void * GC_realloc(void *ptr, size_t size);

       + cc ... -I/usr/include/gc -lgc

DESCRIPTION

       GC_malloc and GC_free are plug-in replacements for standard malloc  and
       free.   However,  GC_malloc  will attempt to reclaim inaccessible space
       automatically  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.

       In  most  cases it is preferable to call the macros GC_MALLOC, GC_FREE,
       etc.  instead of calling GC_malloc and friends directly.   This  allows
       debugging  versions  of  the  routines  to  be  substituted by defining
       GC_DEBUG before including gc.h.

       See the documentation in the include file gc_cpp.h  for  an  alternate,
       C++ specific interface to the garbage collector.

       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
       generally  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.

       The garbage collector tries to avoid  allocating  memory  at  locations
       that already appear to be referenced before allocation.  (Such apparent
       ‘‘pointers’’ are usually large integers and the like that  just  happen
       to look like an address.)  This may make it hard to allocate very large
       objects.  An attempt to do so may generate a warning.

       GC_malloc_ignore_off_page and  GC_malloc_atomic_ignore_off_page  inform
       the  collector  that  the client code will always maintain a pointer to
       near the beginning of the object (within the first 512 bytes), and that
       pointers  beyond  that  can be ignored by the collector.  This makes it
       much easier for the  collector  to  place  large  objects.   These  are
       recommended  for  large  object  allocation.   (Objects  expected to be
       larger than about 100KBytes should be allocated this way.)

       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.

       The collector may, on rare occasion produce warning messages.  On  UNIX
       machines  these  appear  on  stderr.  Warning messages can be filtered,
       redirected, or ignored with GC_set_warn_proc This  is  recommended  for
       production code.  See gc.h for details.

       Fully  portable  code  should call GC_INIT from the main program before
       making any other GC calls.  On most platforms this does nothing and the
       collector  is  initialized  on  first use.  On a few platforms explicit
       initialization is necessary.  And it can never hurt.

       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  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, support for ‘‘abortable’’  garbage  collections  during  idle
       time, etc.

SEE ALSO

       The   README  and  gc.h  files  in  the  distribution.   More  detailed
       definitions of the functions exported by the collector are given there.
       (The above list is not complete.)

       The web site at http://www.hpl.hp.com/personal/Hans_Boehm/gc .

       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  (Hans.Boehm@hp.com).   Some  of the code was written by
       others, most notably Alan Demers.

                                2 October 2003                    GC_MALLOC(3)