<head>
<meta http-equiv="Content-Type" Content="text/html; charset=UTF-8" >
<title>Accurate Garbage Collection with LLVM</title>
- <link rel="stylesheet" href="llvm.css" type="text/css">
+ <link rel="stylesheet" href="_static/llvm.css" type="text/css">
<style type="text/css">
.rowhead { text-align: left; background: inherit; }
.indent { padding-left: 1em; }
understand the data structure, but there are only 20 lines of meaningful
code.)</p>
-</div>
-
-<div class="doc_code"><pre
->/// @brief The map for a single function's stack frame. One of these is
+<pre class="doc_code">
+/// @brief The map for a single function's stack frame. One of these is
/// compiled as constant data into the executable for each function.
///
/// Storage of metadata values is elided if the %metadata parameter to
for (unsigned e = R->Map->NumRoots; i != e; ++i)
Visitor(&R->Roots[i], NULL);
}
-}</pre></div>
+}</pre>
+
+</div>
<!-- ======================================================================= -->
<h3>
<a name="gcattr">Specifying GC code generation: <tt>gc "..."</tt></a>
</h3>
+<div>
+
<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>
-
<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
<tt>Function</tt>.</p>
<a name="gcroot">Identifying GC roots on the stack: <tt>llvm.gcroot</tt></a>
</h3>
+<div>
+
<div class="doc_code"><tt>
void @llvm.gcroot(i8** %ptrloc, i8* %metadata)
</tt></div>
-<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
collection. The exact impact on generated code is specified by a <a
-href="#plugin">compiler plugin</a>.</p>
+href="#plugin">compiler plugin</a>. All calls to <tt>llvm.gcroot</tt> <b>must</b> reside
+ inside the first basic block.</p>
<p>A compiler which uses mem2reg to raise imperative code using <tt>alloca</tt>
into SSA form need only add a call to <tt>@llvm.gcroot</tt> for those variables
<p>It is also important to mark intermediate values with <tt>llvm.gcroot</tt>.
For example, consider <tt>h(f(), g())</tt>. Beware leaking the result of
-<tt>f()</tt> in the case that <tt>g()</tt> triggers a collection.</p>
+<tt>f()</tt> in the case that <tt>g()</tt> triggers a collection. Note, that
+stack variables must be initialized and marked with <tt>llvm.gcroot</tt> in
+function's prologue.</p>
<p>The first argument <b>must</b> be a value referring to an alloca instruction
or a bitcast of an alloca. The second contains a pointer to metadata that
<p>Consider the following fragment of Java code:</p>
-<pre>
+<pre class="doc_code">
{
Object X; // A null-initialized reference to an object
...
<p>This block (which may be located in the middle of a function or in a loop
nest), could be compiled to this LLVM code:</p>
-<pre>
+<pre class="doc_code">
Entry:
;; In the entry block for the function, allocate the
;; stack space for X, which is an LLVM pointer.
;; Tell LLVM that the stack space is a stack root.
;; Java has type-tags on objects, so we pass null as metadata.
%tmp = bitcast %Object** %X to i8**
- call void @llvm.gcroot(i8** %X, i8* null)
+ call void @llvm.gcroot(i8** %tmp, i8* null)
...
;; "CodeBlock" is the block corresponding to the start
<a name="gcwrite">Write barrier: <tt>llvm.gcwrite</tt></a>
</h4>
+<div>
+
<div class="doc_code"><tt>
void @llvm.gcwrite(i8* %value, i8* %object, i8** %derived)
</tt></div>
-<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
the derived pointer (the third argument). The exact code generated is specified
<a name="gcread">Read barrier: <tt>llvm.gcread</tt></a>
</h4>
+<div>
+
<div class="doc_code"><tt>
i8* @llvm.gcread(i8* %object, i8** %derived)<br>
</tt></div>
-<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
derived pointer (the second argument). The exact code generated is specified by