path: root/docs/overview.md

[Interface Overview](gcinterface.md) | [Tutorial Slides](http://www.hboehm.info/gc/04tutorial.pdf) | [FAQ](faq.md) | [Example](simple_example.md) | [Download](https://github.com/ivmai/bdwgc/wiki/Download)
---|---|---|---|---

# A garbage collector for C and C++

  * Platforms
  * Some collector details
  * Further reading
  * Information provided on the BDWGC site
  * Documentation files
  * More background information
  * Contacts and new release announcements

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

The
[Boehm](http://www.hboehm.info)-[Demers](http://www.cs.cornell.edu/annual_report/00-01/bios.htm#demers)-[Weiser](http://www.ubiq.com/hypertext/weiser/weiser.html)
conservative Garbage Collector (**BDWGC**) 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](simple_example.md).

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](gcinterface.md).

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

Typically several versions are offered for
[downloading](https://github.com/ivmai/bdwgc/wiki/Download): preview, stable,
legacy. Usually you should use the one marked as the _latest stable_ release.
Preview versions may contain additional features, platform support, but are
likely to be less well tested. The list of changes for each version
is specified on the [releases](https://github.com/ivmai/bdwgc/releases) page.
The development version (snapshot) is available in the master branch of
[bdwgc git](https://github.com/ivmai/bdwgc) repository on GitHub.

The arguments for and against conservative garbage collection in C and C++ are
briefly discussed [here](http://www.hboehm.info/gc/issues.html).

The garbage collector code is copyrighted by
[Hans-J. Boehm](http://www.hboehm.info), Alan J. Demers,
[Xerox Corporation](http://www.xerox.com/),
[Silicon Graphics](http://www.sgi.com/),
[Hewlett-Packard Company](http://www.hp.com/),
[Ivan Maidanski](https://github.com/ivmai), and partially by some others.
It may be used and copied without payment of a fee under minimal restrictions.
See the LICENSE file in the distribution for more details.
**IT IS PROVIDED AS IS, WITH ABSOLUTELY NO WARRANTY EXPRESSED OR IMPLIED.
ANY USE IS AT YOUR OWN RISK.**

Empirically, this collector works with most unmodified C programs, simply
by replacing `malloc` and `calloc` with `GC_malloc` calls, replacing `realloc`
with `GC_realloc` calls, and removing `free` calls. Exceptions are discussed
[here](http://www.hboehm.info/gc/issues.html).

## 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, Android, BSD variants, OS/2, Windows (Win32 and Win64), MacOS X,
iOS, HP/UX, Solaris, Tru64, Irix, Symbian and other operating systems. Some
platforms are more polished (better supported) than others.

Irix pthreads, Linux threads, Windows threads, Solaris threads (pthreads
only), HP/UX 11 pthreads, Tru64 pthreads, and MacOS X threads are supported.

See also [here](porting.md) for the instructions on how to port the library to
new platforms.

## Some Collector Details

The collector uses a [mark-sweep](http://www.hboehm.info/gc/complexity.html)
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](finalization.md) 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. See the README and `gc.h` files in the distribution
for more details.

For an overview of the implementation, see [here](gcdescr.md).

The garbage collector distribution includes a C string (`cord.h`) package that
provides for fast concatenation and substring operations on long strings.
A simple curses- and Windows-based editor that represents the entire file as
a cord is included as a sample application.  See [README.cords](README.cords)
file for the details.

Performance of the non-incremental 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](http://citeseerx.ist.psu.edu/viewdoc/download?doi=10.1.1.30.3073&rep=rep1&type=ps)).
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 multi-threaded 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 e.g. decreased copying if programs are written and tuned
for garbage collection.

## Further reading

**The following provide information on garbage collection in general:**

Paul Wilson's
[garbage collection ftp archive](ftp://ftp.cs.utexas.edu/pub/garbage)
and [GC survey](ftp://ftp.cs.utexas.edu/pub/garbage/gcsurvey.ps).

The Ravenbrook
[Memory Management Reference](http://www.memorymanagement.org/).

David Chase's [GC FAQ](http://www.iecc.com/gclist/GC-faq.html).

Richard Jones'
[Garbage Collection Page](https://www.cs.kent.ac.uk/people/staff/rej/gc.html)
and his [book](http://www.cs.kent.ac.uk/people/staff/rej/gcbook/gcbook.html).

**The following papers describe the collector algorithms we use and the
underlying design decisions at a higher level:**

(Some of the lower level details can be found [here](gcdescr.md).)

The first one is not available electronically due to copyright considerations.
Most of the others are subject to ACM copyright.

Boehm, H., Dynamic Memory Allocation and Garbage Collection,
_Computers in Physics 9_, 3, May/June 1995, pp. 297-303. This is directed
at an otherwise sophisticated audience unfamiliar with memory allocation
issues. The algorithmic details differ from those in the implementation. There
is a related letter to the editor and a minor correction in the next issue.

Boehm, H., and [M. Weiser](http://www.ubiq.com/hypertext/weiser/weiser.html),
[Garbage Collection in an Uncooperative Environment](http://www.hboehm.info/spe_gc_paper/),
_Software Practice and Experience_, September 1988, pp. 807-820.

Boehm, H., A. Demers, and S. Shenker,
[Mostly Parallel Garbage Collection](http://www.hboehm.info/gc/papers/pldi91.ps.Z),
Proceedings of the ACM SIGPLAN '91 Conference on Programming Language Design
and Implementation, _SIGPLAN Notices 26_, 6 (June 1991), pp. 157-164.

Boehm, H.,
[Space Efficient Conservative Garbage Collection](http://www.hboehm.info/gc/papers/pldi93.ps.Z),
Proceedings of the ACM SIGPLAN '93 Conference on Programming Language Design
and Implementation, _SIGPLAN Notices 28_, 6 (June 1993), pp. 197-206.

Boehm, H., Reducing Garbage Collector Cache Misses,
_Proceedings of the 2000 International Symposium on Memory Management_.
[Official version](https://dl.acm.org/doi/10.1145/362422.362438).
[Technical report](http://www.hpl.hp.com/techreports/2000/HPL-2000-99.html)
version. Describes the prefetch strategy incorporated into the collector for
some platforms. Explains why the sweep phase of a _mark-sweep_ collector
should not really be a distinct phase.

M. Serrano, H. Boehm, Understanding Memory Allocation of Scheme Programs,
_Proceedings of the Fifth ACM SIGPLAN International Conference on Functional
Programming_, 2000, Montreal, Canada, pp. 245-256.
[Official version](https://dl.acm.org/doi/10.1145/357766.351264). Earlier
[Technical Report](http://www.hpl.hp.com/techreports/2000/HPL-2000-62.html)
version. Includes some discussion of the collector debugging facilities for
identifying causes of memory retention.

Boehm, H., Fast Multiprocessor Memory Allocation and Garbage Collection,
[HP Labs Technical Report HPL 2000-165](http://www.hpl.hp.com/techreports/2000/HPL-2000-165.html).
Discusses the parallel collection algorithms, and presents some performance
results.

Boehm, H., Bounding Space Usage of Conservative Garbage Collectors,
_Proceedings of the 2002 ACM SIGPLAN-SIGACT Symposium on Principles
of Programming Languages_, Jan. 2002, pp. 93-100.
[Official version](https://dl.acm.org/doi/10.1145/565816.503282).
[Technical report](http://www.hpl.hp.com/techreports/2001/HPL-2001-251.html)
version. Includes a discussion of a collector facility to much more reliably
test for the potential of unbounded heap growth.

**The following papers discuss language and compiler restrictions necessary
to guaranteed safety of conservative garbage collection:**

We thank John Levine and JCLT for allowing us to make the second paper
available electronically, and providing PostScript for the final version.

Boehm, H.,
[Simple Garbage-Collector-Safety](http://www.hboehm.info/gc/papers/pldi96.ps.gz),
Proceedings of the ACM SIGPLAN '96 Conference on Programming Language Design
and Implementation.

Boehm, H., and D. Chase,
[A Proposal for Garbage-Collector-Safe C Compilation](http://www.hboehm.info/gc/papers/boecha.ps.gz),
_Journal of C Language Translation 4_, 2 (December 1992), pp. 126-141.

**Other related information:**

The Detlefs, Dosser and Zorn's
[Memory Allocation Costs in Large C and C++ Programs](http://citeseerx.ist.psu.edu/viewdoc/download?doi=10.1.1.30.3073&rep=rep1&type=ps).
This is a performance comparison of the Boehm-Demers-Weiser collector
to `malloc`/`free`, using programs written for `malloc`/`free`.

Joel Bartlett's
[mostly copying conservative garbage collector for C++](ftp://gatekeeper.dec.com/pub/compaq/WRL/research-reports/WRL-TN-12.ps).

John Ellis and David Detlef's
[Safe Efficient Garbage Collection for C++](https://dl.acm.org/doi/10.5555/1267974.1267983)
proposal.

Henry Baker's [paper collection](http://home.pipeline.com/%7Ehbaker1/).

Slides for Hans Boehm's
[Allocation and GC Myths](http://www.hboehm.info/gc/myths.ps) talk.

## Information provided on the BDWGC site

[Current users](https://github.com/ivmai/bdwgc/wiki/Known-clients) list.

[Slides from an ISMM 2004 tutorial about the GC](http://www.hboehm.info/gc/04tutorial.pdf).

[A FAQ (frequently asked questions) list](faq.md).

[Directory](http://www.hboehm.info/gc/gc_source/) containing the distribution
files of all garbage collector releases.  It duplicates
[Download](https://github.com/ivmai/bdwgc/wiki/Download) page on GitHub.

## Documentation files

The following documents are not platform-specific in general.

[A simple illustration of how to build and use the collector](simple_example.md).

[Description of alternate interfaces to the garbage collector](gcinterface.md).

[How to use the garbage collector as a leak detector](leak.md).

[Some hints on debugging garbage collected applications](debugging.md).

[An overview of the implementation of the garbage collector](gcdescr.md).

[The data structure used for fast pointer lookups](tree.md).

[Scalability of the collector to multiprocessors](scale.md).

[Instructions on building the library using autoconf/configure](README.autoconf).

[Instructions on building the library using cmake](README.cmake).

[List of environment variables that affect the collector operation at runtime](README.environment).

[List of compile time macros that affect the library when built](README.macros).

[Details on the finalization facility](finalization.md).

[Instructions on how to port the library to new platforms](porting.md).

[Description of the cord library built on top of GC](README.cords).

## More background information

[An attempt to establish a bound on space usage of conservative garbage collectors](http://www.hboehm.info/gc/bounds.html).

[Mark-sweep versus copying garbage collectors and their complexity](http://www.hboehm.info/gc/complexity.html).

[Pros and cons of conservative garbage collectors, in comparison to other collectors](http://www.hboehm.info/gc/conservative.html).

[Issues related to garbage collection vs. manual memory management in C/C++](http://www.hboehm.info/gc/issues.html).

[An example of a case in which garbage collection results in a much faster implementation as a result of reduced synchronization](http://www.hboehm.info/gc/example.html).

[Slide set discussing performance of nonmoving garbage collectors](http://www.hboehm.info/gc/nonmoving/).

[Slide set discussing _Destructors, Finalizers, and Synchronization_, POPL 2003](http://www.hboehm.info/popl03/web/).

[Paper corresponding to above slide set](https://dl.acm.org/doi/10.1145/604131.604153)
([Technical Report](http://www.hpl.hp.com/techreports/2002/HPL-2002-335.html)
version).

[A Java/Scheme/C/C++ garbage collection benchmark](http://www.hboehm.info/gc/gc_bench/).

[Slides for talk on memory allocation myths](http://www.hboehm.info/gc/myths.ps).

[Slides for OOPSLA 98 garbage collection talk](http://www.hboehm.info/gc/gctalk.ps).

[Related papers](http://www.hboehm.info/gc/papers/).

## Contacts and new release announcements

GitHub and Stack Overflow are the major two places for communication.

Technical questions (how to, how does it work, etc.) should be posted
to [Stack Overflow](https://stackoverflow.com/questions/tagged/boehm-gc) with
_boehm-gc_ tag.

To contribute, please rebase your code to the latest
[master](https://github.com/ivmai/bdwgc/tree/master/) and submit
a [pull request](https://github.com/ivmai/bdwgc/pulls) to GitHub.

To report a bug, or propose (request) a new feature, create
a [GitHub issue](https://github.com/ivmai/bdwgc/issues). Please make sure
it has not been reported yet by someone else.

To receive notifications on every release, please subscribe to
[Releases RSS feed](https://github.com/ivmai/bdwgc/releases.atom).
Notifications on all issues and pull requests are available
by [watching](https://github.com/ivmai/bdwgc/watchers) the project.

Mailing lists (bdwgc-announce@lists.opendylan.org, bdwgc@lists.opendylan.org,
and the former gc-announce@linux.hpl.hp.com and gc@linux.hpl.hp.com) are not
used at this moment. Their content is available
in
[bdwgc-announce](https://github.com/ivmai/bdwgc/files/1037650/bdwgc-announce-mailing-list-archive-2014_02.tar.gz)
and
[bdwgc](https://github.com/ivmai/bdwgc/files/1038163/bdwgc-mailing-list-archive-2017_04.tar.gz)
archive files, respectively. The gc list archive may also be read
at [Narkive](http://bdwgc.opendylan.narkive.com).

Some prior discussion of the collector has taken place on the gcc java mailing
list, whose archives appear [here](http://gcc.gnu.org/ml/java/), and also
on [gclist@iecc.com](http://lists.tunes.org/mailman/listinfo/gclist).