Update to explain how ssp and sspreq attributes override each other.
[oota-llvm.git] / docs / ProgrammersManual.html
index bde2ae03d33958005556785d2da3504e4b1bd876..6b93e9cc0446e7daa8e66666bcc3b682f490fdcf 100644 (file)
@@ -62,6 +62,7 @@ option</a></li>
       <li><a href="#dss_sortedvectorset">A sorted 'vector'</a></li>
       <li><a href="#dss_smallset">"llvm/ADT/SmallSet.h"</a></li>
       <li><a href="#dss_smallptrset">"llvm/ADT/SmallPtrSet.h"</a></li>
+      <li><a href="#dss_denseset">"llvm/ADT/DenseSet.h"</a></li>
       <li><a href="#dss_FoldingSet">"llvm/ADT/FoldingSet.h"</a></li>
       <li><a href="#dss_set">&lt;set&gt;</a></li>
       <li><a href="#dss_setvector">"llvm/ADT/SetVector.h"</a></li>
@@ -77,6 +78,11 @@ option</a></li>
       <li><a href="#dss_map">&lt;map&gt;</a></li>
       <li><a href="#dss_othermap">Other Map-Like Container Options</a></li>
     </ul></li>
+    <li><a href="#ds_bit">BitVector-like containers</a>
+    <ul>
+      <li><a href="#dss_bitvector">A dense bitvector</a></li>
+      <li><a href="#dss_sparsebitvector">A sparse bitvector</a></li>
+    </ul></li>
   </ul>
   </li>
   <li><a href="#common">Helpful Hints for Common Operations</a>
@@ -97,6 +103,8 @@ complex example</a> </li>
 the same way</a> </li>
           <li><a href="#iterate_chains">Iterating over def-use &amp;
 use-def chains</a> </li>
+          <li><a href="#iterate_preds">Iterating over predecessors &amp;
+successors of blocks</a></li>
         </ul>
       </li>
       <li><a href="#simplechanges">Making simple changes</a>
@@ -106,6 +114,7 @@ use-def chains</a> </li>
           <li><a href="#schanges_deleting">Deleting             <tt>Instruction</tt>s</a> </li>
           <li><a href="#schanges_replacing">Replacing an                <tt>Instruction</tt>
 with another <tt>Value</tt></a> </li>
+          <li><a href="#schanges_deletingGV">Deleting <tt>GlobalVariable</tt>s</a> </li>  
         </ul>
       </li>
 <!--
@@ -129,7 +138,8 @@ with another <tt>Value</tt></a> </li>
     <li><a href="#AbstractTypeUser">The AbstractTypeUser Class</a></li>
   </ul></li>
 
-  <li><a href="#SymbolTable">The <tt>ValueSymbolTable</tt> and <tt>TypeSymbolTable</tt> classes </a></li>
+  <li><a href="#SymbolTable">The <tt>ValueSymbolTable</tt> and <tt>TypeSymbolTable</tt> classes</a></li>
+  <li><a href="#UserLayout">The <tt>User</tt> and owned <tt>Use</tt> classes' memory layout</a></li>
   </ul></li>
 
   <li><a href="#coreclasses">The Core LLVM Class Hierarchy Reference</a>
@@ -164,7 +174,8 @@ with another <tt>Value</tt></a> </li>
 <div class="doc_author">    
   <p>Written by <a href="mailto:sabre@nondot.org">Chris Lattner</a>, 
                 <a href="mailto:dhurjati@cs.uiuc.edu">Dinakar Dhurjati</a>, 
-                <a href="mailto:jstanley@cs.uiuc.edu">Joel Stanley</a>, and
+                <a href="mailto:ggreif@gmail.com">Gabor Greif</a>, 
+                <a href="mailto:jstanley@cs.uiuc.edu">Joel Stanley</a> and
                 <a href="mailto:rspencer@x10sys.com">Reid Spencer</a></p>
 </div>
 
@@ -322,7 +333,7 @@ file (note that you very rarely have to include this file directly).</p>
   <dt><tt>cast&lt;&gt;</tt>: </dt>
 
   <dd><p>The <tt>cast&lt;&gt;</tt> operator is a "checked cast" operation. It
