diff options
| author | Dimitry Andric <dim@FreeBSD.org> | 2011-05-02 19:34:44 +0000 |
|---|---|---|
| committer | Dimitry Andric <dim@FreeBSD.org> | 2011-05-02 19:34:44 +0000 |
| commit | 6b943ff3a3f8617113ecbf611cf0f8957e4e19d2 (patch) | |
| tree | fc5f365fb9035b2d0c622bbf06c9bbe8627d7279 /docs/GarbageCollection.html | |
| parent | d0e4e96dc17a6c1c6de3340842c80f0e187ba349 (diff) | |
Notes
Diffstat (limited to 'docs/GarbageCollection.html')
| -rw-r--r-- | docs/GarbageCollection.html | 151 |
1 files changed, 75 insertions, 76 deletions
diff --git a/docs/GarbageCollection.html b/docs/GarbageCollection.html index fde070ce6b45..13a3714e8233 100644 --- a/docs/GarbageCollection.html +++ b/docs/GarbageCollection.html @@ -13,9 +13,9 @@ </head> <body> -<div class="doc_title"> +<h1> Accurate Garbage Collection with LLVM -</div> +</h1> <ol> <li><a href="#introduction">Introduction</a> @@ -79,12 +79,12 @@ </div> <!-- *********************************************************************** --> -<div class="doc_section"> +<h2> <a name="introduction">Introduction</a> -</div> +</h2> <!-- *********************************************************************** --> -<div class="doc_text"> +<div> <p>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 @@ -124,14 +124,12 @@ techniques dominates any low-level losses.</p> <p>This document describes the mechanisms and interfaces provided by LLVM to support accurate garbage collection.</p> -</div> - <!-- ======================================================================= --> -<div class="doc_subsection"> +<h3> <a name="feature">Goals and non-goals</a> -</div> +</h3> -<div class="doc_text"> +<div> <p>LLVM's intermediate representation provides <a href="#intrinsics">garbage collection intrinsics</a> that offer support for a broad class of @@ -151,14 +149,14 @@ collector models. For instance, the intrinsics permit:</p> support a broad class of garbage collected languages including Scheme, ML, Java, C#, Perl, Python, Lua, Ruby, other scripting languages, and more.</p> -<p>However, LLVM does not itself provide a garbage collector—this should +<p>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 <a href="#plugin">code generation plugins</a>. The role of these plugins is to generate code and data structures which conforms to the <em>binary interface</em> specified by the <em>runtime library</em>. 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.</p> +of garbage collection—thus the plugins.</p> <p>The aspects of the binary interface with which LLVM's GC support is concerned are:</p> @@ -198,13 +196,15 @@ compiler matures.</p> </div> +</div> + <!-- *********************************************************************** --> -<div class="doc_section"> +<h2> <a name="quickstart">Getting started</a> -</div> +</h2> <!-- *********************************************************************** --> -<div class="doc_text"> +<div> <p>Using a GC with LLVM implies many things, for example:</p> @@ -246,14 +246,12 @@ compiler matures.</p> includes a highly portable, built-in ShadowStack code generator. It is compiled into <tt>llc</tt> and works even with the interpreter and C backends.</p> -</div> - <!-- ======================================================================= --> -<div class="doc_subsection"> +<h3> <a name="quickstart-compiler">In your compiler</a> -</div> +</h3> -<div class="doc_text"> +<div> <p>To turn the shadow stack on for your functions, first call:</p> @@ -276,11 +274,11 @@ switching to a more advanced GC.</p> </div> <!-- ======================================================================= --> -<div class="doc_subsection"> +<h3> <a name="quickstart-runtime">In your runtime</a> -</div> +</h3> -<div class="doc_text"> +<div> <p>The shadow stack doesn't imply a memory allocation algorithm. A semispace collector or building atop <tt>malloc</tt> are great places to start, and can @@ -343,11 +341,11 @@ void visitGCRoots(void (*Visitor)(void **Root, const void *Meta)) { }</pre></div> <!-- ======================================================================= --> -<div class="doc_subsection"> +<h3> <a name="shadow-stack">About the shadow stack</a> -</div> +</h3> -<div class="doc_text"> +<div> <p>Unlike many GC algorithms which rely on a cooperative code generator to compile stack maps, this algorithm carefully maintains a linked list of stack @@ -372,13 +370,15 @@ in order to improve performance.</p> </div> +</div> + <!-- *********************************************************************** --> -<div class="doc_section"> +<h2> <a name="core">IR features</a><a name="intrinsics"></a> -</div> +</h2> <!-- *********************************************************************** --> -<div class="doc_text"> +<div> <p>This section describes the garbage collection facilities provided by the <a href="LangRef.html">LLVM intermediate representation</a>. The exact behavior @@ -390,18 +390,16 @@ intended to be a complete interface to any garbage collector. A program will need to interface with the GC library using the facilities provided by that program.</p> -</div> - <!-- ======================================================================= --> -<div class="doc_subsection"> +<h3> <a name="gcattr">Specifying GC code generation: <tt>gc "..."</tt></a> -</div> +</h3> <div class="doc_code"><tt> define <i>ty</i> @<i>name</i>(...) <span style="text-decoration: underline">gc "<i>name</i>"</span> { ... </tt></div> -<div class="doc_text"> +<div> <p>The <tt>gc</tt> function attribute is used to specify the desired GC style to the compiler. Its programmatic equivalent is the <tt>setGC</tt> method of @@ -418,15 +416,15 @@ programs that use different garbage collection algorithms (or none at all).</p> </div> <!-- ======================================================================= --> -<div class="doc_subsection"> +<h3> <a name="gcroot">Identifying GC roots on the stack: <tt>llvm.gcroot</tt></a> -</div> +</h3> <div class="doc_code"><tt> void @llvm.gcroot(i8** %ptrloc, i8* %metadata) </tt></div> -<div class="doc_text"> +<div> <p>The <tt>llvm.gcroot</tt> intrinsic is used to inform LLVM that a stack variable references an object on the heap and is to be tracked for garbage @@ -494,11 +492,11 @@ CodeBlock: </div> <!-- ======================================================================= --> -<div class="doc_subsection"> +<h3> <a name="barriers">Reading and writing references in the heap</a> -</div> +</h3> -<div class="doc_text"> +<div> <p>Some collectors need to be informed when the mutator (the program that needs garbage collection) either reads a pointer from or writes a pointer to a field @@ -534,18 +532,16 @@ require the corresponding barrier. Such a GC plugin will replace the intrinsic calls with the corresponding <tt>load</tt> or <tt>store</tt> instruction if they are used.</p> -</div> - <!-- ======================================================================= --> -<div class="doc_subsubsection"> +<h4> <a name="gcwrite">Write barrier: <tt>llvm.gcwrite</tt></a> -</div> +</h4> <div class="doc_code"><tt> void @llvm.gcwrite(i8* %value, i8* %object, i8** %derived) </tt></div> -<div class="doc_text"> +<div> <p>For write barriers, LLVM provides the <tt>llvm.gcwrite</tt> intrinsic function. It has exactly the same semantics as a non-volatile <tt>store</tt> to @@ -559,15 +555,15 @@ implement reference counting.</p> </div> <!-- ======================================================================= --> -<div class="doc_subsubsection"> +<h4> <a name="gcread">Read barrier: <tt>llvm.gcread</tt></a> -</div> +</h4> <div class="doc_code"><tt> i8* @llvm.gcread(i8* %object, i8** %derived)<br> </tt></div> -<div class="doc_text"> +<div> <p>For read barriers, LLVM provides the <tt>llvm.gcread</tt> intrinsic function. It has exactly the same semantics as a non-volatile <tt>load</tt> from the @@ -580,13 +576,17 @@ writes.</p> </div> +</div> + +</div> + <!-- *********************************************************************** --> -<div class="doc_section"> +<h2> <a name="plugin">Implementing a collector plugin</a> -</div> +</h2> <!-- *********************************************************************** --> -<div class="doc_text"> +<div> <p>User code specifies which GC code generation to use with the <tt>gc</tt> function attribute or, equivalently, with the <tt>setGC</tt> method of @@ -666,14 +666,12 @@ $ llvm-as < sample.ll | llc -load=MyGC.so</pre></blockquote> <p>It is also possible to statically link the collector plugin into tools, such as a language-specific compiler front-end.</p> -</div> - <!-- ======================================================================= --> -<div class="doc_subsection"> +<h3> <a name="collector-algos">Overview of available features</a> -</div> +</h3> -<div class="doc_text"> +<div> <p><tt>GCStrategy</tt> provides a range of features through which a plugin may do useful work. Some of these are callbacks, some are algorithms that can @@ -958,11 +956,11 @@ interest.</p> </div> <!-- ======================================================================= --> -<div class="doc_subsection"> +<h3> <a name="stack-map">Computing stack maps</a> -</div> +</h3> -<div class="doc_text"> +<div> <p>LLVM automatically computes a stack map. One of the most important features of a <tt>GCStrategy</tt> is to compile this information into the executable in @@ -1014,11 +1012,11 @@ for collector plugins which implement reference counting or a shadow stack.</p> <!-- ======================================================================= --> -<div class="doc_subsection"> +<h3> <a name="init-roots">Initializing roots to null: <tt>InitRoots</tt></a> -</div> +</h3> -<div class="doc_text"> +<div> <blockquote><pre >MyGC::MyGC() { @@ -1039,12 +1037,12 @@ this feature should be used by all GC plugins. It is enabled by default.</p> <!-- ======================================================================= --> -<div class="doc_subsection"> +<h3> <a name="custom">Custom lowering of intrinsics: <tt>CustomRoots</tt>, <tt>CustomReadBarriers</tt>, and <tt>CustomWriteBarriers</tt></a> -</div> +</h3> -<div class="doc_text"> +<div> <p>For GCs which use barriers or unusual treatment of stack roots, these flags allow the collector to perform arbitrary transformations of the LLVM @@ -1129,11 +1127,11 @@ bool MyGC::performCustomLowering(Function &F) { <!-- ======================================================================= --> -<div class="doc_subsection"> +<h3> <a name="safe-points">Generating safe points: <tt>NeededSafePoints</tt></a> -</div> +</h3> -<div class="doc_text"> +<div> <p>LLVM can compute four kinds of safe points:</p> @@ -1193,11 +1191,11 @@ safe point (because only the topmost function has been patched).</p> <!-- ======================================================================= --> -<div class="doc_subsection"> +<h3> <a name="assembly">Emitting assembly code: <tt>GCMetadataPrinter</tt></a> -</div> +</h3> -<div class="doc_text"> +<div> <p>LLVM allows a plugin to print arbitrary assembly code before and after the rest of a module's assembly code. At the end of the module, the GC can compile @@ -1341,14 +1339,15 @@ void MyGCPrinter::finishAssembly(std::ostream &OS, AsmPrinter &AP, </div> +</div> <!-- *********************************************************************** --> -<div class="doc_section"> +<h2> <a name="references">References</a> -</div> +</h2> <!-- *********************************************************************** --> -<div class="doc_text"> +<div> <p><a name="appel89">[Appel89]</a> Runtime Tags Aren't Necessary. Andrew W. Appel. Lisp and Symbolic Computation 19(7):703-705, July 1989.</p> @@ -1379,8 +1378,8 @@ Fergus Henderson. International Symposium on Memory Management 2002.</p> src="http://www.w3.org/Icons/valid-html401-blue" alt="Valid HTML 4.01"></a> <a href="mailto:sabre@nondot.org">Chris Lattner</a><br> - <a href="http://llvm.org">LLVM Compiler Infrastructure</a><br> - Last modified: $Date: 2010-05-11 22:16:09 +0200 (Tue, 11 May 2010) $ + <a href="http://llvm.org/">LLVM Compiler Infrastructure</a><br> + Last modified: $Date: 2011-04-23 02:30:22 +0200 (Sat, 23 Apr 2011) $ </address> </body> |