A garbage collector for C and C++

Where to get the collector
Platforms
Scalable multiprocessor versions
Some collector details
Further reading
Current users
Local links for this collector
Local background Links
Contacts, Updates, and Reporting Issues
Translations of this page

[ This is an updated version of the page formerly at http://www.hpl.hp.com/personal/Hans_Boehm/gc, and before that at http://reality.sgi.com/boehm/gc.html and before that at ftp://parcftp.xerox.com/pub/gc/gc.html. ]

The Boehm-Demers-Weiser conservative garbage collector can be used as a garbage collecting replacement for C malloc or C++ new. It allows you to allocate memory basically as you normally would, without explicitly deallocating memory that is no longer useful. The collector automatically recycles memory when it determines that it can no longer be otherwise accessed. A simple example of such a use is given here.

The collector is also used by a number of programming language implementations that either use C as intermediate code, want to facilitate easier interoperation with C libraries, or just prefer the simple collector interface. For a more detailed description of the interface, see here.

Alternatively, the garbage collector may be used as a leak detector for C or C++ programs, though that is not its primary goal.

The arguments for and against conservative garbage collection in C and C++ are briefly discussed in issues.html. The beginnings of a frequently-asked-questions list are here.

Empirically, this collector works with most unmodified C programs, simply by replacing malloc with GC_malloc calls, replacing realloc with GC_realloc calls, and removing free calls. Exceptions are discussed in issues.html.

Where to get the collector

Many versions are available in the gc_source subdirectory. Currently a recent stable version is gc-8.2.4.tar.gz. Note that this uses the new version numbering scheme and may occasionally require a separate libatomic_ops download (see below).

If that fails, try the latest explicitly numbered version in gc_source. Later versions may contain additional features, platform support, or bug fixes, but are likely to be less well tested.

Version 7.3 and later require that you download a corresponding version of libatomic_ops, which should be available in https://github.com/ivmai/libatomic_ops/wiki/Download. The current (stable) version is also available as gc_source/libatomic_ops-7.8.0.tar.gz. You will need to place that in a libatomic_ops subdirectory.

Previously it was best to use corresponding versions of gc and libatomic_ops, but for recent versions, it should be OK to mix and match them.

Starting with 8.0, libatomic_ops is only required if the compiler does not understand gcc's C atomic intrinsics.

The development version of the GC source code now resides on github, along with the downloadable packages. The GC tree itself is at https://github.com/ivmai/bdwgc/. The libatomic_ops tree required by the GC is at https://github.com/ivmai/libatomic_ops/.

To build a working version of the collector, you will need to do something like the following, where D is the absolute path to an installation directory:

cd D
git clone https://github.com/ivmai/libatomic_ops
git clone https://github.com/ivmai/bdwgc
ln -s  D/libatomic_ops D/bdwgc/libatomic_ops
cd bdwgc
autoreconf -vif
automake --add-missing
./configure
make

This will require that you have C and C++ toolchains, git, automake, autoconf, and libtool already installed.

Historical versions of the source can still be found on the SourceForge site (project "bdwgc") here.

The garbage collector code is copyrighted by Hans-J. Boehm, Alan J. Demers, Xerox Corporation, Silicon Graphics, and Hewlett-Packard Company. It may be used and copied without payment of a fee under minimal restrictions. See the README file in the distribution or the license for more details. IT IS PROVIDED AS IS, WITH ABSOLUTELY NO WARRANTY EXPRESSED OR IMPLIED. ANY USE IS AT YOUR OWN RISK.

Platforms

The collector is not completely portable, but the distribution includes ports to most standard PC and UNIX/Linux platforms. The collector should work on Linux, *BSD, recent Windows versions, MacOS X, HP/UX, Solaris, Tru64, Irix and a few other operating systems. Some ports are more polished than others. There are instructions for porting the collector to a new platform.

Irix pthreads, Linux threads, Win32 threads, Solaris threads (old style and pthreads), HP/UX 11 pthreads, Tru64 pthreads, and MacOS X threads are supported in recent versions.

Separately distributed ports

For MacOS 9/Classic use, Patrick Beard's latest port were once available from http://homepage.mac.com/pcbeard/gc/.

Several Linux and BSD versions provide prepacked versions of the collector. The Debian port can be found at https://packages.debian.org/sid/libgc-dev.

Scalable multiprocessor versions

Kenjiro Taura, Toshio Endo, and Akinori Yonezawa developed a parallel collector based on this one. It was once available from http://www.yl.is.s.u-tokyo.ac.jp/gc/ Their collector takes advantage of multiple processors during a collection. Starting with collector version 6.0alpha1 we also do this, though with more modest processor scalability goals. Our approach is discussed briefly in scale.html.

Some Collector Details

The collector uses a mark-sweep algorithm. It provides incremental and generational collection under operating systems which provide the right kind of virtual memory support. (Currently this includes SunOS[45], IRIX, OSF/1, Linux, and Windows, with varying restrictions.) It allows finalization code to be invoked when an object is collected. It can take advantage of type information to locate pointers if such information is provided, but it is usually used without such information. ee the README and gc.h files in the distribution for more details.

For an overview of the implementation, see here.

The garbage collector distribution includes a C string (cord) package that provides for fast concatenation and substring operations on long strings. A simple curses- and win32-based editor that represents the entire file as a cord is included as a sample application.

Performance of the nonincremental collector is typically competitive with malloc/free implementations. Both space and time overhead are likely to be only slightly higher for programs written for malloc/free (see Detlefs, Dosser and Zorn's Memory Allocation Costs in Large C and C++ Programs.) For programs allocating primarily very small objects, the collector may be faster; for programs allocating primarily large objects it will be slower. If the collector is used in a multithreaded environment and configured for thread-local allocation, it may in some cases significantly outperform malloc/free allocation in time.

We also expect that in many cases any additional overhead will be more than compensated for by decreased copying etc. if programs are written and tuned for garbage collection.