-  converts a pointer or reference from a base class to a derived cast, causing
+  converts a pointer or reference from a base class to a derived class, causing
   an assertion failure if it is not really an instance of the right type.  This
   should be used in cases where you have some information that makes you believe
   that something is of the right type.  An example of the <tt>isa&lt;&gt;</tt>
@@ -580,9 +591,9 @@ suite, it gives a report that looks like this:</p>
 
 <div class="doc_code">
 <pre>
-   7646 bytecodewriter  - Number of normal instructions
-    725 bytecodewriter  - Number of oversized instructions
- 129996 bytecodewriter  - Number of bytecode bytes written
+   7646 bitcodewriter   - Number of normal instructions
+    725 bitcodewriter   - Number of oversized instructions
+ 129996 bitcodewriter   - Number of bitcode bytes written
    2817 raise           - Number of insts DCEd or constprop'd
    3213 raise           - Number of cast-of-self removed
    5046 raise           - Number of expression trees converted
@@ -704,6 +715,11 @@ access the container.  Based on that, you should use:</p>
     iteration, but do not support efficient look-up based on a key.
 </li>
 
+<li>a <a href="#ds_bit">bit</a> container provides an efficient way to store and
+    perform set operations on sets of numeric id's, while automatically
+    eliminating duplicates.  Bit containers require a maximum of 1 bit for each
+    identifier you want to store.
+</li>
 </ul>
 
 <p>
@@ -803,7 +819,7 @@ vector is also useful when interfacing with code that expects vectors :).
 <div class="doc_code">
 <pre>
 for ( ... ) {
-   std::vector<foo> V;
+   std::vector&lt;foo&gt; V;
    use V;
 }
 </pre>
@@ -813,7 +829,7 @@ for ( ... ) {
 
 <div class="doc_code">
 <pre>
-std::vector<foo> V;
+std::vector&lt;foo&gt; V;
 for ( ... ) {
    use V;
    V.clear();
@@ -975,6 +991,25 @@ visited in sorted order.</p>
 
 </div>
 
+<!-- _______________________________________________________________________ -->
+<div class="doc_subsubsection">
+  <a name="dss_denseset">"llvm/ADT/DenseSet.h"</a>
+</div>
+
+<div class="doc_text">
+
+<p>
+DenseSet is a simple quadratically probed hash table.  It excels at supporting
+small values: it uses a single allocation to hold all of the pairs that
+are currently inserted in the set.  DenseSet is a great way to unique small
+values that are not simple pointers (use <a 
+href="#dss_smallptrset">SmallPtrSet</a> for pointers).  Note that DenseSet has
+the same requirements for the value type that <a 
+href="#dss_densemap">DenseMap</a> has.
+</p>
+
+</div>
+
 <!-- _______________________________________________________________________ -->
 <div class="doc_subsubsection">
   <a name="dss_FoldingSet">"llvm/ADT/FoldingSet.h"</a>
@@ -1224,7 +1259,7 @@ iterators in a densemap are invalidated whenever an insertion occurs, unlike
 map.  Also, because DenseMap allocates space for a large number of key/value
 pairs (it starts with 64 by default), it will waste a lot of space if your keys
 or values are large.  Finally, you must implement a partial specialization of
-DenseMapKeyInfo for the key that you want, if it isn't already supported.  This
+DenseMapInfo for the key that you want, if it isn't already supported.  This
 is required to tell DenseMap about two special marker values (which can never be
 inserted into the map) that it needs internally.</p>
 
@@ -1275,6 +1310,52 @@ expensive.  Element iteration does not visit elements in a useful order.</p>
 
 </div>
 
+<!-- ======================================================================= -->
+<div class="doc_subsection">
+  <a name="ds_bit">Bit storage containers (BitVector, SparseBitVector)</a>
+</div>
+
+<div class="doc_text">
+<p>Unlike the other containers, there are only two bit storage containers, and 
+choosing when to use each is relatively straightforward.</p>
+
+<p>One additional option is 
+<tt>std::vector&lt;bool&gt;</tt>: we discourage its use for two reasons 1) the
+implementation in many common compilers (e.g. commonly available versions of 
+GCC) is extremely inefficient and 2) the C++ standards committee is likely to
+deprecate this container and/or change it significantly somehow.  In any case,
+please don't use it.</p>
+</div>
+
+<!-- _______________________________________________________________________ -->
+<div class="doc_subsubsection">
+  <a name="dss_bitvector">BitVector</a>
+</div>
+
+<div class="doc_text">
+<p> The BitVector container provides a fixed size set of bits for manipulation.
+It supports individual bit setting/testing, as well as set operations.  The set
+operations take time O(size of bitvector), but operations are performed one word
+at a time, instead of one bit at a time.  This makes the BitVector very fast for
+set operations compared to other containers.  Use the BitVector when you expect
+the number of set bits to be high (IE a dense set).
+</p>
+</div>
+
+<!-- _______________________________________________________________________ -->
+<div class="doc_subsubsection">
+  <a name="dss_sparsebitvector">SparseBitVector</a>
+</div>
+
+<div class="doc_text">
+<p> The SparseBitVector container is much like BitVector, with one major
+difference: Only the bits that are set, are stored.  This makes the
+SparseBitVector much more space efficient than BitVector when the set is sparse,
+as well as making set operations O(number of set bits) instead of O(size of
+universe).  The downside to the SparseBitVector is that setting and testing of random bits is O(N), and on large SparseBitVectors, this can be slower than BitVector. In our implementation, setting or testing bits in sorted order
+(either forwards or reverse) is O(1) worst case.  Testing and setting bits within 128 bits (depends on size) of the current bit is also O(1).  As a general statement, testing/setting bits in a SparseBitVector is O(distance away from last set bit).
+</p>
+</div>
 
 <!-- *********************************************************************** -->
 <div class="doc_section">
