C Interface

Code must be linked against the GC library. On most UNIX platforms, this is normally gc.a.

The following describes the standard C interface to the garbage collector. It is not a complete definition of the interface. It describes only the most commonly used functionality, approximately in decreasing order of frequency of use. The description assumes an ANSI C compiler. The full interface is described in gc.h.

Clients should include gc.h. In the case if Irix pthreads code or Solaris threads code, gc.h should be included after the threads header file, and after defining IRIX_THREADS or SOLARIS_THREADS. (Gc.h must be included in files that use either GC or threads primitives.)

void * GC_malloc(size_t nbytes)

Allocates and clears nbytes of storage. Requires (amortized) time proportional to nbytes. The resulting object will be automatically deallocated when unreferenced. References from objects allocated with the system malloc are usually not considered by the collector. (See GC_malloc_uncollectable, however.) GC_MALLOC is a macro which invokes GC_malloc by default or, if GC_DEBUG is defined before gc.h is included, a debugging version that checks occasionally for overwrite errors, and the like.

void * GC_malloc_atomic(size_t nbytes)

Allocates nbytes of storage. Requires (amortized) time proportional to nbytes. The resulting object will be automatically deallocated when unreferenced. The client promises that the resulting object will never contain any pointers. The memory is not cleared. This is the preferred way to allocate strings, floating point arrays, bitmaps, etc. More precise information about pointer locations can be communicated to the collector using the interface in gc_typed.h. (GC_MALLOC_ATOMIC supports debugging.)

void * GC_malloc_uncollectable(size_t nbytes)

Identical to GC_malloc, except that the resulting object is not automatically deallocated. Unlike the system-provided malloc, the collector does scan the object for pointers to garbage-collectable memory. (GC_MALLOC_UNCOLLECTABLE supports debugging.)

void * GC_realloc(void *old, size_t new_size)

Allocate a new object of the indicated size and copy (a prefix of) the old object into the new object. The old object is reused in place if convenient. If the original object was allocated with GC_malloc_atomic, the new object is subject to the same constraints. If it was allocated as an uncollectable object, then the new object is uncollectable, and the old object (if different) is deallocated. (Use GC_REALLOC with GC_MALLOC, etc.)

void GC_free(void *dead)

Explicitly deallocate an object. Typically not useful for small collectable objects. (Use GC_FREE with GC_MALLOC, etc.)

void * GC_malloc_ignore_off_page(size_t nbytes)

void * GC_malloc_atomic_ignore_off_page(size_t nbytes)

Analogous to GC_malloc and GC_malloc_atomic, except that the client guarantees that as long as the resulting object is of use, a pointer is maintained to someplace inside the first 512 bytes of the object. This pointer should be declared volatile to avoid interference from compiler optimizations. (Other nonvolatile pointers to the object may exist as well.) This is the preferred way to allocate objects that are likely to be > 100KBytes in size. It greatly reduces the risk that such objects will be accidentally retained when they are no longer needed. Thus space usage may be significantly reduced.

void GC_gcollect(void)

Explicitly force a garbage collection.

void GC_enable_incremental(void)

Cause the garbage collector to perform a small amount of work every few invocations of GC_malloc or the like, instead of performing an entire collection at once. This is likely to increase total running time. It will improve response on a platform that either has suitable support in the garbage collector (Irix and most other Unix versions, win32 if the collector was suitably built) or if "stubborn" allocation is used (see gc.h). On many platforms this interacts poorly with system calls (other than read) that write to the garbage collected heap.

GC_warn_proc GC_set_warn_proc(GC_warn_proc p)

Replace the default procedure used by the collector to print warnings. The collector may otherwise write to sterr, most commonly because GC_malloc was used in a situation in which GC_malloc_ignore_off_page would have been more appropriate. See gc.h for details.

void GC_register_finalizer(...)

Register a function to be called when an object becomes inaccessible. This is often useful as a backup method for releasing system resources (e.g. closing files) when the object referencing them becomes inaccessible. It is not an acceptable method to perform actions that must be performed in a timely fashion. See gc.h for details of the interface. See here for a more detailed discussion of the design.

The collector distribution also includes a string package that takes advantage of the collector. For details see cord.h

C++ Interface

STL allocators

Users of the SGI extended STL can include gc_alloc.h before including STL header files. This defines SGI-style allocators

• alloc
• single_client_alloc
• gc_alloc
• single_client_gc_alloc

which may be used either directly to allocate memory or to instantiate container templates. The first two allocate uncollectable but traced memory, while the second two allocate collectable memory. The single_client versions are not safe for concurrent access by multiple threads, but are faster.

For an example, click here.

Class inheritance based interface

Users may include gc_cpp.h and then cause members of certain classes to be allocated in garbage collectable memory by inheriting from class gc. For details see gc_cpp.h.

C interface

It is also possible to use the C interface from gc.h directly. On platforms which use malloc to implement ::new, it should usually be possible to use a version of the collector that has been compiled as a malloc replacement. It is also possible to replace ::new and other allocation functions suitably.

Note that user-implemented small-block allocation often works poorly with an underlying garbage-collected large block allocator, since the collector has to view all objects accessible from the user's free list as reachable. This is likely to cause problems if GC_malloc is used with something like the original HP version of STL.