-Garbage collection is a widely used technique that frees the programmer from
-having to know the lifetimes of heap objects, making software easier to produce
-and maintain. Many programming languages rely on garbage collection for
-automatic memory management. There are two primary forms of garbage collection:
-conservative and accurate.
-
-Conservative garbage collection often does not require any special support from
-either the language or the compiler: it can handle non-type-safe programming
-languages (such as C/C++) and does not require any special information from the
-compiler. The `Boehm collector
-<http://www.hpl.hp.com/personal/Hans_Boehm/gc/>`__ is an example of a
-state-of-the-art conservative collector.
-
-Accurate garbage collection requires the ability to identify all pointers in the
-program at run-time (which requires that the source-language be type-safe in
-most cases). Identifying pointers at run-time requires compiler support to
-locate all places that hold live pointer variables at run-time, including the
-:ref:`processor stack and registers <gcroot>`.
-
-Conservative garbage collection is attractive because it does not require any
-special compiler support, but it does have problems. In particular, because the
-conservative garbage collector cannot *know* that a particular word in the
-machine is a pointer, it cannot move live objects in the heap (preventing the
-use of compacting and generational GC algorithms) and it can occasionally suffer
-from memory leaks due to integer values that happen to point to objects in the
-program. In addition, some aggressive compiler transformations can break
-conservative garbage collectors (though these seem rare in practice).
-
-Accurate garbage collectors do not suffer from any of these problems, but they
-can suffer from degraded scalar optimization of the program. In particular,
-because the runtime must be able to identify and update all pointers active in
-the program, some optimizations are less effective. In practice, however, the
-locality and performance benefits of using aggressive garbage collection
-techniques dominates any low-level losses.
-
-This document describes the mechanisms and interfaces provided by LLVM to
-support accurate garbage collection.
-
-Goals and non-goals
--------------------
-
-LLVM's intermediate representation provides :ref:`garbage collection intrinsics
-<gc_intrinsics>` that offer support for a broad class of collector models. For
-instance, the intrinsics permit:
-
-* semi-space collectors
-
-* mark-sweep collectors
-
-* generational collectors
-
-* reference counting
-
-* incremental collectors
-
-* concurrent collectors
-
-* cooperative collectors
-
-We hope that the primitive support built into the LLVM IR is sufficient to
-support a broad class of garbage collected languages including Scheme, ML, Java,
-C#, Perl, Python, Lua, Ruby, other scripting languages, and more.
-
-However, LLVM does not itself provide a garbage collector --- this should be
-part of your language's runtime library. LLVM provides a framework for compile
-time :ref:`code generation plugins <plugin>`. The role of these plugins is to
-generate code and data structures which conforms to the *binary interface*
-specified by the *runtime library*. This is similar to the relationship between
-LLVM and DWARF debugging info, for example. The difference primarily lies in
-the lack of an established standard in the domain of garbage collection --- thus
-the plugins.
-
-The aspects of the binary interface with which LLVM's GC support is
-concerned are:
-
-* Creation of GC-safe points within code where collection is allowed to execute
- safely.
-
-* Computation of the stack map. For each safe point in the code, object
- references within the stack frame must be identified so that the collector may
- traverse and perhaps update them.
-
-* Write barriers when storing object references to the heap. These are commonly
- used to optimize incremental scans in generational collectors.
-
-* Emission of read barriers when loading object references. These are useful
- for interoperating with concurrent collectors.
-
-There are additional areas that LLVM does not directly address:
-
-* Registration of global roots with the runtime.
-
-* Registration of stack map entries with the runtime.
-
-* The functions used by the program to allocate memory, trigger a collection,
- etc.
-
-* Computation or compilation of type maps, or registration of them with the
- runtime. These are used to crawl the heap for object references.
-
-In general, LLVM's support for GC does not include features which can be
-adequately addressed with other features of the IR and does not specify a
-particular binary interface. On the plus side, this means that you should be
-able to integrate LLVM with an existing runtime. On the other hand, it leaves a
-lot of work for the developer of a novel language. However, it's easy to get
-started quickly and scale up to a more sophisticated implementation as your
-compiler matures.