@@ -1405,8 +1486,8 @@ small example that shows how to dump all instructions in a function to the stand
 #include "<a href="/doxygen/InstIterator_8h-source.html">llvm/Support/InstIterator.h</a>"
 
 // <i>F is a pointer to a Function instance</i>
-for (inst_iterator i = inst_begin(F), e = inst_end(F); i != e; ++i)
-  llvm::cerr &lt;&lt; *i &lt;&lt; "\n";
+for (inst_iterator I = inst_begin(F), E = inst_end(F); I != E; ++I)
+  llvm::cerr &lt;&lt; *I &lt;&lt; "\n";
 </pre>
 </div>
 
@@ -1418,7 +1499,10 @@ F, all you would need to do is something like:</p>
 <div class="doc_code">
 <pre>
 std::set&lt;Instruction*&gt; worklist;
-worklist.insert(inst_begin(F), inst_end(F));
+// or better yet, SmallPtrSet&lt;Instruction*, 64&gt; worklist;
+
+for (inst_iterator I = inst_begin(F), E = inst_end(F); I != E; ++I)
+   worklist.insert(&amp;*I);
 </pre>
 </div>
 
@@ -1459,7 +1543,7 @@ the last line of the last example,</p>
 
 <div class="doc_code">
 <pre>
-Instructionpinst = &amp;*i;
+Instruction *pinst = &amp;*i;
 </pre>
 </div>
 
@@ -1467,7 +1551,7 @@ Instruction* pinst = &amp;*i;
 
 <div class="doc_code">
 <pre>
-Instructionpinst = i;
+Instruction *pinst = i;
 </pre>
 </div>
 
@@ -1530,13 +1614,12 @@ class OurFunctionPass : public FunctionPass {
 
     virtual runOnFunction(Function&amp; F) {
       for (Function::iterator b = F.begin(), be = F.end(); b != be; ++b) {
-        for (BasicBlock::iterator i = b-&gt;begin(); ie = b-&gt;end(); i != ie; ++i) {
+        for (BasicBlock::iterator i = b-&gt;begin(), ie = b-&gt;end(); i != ie; ++i) {
           if (<a href="#CallInst">CallInst</a>* callInst = <a href="#isa">dyn_cast</a>&lt;<a
  href="#CallInst">CallInst</a>&gt;(&amp;*i)) {
             // <i>We know we've encountered a call instruction, so we</i>
             // <i>need to determine if it's a call to the</i>
-            // <i>function pointed to by m_func or not</i>
-
+            // <i>function pointed to by m_func or not.</i>
             if (callInst-&gt;getCalledFunction() == targetFunc)
               ++callCounter;
           }
@@ -1545,7 +1628,7 @@ class OurFunctionPass : public FunctionPass {
     }
 
   private:
-    unsigned  callCounter;
+    unsigned callCounter;
 };
 </pre>
 </div>
@@ -1597,7 +1680,7 @@ of <tt>F</tt>:</p>
 
 <div class="doc_code">
 <pre>
-FunctionF = ...;
+Function *F = ...;
 
 for (Value::use_iterator i = F-&gt;use_begin(), e = F-&gt;use_end(); i != e; ++i)
   if (Instruction *Inst = dyn_cast&lt;Instruction&gt;(*i)) {
@@ -1617,10 +1700,10 @@ the particular <tt>Instruction</tt>):</p>
 
 <div class="doc_code">
 <pre>
-Instructionpi = ...;
+Instruction *pi = ...;
 
 for (User::op_iterator i = pi-&gt;op_begin(), e = pi-&gt;op_end(); i != e; ++i) {
-  Valuev = *i;
+  Value *v = *i;
   // <i>...</i>
 }
 </pre>
@@ -1633,6 +1716,36 @@ for (User::op_iterator i = pi-&gt;op_begin(), e = pi-&gt;op_end(); i != e; ++i)
 
 </div>
 
+<!--_______________________________________________________________________-->
+<div class="doc_subsubsection">
+  <a name="iterate_preds">Iterating over predecessors &amp;
+successors of blocks</a>
+</div>
+
+<div class="doc_text">
+
+<p>Iterating over the predecessors and successors of a block is quite easy
+with the routines defined in <tt>"llvm/Support/CFG.h"</tt>.  Just use code like
+this to iterate over all predecessors of BB:</p>
+
+<div class="doc_code">
+<pre>
+#include "llvm/Support/CFG.h"
+BasicBlock *BB = ...;
+
+for (pred_iterator PI = pred_begin(BB), E = pred_end(BB); PI != E; ++PI) {
+  BasicBlock *Pred = *PI;
+  // <i>...</i>
+}
+</pre>
+</div>
+
+<p>Similarly, to iterate over successors use
+succ_iterator/succ_begin/succ_end.</p>
+
+</div>
+
+
 <!-- ======================================================================= -->
 <div class="doc_subsection">
   <a name="simplechanges">Making simple changes</a>
@@ -1665,7 +1778,7 @@ parameters. For example, an <tt>AllocaInst</tt> only <i>requires</i> a
 
 <div class="doc_code">
 <pre>
-AllocaInst* ai = new AllocaInst(Type::IntTy);
+AllocaInst* ai = new AllocaInst(Type::Int32Ty);
 </pre>
 </div>
 
@@ -1693,7 +1806,7 @@ used as some kind of index by some other code.  To accomplish this, I place an
 
 <div class="doc_code">
 <pre>
-AllocaInst* pa = new AllocaInst(Type::IntTy, 0, "indexLoc");
+AllocaInst* pa = new AllocaInst(Type::Int32Ty, 0, "indexLoc");
 </pre>
 </div>
 
@@ -1806,9 +1919,7 @@ erase function to remove your instruction. For example:</p>
 <div class="doc_code">
 <pre>
 <a href="#Instruction">Instruction</a> *I = .. ;
-<a href="#BasicBlock">BasicBlock</a> *BB = I-&gt;getParent();
-
-BB-&gt;getInstList().erase(I);
+I-&gt;eraseFromParent();
 </pre>
 </div>
 
@@ -1833,9 +1944,9 @@ and <tt>ReplaceInstWithInst</tt>.</p>
 <ul>
   <li><tt>ReplaceInstWithValue</tt>
 
-    <p>This function replaces all uses (within a basic block) of a given
-    instruction with a value, and then removes the original instruction. The
-    following example illustrates the replacement of the result of a particular
+    <p>This function replaces all uses of a given instruction with a value,
+    and then removes the original instruction. The following example
+    illustrates the replacement of the result of a particular
     <tt>AllocaInst</tt> that allocates memory for a single integer with a null
     pointer to an integer.</p>
 
@@ -1845,14 +1956,16 @@ AllocaInst* instToReplace = ...;
 BasicBlock::iterator ii(instToReplace);
 
 ReplaceInstWithValue(instToReplace-&gt;getParent()-&gt;getInstList(), ii,
-                     Constant::getNullValue(PointerType::get(Type::IntTy)));
+                     Constant::getNullValue(PointerType::getUnqual(Type::Int32Ty)));
 </pre></div></li>
 
   <li><tt>ReplaceInstWithInst</tt> 
 
     <p>This function replaces a particular instruction with another
-    instruction. The following example illustrates the replacement of one
-    <tt>AllocaInst</tt> with another.</p>
+    instruction, inserting the new instruction into the basic block at the
+    location where the old instruction was, and replacing any uses of the old
+    instruction with the new instruction. The following example illustrates
+    the replacement of one <tt>AllocaInst</tt> with another.</p>
 
 <div class="doc_code">
 <pre>
@@ -1860,7 +1973,7 @@ AllocaInst* instToReplace = ...;
 BasicBlock::iterator ii(instToReplace);
 
 ReplaceInstWithInst(instToReplace-&gt;getParent()-&gt;getInstList(), ii,
-                    new AllocaInst(Type::IntTy, 0, "ptrToReplacedInt"));
+                    new AllocaInst(Type::Int32Ty, 0, "ptrToReplacedInt"));
 </pre></div></li>
 </ul>
 
@@ -1878,6 +1991,28 @@ ReplaceInstWithValue, ReplaceInstWithInst -->
 
 </div>
 
+<!--_______________________________________________________________________-->
+<div class="doc_subsubsection">
+  <a name="schanges_deletingGV">Deleting <tt>GlobalVariable</tt>s</a>
+</div>
+
+<div class="doc_text">
+
+<p>Deleting a global variable from a module is just as easy as deleting an 
+Instruction. First, you must have a pointer to the global variable that you wish
+ to delete.  You use this pointer to erase it from its parent, the module.
+ For example:</p>
+
+<div class="doc_code">
+<pre>
+<a href="#GlobalVariable">GlobalVariable</a> *GV = .. ;
+
+GV-&gt;eraseFromParent();
+</pre>
+</div>
+
+</div>
+
 <!-- *********************************************************************** -->
 <div class="doc_section">
   <a name="advanced">Advanced Topics</a>
@@ -1912,7 +2047,7 @@ recursive types and late resolution of opaque types makes the situation very
 difficult to handle.  Fortunately, for the most part, our implementation makes
 most clients able to be completely unaware of the nasty internal details.  The
 primary case where clients are exposed to the inner workings of it are when
-building a recursive type.  In addition to this case, the LLVM bytecode reader,
+building a recursive type.  In addition to this case, the LLVM bitcode reader,
 assembly parser, and linker also have to be aware of the inner workings of this
 system.
 </p>
@@ -1956,8 +2091,8 @@ To build this, use the following LLVM APIs:
 // <i>Create the initial outer struct</i>
 <a href="#PATypeHolder">PATypeHolder</a> StructTy = OpaqueType::get();
 std::vector&lt;const Type*&gt; Elts;
-Elts.push_back(PointerType::get(StructTy));
-Elts.push_back(Type::IntTy);
+Elts.push_back(PointerType::getUnqual(StructTy));
+Elts.push_back(Type::Int32Ty);
 StructType *NewSTy = StructType::get(Elts);
 
 // <i>At this point, NewSTy = "{ opaque*, i32 }". Tell VMCore that</i>
@@ -2076,7 +2211,7 @@ names for types.</p>
 by most clients.  It should only be used when iteration over the symbol table 
 names themselves are required, which is very special purpose.  Note that not 
 all LLVM
-<a href="#Value">Value</a>s have names, and those without names (i.e. they have
+<tt><a href="#Value">Value</a></tt>s have names, and those without names (i.e. they have
 an empty name) do not exist in the symbol table.
 </p>
 
@@ -2092,7 +2227,230 @@ insert entries into the symbol table.</p>
 
 
 
-<!-- *********************************************************************** -->
+<!-- ======================================================================= -->
+<div class="doc_subsection">
+  <a name="UserLayout">The <tt>User</tt> and owned <tt>Use</tt> classes' memory layout</a>
+</div>
+
+<div class="doc_text">
+<p>The <tt><a href="http://llvm.org/doxygen/classllvm_1_1User.html">
+User</a></tt> class provides a base for expressing the ownership of <tt>User</tt>
+towards other <tt><a href="http://llvm.org/doxygen/classllvm_1_1Value.html">
+Value</a></tt>s. The <tt><a href="http://llvm.org/doxygen/classllvm_1_1Use.html">
+Use</a></tt> helper class is employed to do the bookkeeping and to facilitate <i>O(1)</i>
+addition and removal.</p>
+
+<!-- ______________________________________________________________________ -->
+<div class="doc_subsubsection">
+  <a name="PATypeHolder">Interaction and relationship between <tt>User</tt> and <tt>Use</tt> objects</a>
+</div>
+
+<div class="doc_text">
+<p>
+A subclass of <tt>User</tt> can choose between incorporating its <tt>Use</tt> objects
+or refer to them out-of-line by means of a pointer. A mixed variant
+(some <tt>Use</tt>s inline others hung off) is impractical and breaks the invariant
+that the <tt>Use</tt> objects belonging to the same <tt>User</tt> form a contiguous array.
+</p>
+</div>
+
+<p>
+We have 2 different layouts in the <tt>User</tt> (sub)classes:
+<ul>
+<li><p>Layout a)
+The <tt>Use</tt> object(s) are inside (resp. at fixed offset) of the <tt>User</tt>
+object and there are a fixed number of them.</p>
+
+<li><p>Layout b)
+The <tt>Use</tt> object(s) are referenced by a pointer to an
+array from the <tt>User</tt> object and there may be a variable
+number of them.</p>
+</ul>
+<p>
+As of v2.4 each layout still possesses a direct pointer to the
+start of the array of <tt>Use</tt>s. Though not mandatory for layout a),
+we stick to this redundancy for the sake of simplicity.
+The <tt>User</tt> object also stores the number of <tt>Use</tt> objects it
+has. (Theoretically this information can also be calculated
+given the scheme presented below.)</p>
+<p>
+Special forms of allocation operators (<tt>operator new</tt>)
+enforce the following memory layouts:</p>
+
+<ul>
+<li><p>Layout a) is modelled by prepending the <tt>User</tt> object by the <tt>Use[]</tt> array.</p>
+
+<pre>
+...---.---.---.---.-------...
+  | P | P | P | P | User
+'''---'---'---'---'-------'''
+</pre>
+
+<li><p>Layout b) is modelled by pointing at the <tt>Use[]</tt> array.</p>
+<pre>
+.-------...
+| User
+'-------'''
+    |
+    v
+    .---.---.---.---...
+    | P | P | P | P |
+    '---'---'---'---'''
+</pre>
+</ul>
+<i>(In the above figures '<tt>P</tt>' stands for the <tt>Use**</tt> that
+    is stored in each <tt>Use</tt> object in the member <tt>Use::Prev</tt>)</i>
+
+<!-- ______________________________________________________________________ -->
+<div class="doc_subsubsection">
+  <a name="PATypeHolder">The waymarking algorithm</a>
+</div>
+
+<div class="doc_text">
+<p>
+Since the <tt>Use</tt> objects are deprived of the direct (back)pointer to
+their <tt>User</tt> objects, there must be a fast and exact method to
+recover it. This is accomplished by the following scheme:</p>
+</div>
+
+A bit-encoding in the 2 LSBits (least significant bits) of the <tt>Use::Prev</tt> allows to find the
+start of the <tt>User</tt> object:
+<ul>
+<li><tt>00</tt> &mdash;&gt; binary digit 0</li>
+<li><tt>01</tt> &mdash;&gt; binary digit 1</li>
+<li><tt>10</tt> &mdash;&gt; stop and calculate (<tt>s</tt>)</li>
+<li><tt>11</tt> &mdash;&gt; full stop (<tt>S</tt>)</li>
+</ul>
+<p>
+Given a <tt>Use*</tt>, all we have to do is to walk till we get
+a stop and we either have a <tt>User</tt> immediately behind or
+we have to walk to the next stop picking up digits
+and calculating the offset:</p>
+<pre>
+.---.---.---.---.---.---.---.---.---.---.---.---.---.---.---.---.----------------
+| 1 | s | 1 | 0 | 1 | 0 | s | 1 | 1 | 0 | s | 1 | 1 | s | 1 | S | User (or User*)
+'---'---'---'---'---'---'---'---'---'---'---'---'---'---'---'---'----------------
+    |+15                |+10            |+6         |+3     |+1
+    |                   |               |           |       |__>
+    |                   |               |           |__________>
+    |                   |               |______________________>
+    |                   |______________________________________>
+    |__________________________________________________________>
+</pre>
+<p>
+Only the significant number of bits need to be stored between the
+stops, so that the <i>worst case is 20 memory accesses</i> when there are
+1000 <tt>Use</tt> objects associated with a <tt>User</tt>.</p>
+
+<!-- ______________________________________________________________________ -->
+<div class="doc_subsubsection">
+  <a name="PATypeHolder">Reference implementation</a>
+</div>
+
+<div class="doc_text">
+<p>
+The following literate Haskell fragment demonstrates the concept:</p>
+</div>
+
+<div class="doc_code">
+<pre>
+> import Test.QuickCheck
+> 
+> digits :: Int -> [Char] -> [Char]
+> digits 0 acc = '0' : acc
+> digits 1 acc = '1' : acc
+> digits n acc = digits (n `div` 2) $ digits (n `mod` 2) acc
+> 
+> dist :: Int -> [Char] -> [Char]
+> dist 0 [] = ['S']
+> dist 0 acc = acc
+> dist 1 acc = let r = dist 0 acc in 's' : digits (length r) r
+> dist n acc = dist (n - 1) $ dist 1 acc
+> 
+> takeLast n ss = reverse $ take n $ reverse ss
+> 
+> test = takeLast 40 $ dist 20 []
+> 
+</pre>
+</div>
+<p>
+Printing &lt;test&gt; gives: <tt>"1s100000s11010s10100s1111s1010s110s11s1S"</tt></p>
+<p>
+The reverse algorithm computes the length of the string just by examining
+a certain prefix:</p>
+
+<div class="doc_code">
+<pre>
+> pref :: [Char] -> Int
+> pref "S" = 1
+> pref ('s':'1':rest) = decode 2 1 rest
+> pref (_:rest) = 1 + pref rest
+> 
+> decode walk acc ('0':rest) = decode (walk + 1) (acc * 2) rest
+> decode walk acc ('1':rest) = decode (walk + 1) (acc * 2 + 1) rest
+> decode walk acc _ = walk + acc
+> 
+</pre>
+</div>
+<p>
+Now, as expected, printing &lt;pref test&gt; gives <tt>40</tt>.</p>
+<p>
+We can <i>quickCheck</i> this with following property:</p>
+
+<div class="doc_code">
+<pre>
+> testcase = dist 2000 []
+> testcaseLength = length testcase
+> 
+> identityProp n = n > 0 && n <= testcaseLength ==> length arr == pref arr
+>     where arr = takeLast n testcase
+> 
+</pre>
+</div>
+<p>
+As expected &lt;quickCheck identityProp&gt; gives:</p>
+
+<pre>
+*Main> quickCheck identityProp
+OK, passed 100 tests.
+</pre>
+<p>
+Let's be a bit more exhaustive:</p>
+
+<div class="doc_code">
+<pre>
+> 
+> deepCheck p = check (defaultConfig { configMaxTest = 500 }) p
+> 
+</pre>
+</div>
+<p>
+And here is the result of &lt;deepCheck identityProp&gt;:</p>
+
+<pre>
+*Main> deepCheck identityProp
+OK, passed 500 tests.
+</pre>
+
+<!-- ______________________________________________________________________ -->
+<div class="doc_subsubsection">
+  <a name="PATypeHolder">Tagging considerations</a>
+</div>
+
+<p>
+To maintain the invariant that the 2 LSBits of each <tt>Use**</tt> in <tt>Use</tt>
+never change after being set up, setters of <tt>Use::Prev</tt> must re-tag the
+new <tt>Use**</tt> on every modification. Accordingly getters must strip the
+tag bits.</p>
+<p>
+For layout b) instead of the <tt>User</tt> we find a pointer (<tt>User*</tt> with LSBit set).
+Following this pointer brings us to the <tt>User</tt>. A portable trick ensures
+that the first bytes of <tt>User</tt> (if interpreted as a pointer) never has
+the LSBit set.</p>
+
+</div>
+
+  <!-- *********************************************************************** -->
 <div class="doc_section">
   <a name="coreclasses">The Core LLVM Class Hierarchy Reference </a>
 </div>
@@ -2195,7 +2553,7 @@ the <tt>lib/VMCore</tt> directory.</p>
   point type.</dd>
   <dt><tt>StructType</tt></dt>
   <dd>Subclass of DerivedTypes for struct types.</dd>
-  <dt><tt>FunctionType</tt></dt>
+  <dt><tt><a name="FunctionType">FunctionType</a></tt></dt>
   <dd>Subclass of DerivedTypes for function types.
     <ul>
       <li><tt>bool isVarArg() const</tt>: Returns true if its a vararg
@@ -2389,7 +2747,7 @@ method. In addition, all LLVM values can be named.  The "name" of the
 </pre>
 </div>
 
-<p><a name="#nameWarning">The name of this instruction is "foo".</a> <b>NOTE</b>
+<p><a name="nameWarning">The name of this instruction is "foo".</a> <b>NOTE</b>
 that the name of any value may be missing (an empty string), so names should
 <b>ONLY</b> be used for debugging (making the source code easier to read,
 debugging printouts), they should not be used to keep track of values or map
@@ -2805,13 +3163,13 @@ is its address (after linking) which is guaranteed to be constant.</p>
     create and what type of linkage the function should have. The <a 
     href="#FunctionType"><tt>FunctionType</tt></a> argument
     specifies the formal arguments and return value for the function. The same
-    <a href="#FunctionTypel"><tt>FunctionType</tt></a> value can be used to
+    <a href="#FunctionType"><tt>FunctionType</tt></a> value can be used to
     create multiple functions. The <tt>Parent</tt> argument specifies the Module
     in which the function is defined. If this argument is provided, the function
     will automatically be inserted into that module's list of
     functions.</p></li>
 
-  <li><tt>bool isExternal()</tt>
+  <li><tt>bool isDeclaration()</tt>
 
     <p>Return whether or not the <tt>Function</tt> has a body defined.  If the
     function is "external", it does not have a body, and thus must be resolved
@@ -3055,7 +3413,7 @@ arguments. An argument has a pointer to the parent Function.</p>
   <a href="http://jigsaw.w3.org/css-validator/check/referer"><img
   src="http://jigsaw.w3.org/css-validator/images/vcss" alt="Valid CSS!"></a>
   <a href="http://validator.w3.org/check/referer"><img
-  src="http://www.w3.org/Icons/valid-html401" alt="Valid HTML 4.01!" /></a>
+  src="http://www.w3.org/Icons/valid-html401" alt="Valid HTML 4.01 Strict"></a>
 
   <a href="mailto:dhurjati@cs.uiuc.edu">Dinakar Dhurjati</a> and
   <a href="mailto:sabre@nondot.org">Chris Lattner</a><br>