<li><a href="#ViewGraph">Viewing graphs while debugging code</a></li>
</ul>
</li>
+ <li><a href="#datastructure">Picking the Right Data Structure for a Task</a>
+ <ul>
+ <li><a href="#ds_sequential">Sequential Containers (std::vector, std::list, etc)</a>
+ <ul>
+ <li><a href="#dss_fixedarrays">Fixed Size Arrays</a></li>
+ <li><a href="#dss_heaparrays">Heap Allocated Arrays</a></li>
+ <li><a href="#dss_smallvector">"llvm/ADT/SmallVector.h"</a></li>
+ <li><a href="#dss_vector"><vector></a></li>
+ <li><a href="#dss_deque"><deque></a></li>
+ <li><a href="#dss_list"><list></a></li>
+ <li><a href="#dss_ilist">llvm/ADT/ilist</a></li>
+ <li><a href="#dss_other">Other Sequential Container Options</a></li>
+ </ul></li>
+ <li><a href="#ds_set">Set-Like Containers (std::set, SmallSet, SetVector, etc)</a>
+ <ul>
+ <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_FoldingSet">"llvm/ADT/FoldingSet.h"</a></li>
+ <li><a href="#dss_set"><set></a></li>
+ <li><a href="#dss_setvector">"llvm/ADT/SetVector.h"</a></li>
+ <li><a href="#dss_uniquevector">"llvm/ADT/UniqueVector.h"</a></li>
+ <li><a href="#dss_otherset">Other Set-Like ContainerOptions</a></li>
+ </ul></li>
+ <li><a href="#ds_map">Map-Like Containers (std::map, DenseMap, etc)</a>
+ <ul>
+ <li><a href="#dss_sortedvectormap">A sorted 'vector'</a></li>
+ <li><a href="#dss_stringmap">"llvm/ADT/StringMap.h"</a></li>
+ <li><a href="#dss_indexedmap">"llvm/ADT/IndexedMap.h"</a></li>
+ <li><a href="#dss_densemap">"llvm/ADT/DenseMap.h"</a></li>
+ <li><a href="#dss_map"><map></a></li>
+ <li><a href="#dss_othermap">Other Map-Like Container Options</a></li>
+ </ul></li>
+ </ul>
+ </li>
<li><a href="#common">Helpful Hints for Common Operations</a>
<ul>
<li><a href="#inspection">Basic Inspection and Traversal Routines</a>
<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>
<!--
<li><a href="#AbstractTypeUser">The AbstractTypeUser Class</a></li>
</ul></li>
- <li><a href="#SymbolTable">The <tt>SymbolTable</tt> class </a></li>
+ <li><a href="#SymbolTable">The <tt>ValueSymbolTable</tt> and <tt>TypeSymbolTable</tt> classes </a></li>
</ul></li>
<li><a href="#coreclasses">The Core LLVM Class Hierarchy Reference</a>
<ul>
+ <li><a href="#Type">The <tt>Type</tt> class</a> </li>
+ <li><a href="#Module">The <tt>Module</tt> class</a></li>
<li><a href="#Value">The <tt>Value</tt> class</a>
+ <ul>
+ <li><a href="#User">The <tt>User</tt> class</a>
<ul>
- <li><a href="#User">The <tt>User</tt> class</a>
+ <li><a href="#Instruction">The <tt>Instruction</tt> class</a></li>
+ <li><a href="#Constant">The <tt>Constant</tt> class</a>
+ <ul>
+ <li><a href="#GlobalValue">The <tt>GlobalValue</tt> class</a>
<ul>
- <li><a href="#Instruction">The <tt>Instruction</tt> class</a>
- <ul>
- <li><a href="#GetElementPtrInst">The <tt>GetElementPtrInst</tt> class</a></li>
- </ul>
- </li>
- <li><a href="#Module">The <tt>Module</tt> class</a></li>
- <li><a href="#Constant">The <tt>Constant</tt> class</a>
- <ul>
- <li><a href="#GlobalValue">The <tt>GlobalValue</tt> class</a>
- <ul>
- <li><a href="#BasicBlock">The <tt>BasicBlock</tt>class</a></li>
- <li><a href="#Function">The <tt>Function</tt> class</a></li>
- <li><a href="#GlobalVariable">The <tt>GlobalVariable</tt> class</a></li>
- </ul>
- </li>
- </ul>
- </li>
- </ul>
- </li>
- <li><a href="#Type">The <tt>Type</tt> class</a> </li>
- <li><a href="#Argument">The <tt>Argument</tt> class</a></li>
+ <li><a href="#Function">The <tt>Function</tt> class</a></li>
+ <li><a href="#GlobalVariable">The <tt>GlobalVariable</tt> class</a></li>
+ </ul>
+ </li>
+ </ul>
+ </li>
</ul>
+ </li>
+ <li><a href="#BasicBlock">The <tt>BasicBlock</tt> class</a></li>
+ <li><a href="#Argument">The <tt>Argument</tt> class</a></li>
+ </ul>
</li>
</ul>
</li>
<p>The <tt>STATISTIC</tt> macro defines a static variable, whose name is
specified by the first argument. The pass name is taken from the DEBUG_TYPE
macro, and the description is taken from the second argument. The variable
- defined ("NumXForms" in this case) acts like an unsigned int.</p></li>
+ defined ("NumXForms" in this case) acts like an unsigned integer.</p></li>
<li><p>Whenever you make a transformation, bump the counter:</p>
</pre>
</div>
- <p> When running <tt>gccas</tt> on a C file from the SPEC benchmark
+ <p> When running <tt>opt</tt> on a C file from the SPEC benchmark
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
toolkit, and make sure 'dot' and 'gv' are in your path. If you are running on
Mac OS/X, download and install the Mac OS/X <a
href="http://www.pixelglow.com/graphviz/">Graphviz program</a>, and add
-<tt>/Applications/Graphviz.app/Contents/MacOS/</tt> (or whereever you install
+<tt>/Applications/Graphviz.app/Contents/MacOS/</tt> (or wherever you install
it) to your path. Once in your system and path are set up, rerun the LLVM
configure script and rebuild LLVM to enable this functionality.</p>
<p><tt>SelectionDAG</tt> has been extended to make it easier to locate
<i>interesting</i> nodes in large complex graphs. From gdb, if you
<tt>call DAG.setGraphColor(<i>node</i>, "<i>color</i>")</tt>, then the
-next <tt>call DAG.viewGraph()</tt> would hilight the node in the
+next <tt>call DAG.viewGraph()</tt> would highlight the node in the
specified color (choices of colors can be found at <a
-href="http://www.graphviz.org/doc/info/colors.html">Colors<a>.) More
+href="http://www.graphviz.org/doc/info/colors.html">colors</a>.) More
complex node attributes can be provided with <tt>call
DAG.setGraphAttrs(<i>node</i>, "<i>attributes</i>")</tt> (choices can be
found at <a href="http://www.graphviz.org/doc/info/attrs.html">Graph
</div>
-
<!-- *********************************************************************** -->
<div class="doc_section">
- <a name="common">Helpful Hints for Common Operations</a>
+ <a name="datastructure">Picking the Right Data Structure for a Task</a>
</div>
<!-- *********************************************************************** -->
<div class="doc_text">
-<p>This section describes how to perform some very simple transformations of
-LLVM code. This is meant to give examples of common idioms used, showing the
-practical side of LLVM transformations. <p> Because this is a "how-to" section,
-you should also read about the main classes that you will be working with. The
-<a href="#coreclasses">Core LLVM Class Hierarchy Reference</a> contains details
-and descriptions of the main classes that you should know about.</p>
+<p>LLVM has a plethora of data structures in the <tt>llvm/ADT/</tt> directory,
+ and we commonly use STL data structures. This section describes the trade-offs
+ you should consider when you pick one.</p>
+
+<p>
+The first step is a choose your own adventure: do you want a sequential
+container, a set-like container, or a map-like container? The most important
+thing when choosing a container is the algorithmic properties of how you plan to
+access the container. Based on that, you should use:</p>
+
+<ul>
+<li>a <a href="#ds_map">map-like</a> container if you need efficient look-up
+ of an value based on another value. Map-like containers also support
+ efficient queries for containment (whether a key is in the map). Map-like
+ containers generally do not support efficient reverse mapping (values to
+ keys). If you need that, use two maps. Some map-like containers also
+ support efficient iteration through the keys in sorted order. Map-like
+ containers are the most expensive sort, only use them if you need one of
+ these capabilities.</li>
+
+<li>a <a href="#ds_set">set-like</a> container if you need to put a bunch of
+ stuff into a container that automatically eliminates duplicates. Some
+ set-like containers support efficient iteration through the elements in
+ sorted order. Set-like containers are more expensive than sequential
+ containers.
+</li>
+
+<li>a <a href="#ds_sequential">sequential</a> container provides
+ the most efficient way to add elements and keeps track of the order they are
+ added to the collection. They permit duplicates and support efficient
+ iteration, but do not support efficient look-up based on a key.
+</li>
+
+</ul>
+
+<p>
+Once the proper category of container is determined, you can fine tune the
+memory use, constant factors, and cache behaviors of access by intelligently
+picking a member of the category. Note that constant factors and cache behavior
+can be a big deal. If you have a vector that usually only contains a few
+elements (but could contain many), for example, it's much better to use
+<a href="#dss_smallvector">SmallVector</a> than <a href="#dss_vector">vector</a>
+. Doing so avoids (relatively) expensive malloc/free calls, which dwarf the
+cost of adding the elements to the container. </p>
</div>
-<!-- NOTE: this section should be heavy on example code -->
<!-- ======================================================================= -->
<div class="doc_subsection">
- <a name="inspection">Basic Inspection and Traversal Routines</a>
+ <a name="ds_sequential">Sequential Containers (std::vector, std::list, etc)</a>
</div>
<div class="doc_text">
-
-<p>The LLVM compiler infrastructure have many different data structures that may
-be traversed. Following the example of the C++ standard template library, the
-techniques used to traverse these various data structures are all basically the
-same. For a enumerable sequence of values, the <tt>XXXbegin()</tt> function (or
-method) returns an iterator to the start of the sequence, the <tt>XXXend()</tt>
-function returns an iterator pointing to one past the last valid element of the
-sequence, and there is some <tt>XXXiterator</tt> data type that is common
-between the two operations.</p>
-
-<p>Because the pattern for iteration is common across many different aspects of
-the program representation, the standard template library algorithms may be used
-on them, and it is easier to remember how to iterate. First we show a few common
-examples of the data structures that need to be traversed. Other data
-structures are traversed in very similar ways.</p>
-
+There are a variety of sequential containers available for you, based on your
+needs. Pick the first in this section that will do what you want.
</div>
<!-- _______________________________________________________________________ -->
<div class="doc_subsubsection">
- <a name="iterate_function">Iterating over the </a><a
- href="#BasicBlock"><tt>BasicBlock</tt></a>s in a <a
- href="#Function"><tt>Function</tt></a>
+ <a name="dss_fixedarrays">Fixed Size Arrays</a>
</div>
<div class="doc_text">
-
-<p>It's quite common to have a <tt>Function</tt> instance that you'd like to
-transform in some way; in particular, you'd like to manipulate its
-<tt>BasicBlock</tt>s. To facilitate this, you'll need to iterate over all of
-the <tt>BasicBlock</tt>s that constitute the <tt>Function</tt>. The following is
-an example that prints the name of a <tt>BasicBlock</tt> and the number of
-<tt>Instruction</tt>s it contains:</p>
-
-<div class="doc_code">
-<pre>
-// <i>func is a pointer to a Function instance</i>
-for (Function::iterator i = func->begin(), e = func->end(); i != e; ++i)
- // <i>Print out the name of the basic block if it has one, and then the</i>
- // <i>number of instructions that it contains</i>
- llvm::cerr << "Basic block (name=" << i->getName() << ") has "
- << i->size() << " instructions.\n";
-</pre>
+<p>Fixed size arrays are very simple and very fast. They are good if you know
+exactly how many elements you have, or you have a (low) upper bound on how many
+you have.</p>
</div>
-<p>Note that i can be used as if it were a pointer for the purposes of
-invoking member functions of the <tt>Instruction</tt> class. This is
-because the indirection operator is overloaded for the iterator
-classes. In the above code, the expression <tt>i->size()</tt> is
-exactly equivalent to <tt>(*i).size()</tt> just like you'd expect.</p>
+<!-- _______________________________________________________________________ -->
+<div class="doc_subsubsection">
+ <a name="dss_heaparrays">Heap Allocated Arrays</a>
+</div>
+<div class="doc_text">
+<p>Heap allocated arrays (new[] + delete[]) are also simple. They are good if
+the number of elements is variable, if you know how many elements you will need
+before the array is allocated, and if the array is usually large (if not,
+consider a <a href="#dss_smallvector">SmallVector</a>). The cost of a heap
+allocated array is the cost of the new/delete (aka malloc/free). Also note that
+if you are allocating an array of a type with a constructor, the constructor and
+destructors will be run for every element in the array (re-sizable vectors only
+construct those elements actually used).</p>
</div>
<!-- _______________________________________________________________________ -->
<div class="doc_subsubsection">
- <a name="iterate_basicblock">Iterating over the </a><a
- href="#Instruction"><tt>Instruction</tt></a>s in a <a
- href="#BasicBlock"><tt>BasicBlock</tt></a>
+ <a name="dss_smallvector">"llvm/ADT/SmallVector.h"</a>
</div>
<div class="doc_text">
+<p><tt>SmallVector<Type, N></tt> is a simple class that looks and smells
+just like <tt>vector<Type></tt>:
+it supports efficient iteration, lays out elements in memory order (so you can
+do pointer arithmetic between elements), supports efficient push_back/pop_back
+operations, supports efficient random access to its elements, etc.</p>
-<p>Just like when dealing with <tt>BasicBlock</tt>s in <tt>Function</tt>s, it's
-easy to iterate over the individual instructions that make up
-<tt>BasicBlock</tt>s. Here's a code snippet that prints out each instruction in
-a <tt>BasicBlock</tt>:</p>
+<p>The advantage of SmallVector is that it allocates space for
+some number of elements (N) <b>in the object itself</b>. Because of this, if
+the SmallVector is dynamically smaller than N, no malloc is performed. This can
+be a big win in cases where the malloc/free call is far more expensive than the
+code that fiddles around with the elements.</p>
-<div class="doc_code">
-<pre>
-// <i>blk is a pointer to a BasicBlock instance</i>
-for (BasicBlock::iterator i = blk->begin(), e = blk->end(); i != e; ++i)
- // <i>The next statement works since operator<<(ostream&,...)</i>
- // <i>is overloaded for Instruction&</i>
- llvm::cerr << *i << "\n";
-</pre>
-</div>
+<p>This is good for vectors that are "usually small" (e.g. the number of
+predecessors/successors of a block is usually less than 8). On the other hand,
+this makes the size of the SmallVector itself large, so you don't want to
+allocate lots of them (doing so will waste a lot of space). As such,
+SmallVectors are most useful when on the stack.</p>
-<p>However, this isn't really the best way to print out the contents of a
-<tt>BasicBlock</tt>! Since the ostream operators are overloaded for virtually
-anything you'll care about, you could have just invoked the print routine on the
-basic block itself: <tt>llvm::cerr << *blk << "\n";</tt>.</p>
+<p>SmallVector also provides a nice portable and efficient replacement for
+<tt>alloca</tt>.</p>
</div>
<!-- _______________________________________________________________________ -->
<div class="doc_subsubsection">
- <a name="iterate_institer">Iterating over the </a><a
- href="#Instruction"><tt>Instruction</tt></a>s in a <a
- href="#Function"><tt>Function</tt></a>
+ <a name="dss_vector"><vector></a>
</div>
<div class="doc_text">
+<p>
+std::vector is well loved and respected. It is useful when SmallVector isn't:
+when the size of the vector is often large (thus the small optimization will
+rarely be a benefit) or if you will be allocating many instances of the vector
+itself (which would waste space for elements that aren't in the container).
+vector is also useful when interfacing with code that expects vectors :).
+</p>
-<p>If you're finding that you commonly iterate over a <tt>Function</tt>'s
-<tt>BasicBlock</tt>s and then that <tt>BasicBlock</tt>'s <tt>Instruction</tt>s,
-<tt>InstIterator</tt> should be used instead. You'll need to include <a
-href="/doxygen/InstIterator_8h-source.html"><tt>llvm/Support/InstIterator.h</tt></a>,
-and then instantiate <tt>InstIterator</tt>s explicitly in your code. Here's a
-small example that shows how to dump all instructions in a function to the standard error stream:<p>
+<p>One worthwhile note about std::vector: avoid code like this:</p>
<div class="doc_code">
<pre>
-#include "<a href="/doxygen/InstIterator_8h-source.html">llvm/Support/InstIterator.h</a>"
-
-// <i>F is a ptr to a Function instance</i>
-for (inst_iterator i = inst_begin(F), e = inst_end(F); i != e; ++i)
- llvm::cerr << *i << "\n";
+for ( ... ) {
+ std::vector<foo> V;
+ use V;
+}
</pre>
</div>
-<p>Easy, isn't it? You can also use <tt>InstIterator</tt>s to fill a
-worklist with its initial contents. For example, if you wanted to
-initialize a worklist to contain all instructions in a <tt>Function</tt>
-F, all you would need to do is something like:</p>
+<p>Instead, write this as:</p>
<div class="doc_code">
<pre>
-std::set<Instruction*> worklist;
-worklist.insert(inst_begin(F), inst_end(F));
+std::vector<foo> V;
+for ( ... ) {
+ use V;
+ V.clear();
+}
</pre>
</div>
-<p>The STL set <tt>worklist</tt> would now contain all instructions in the
-<tt>Function</tt> pointed to by F.</p>
+<p>Doing so will save (at least) one heap allocation and free per iteration of
+the loop.</p>
</div>
<!-- _______________________________________________________________________ -->
<div class="doc_subsubsection">
- <a name="iterate_convert">Turning an iterator into a class pointer (and
- vice-versa)</a>
+ <a name="dss_deque"><deque></a>
</div>
<div class="doc_text">
+<p>std::deque is, in some senses, a generalized version of std::vector. Like
+std::vector, it provides constant time random access and other similar
+properties, but it also provides efficient access to the front of the list. It
+does not guarantee continuity of elements within memory.</p>
-<p>Sometimes, it'll be useful to grab a reference (or pointer) to a class
-instance when all you've got at hand is an iterator. Well, extracting
-a reference or a pointer from an iterator is very straight-forward.
-Assuming that <tt>i</tt> is a <tt>BasicBlock::iterator</tt> and <tt>j</tt>
-is a <tt>BasicBlock::const_iterator</tt>:</p>
-
-<div class="doc_code">
-<pre>
-Instruction& inst = *i; // <i>Grab reference to instruction reference</i>
-Instruction* pinst = &*i; // <i>Grab pointer to instruction reference</i>
-const Instruction& inst = *j;
-</pre>
+<p>In exchange for this extra flexibility, std::deque has significantly higher
+constant factor costs than std::vector. If possible, use std::vector or
+something cheaper.</p>
</div>
-<p>However, the iterators you'll be working with in the LLVM framework are
-special: they will automatically convert to a ptr-to-instance type whenever they
-need to. Instead of dereferencing the iterator and then taking the address of
-the result, you can simply assign the iterator to the proper pointer type and
-you get the dereference and address-of operation as a result of the assignment
-(behind the scenes, this is a result of overloading casting mechanisms). Thus
-the last line of the last example,</p>
-
-<div class="doc_code">
-<pre>
-Instruction* pinst = &*i;
-</pre>
+<!-- _______________________________________________________________________ -->
+<div class="doc_subsubsection">
+ <a name="dss_list"><list></a>
</div>
-<p>is semantically equivalent to</p>
+<div class="doc_text">
+<p>std::list is an extremely inefficient class that is rarely useful.
+It performs a heap allocation for every element inserted into it, thus having an
+extremely high constant factor, particularly for small data types. std::list
+also only supports bidirectional iteration, not random access iteration.</p>
-<div class="doc_code">
-<pre>
-Instruction* pinst = i;
-</pre>
+<p>In exchange for this high cost, std::list supports efficient access to both
+ends of the list (like std::deque, but unlike std::vector or SmallVector). In
+addition, the iterator invalidation characteristics of std::list are stronger
+than that of a vector class: inserting or removing an element into the list does
+not invalidate iterator or pointers to other elements in the list.</p>
</div>
-<p>It's also possible to turn a class pointer into the corresponding iterator,
-and this is a constant time operation (very efficient). The following code
-snippet illustrates use of the conversion constructors provided by LLVM
-iterators. By using these, you can explicitly grab the iterator of something
-without actually obtaining it via iteration over some structure:</p>
-
-<div class="doc_code">
-<pre>
-void printNextInstruction(Instruction* inst) {
- BasicBlock::iterator it(inst);
- ++it; // <i>After this line, it refers to the instruction after *inst</i>
- if (it != inst->getParent()->end()) llvm::cerr << *it << "\n";
-}
-</pre>
+<!-- _______________________________________________________________________ -->
+<div class="doc_subsubsection">
+ <a name="dss_ilist">llvm/ADT/ilist</a>
</div>
+<div class="doc_text">
+<p><tt>ilist<T></tt> implements an 'intrusive' doubly-linked list. It is
+intrusive, because it requires the element to store and provide access to the
+prev/next pointers for the list.</p>
+
+<p>ilist has the same drawbacks as std::list, and additionally requires an
+ilist_traits implementation for the element type, but it provides some novel
+characteristics. In particular, it can efficiently store polymorphic objects,
+the traits class is informed when an element is inserted or removed from the
+list, and ilists are guaranteed to support a constant-time splice operation.
+</p>
+
+<p>These properties are exactly what we want for things like Instructions and
+basic blocks, which is why these are implemented with ilists.</p>
</div>
-<!--_______________________________________________________________________-->
+<!-- _______________________________________________________________________ -->
<div class="doc_subsubsection">
- <a name="iterate_complex">Finding call sites: a slightly more complex
- example</a>
+ <a name="dss_other">Other Sequential Container options</a>
</div>
<div class="doc_text">
+<p>Other STL containers are available, such as std::string.</p>
-<p>Say that you're writing a FunctionPass and would like to count all the
-locations in the entire module (that is, across every <tt>Function</tt>) where a
-certain function (i.e., some <tt>Function</tt>*) is already in scope. As you'll
-learn later, you may want to use an <tt>InstVisitor</tt> to accomplish this in a
-much more straight-forward manner, but this example will allow us to explore how
-you'd do it if you didn't have <tt>InstVisitor</tt> around. In pseudocode, this
-is what we want to do:</p>
+<p>There are also various STL adapter classes such as std::queue,
+std::priority_queue, std::stack, etc. These provide simplified access to an
+underlying container but don't affect the cost of the container itself.</p>
-<div class="doc_code">
-<pre>
-initialize callCounter to zero
-for each Function f in the Module
- for each BasicBlock b in f
- for each Instruction i in b
- if (i is a CallInst and calls the given function)
- increment callCounter
-</pre>
</div>
-<p>And the actual code is (remember, because we're writing a
-<tt>FunctionPass</tt>, our <tt>FunctionPass</tt>-derived class simply has to
-override the <tt>runOnFunction</tt> method):</p>
-<div class="doc_code">
-<pre>
-Function* targetFunc = ...;
+<!-- ======================================================================= -->
+<div class="doc_subsection">
+ <a name="ds_set">Set-Like Containers (std::set, SmallSet, SetVector, etc)</a>
+</div>
-class OurFunctionPass : public FunctionPass {
- public:
- OurFunctionPass(): callCounter(0) { }
+<div class="doc_text">
- virtual runOnFunction(Function& F) {
- for (Function::iterator b = F.begin(), be = F.end(); b != be; ++b) {
- for (BasicBlock::iterator i = b->begin(); ie = b->end(); i != ie; ++i) {
- if (<a href="#CallInst">CallInst</a>* callInst = <a href="#isa">dyn_cast</a><<a
- href="#CallInst">CallInst</a>>(&*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>
+<p>Set-like containers are useful when you need to canonicalize multiple values
+into a single representation. There are several different choices for how to do
+this, providing various trade-offs.</p>
- if (callInst->getCalledFunction() == targetFunc)
- ++callCounter;
- }
- }
- }
- }
+</div>
- private:
- unsigned callCounter;
-};
-</pre>
+
+<!-- _______________________________________________________________________ -->
+<div class="doc_subsubsection">
+ <a name="dss_sortedvectorset">A sorted 'vector'</a>
</div>
+<div class="doc_text">
+
+<p>If you intend to insert a lot of elements, then do a lot of queries, a
+great approach is to use a vector (or other sequential container) with
+std::sort+std::unique to remove duplicates. This approach works really well if
+your usage pattern has these two distinct phases (insert then query), and can be
+coupled with a good choice of <a href="#ds_sequential">sequential container</a>.
+</p>
+
+<p>
+This combination provides the several nice properties: the result data is
+contiguous in memory (good for cache locality), has few allocations, is easy to
+address (iterators in the final vector are just indices or pointers), and can be
+efficiently queried with a standard binary or radix search.</p>
+
</div>
-<!--_______________________________________________________________________-->
+<!-- _______________________________________________________________________ -->
<div class="doc_subsubsection">
- <a name="calls_and_invokes">Treating calls and invokes the same way</a>
+ <a name="dss_smallset">"llvm/ADT/SmallSet.h"</a>
</div>
<div class="doc_text">
-<p>You may have noticed that the previous example was a bit oversimplified in
-that it did not deal with call sites generated by 'invoke' instructions. In
-this, and in other situations, you may find that you want to treat
-<tt>CallInst</tt>s and <tt>InvokeInst</tt>s the same way, even though their
-most-specific common base class is <tt>Instruction</tt>, which includes lots of
-less closely-related things. For these cases, LLVM provides a handy wrapper
-class called <a
-href="http://llvm.org/doxygen/classllvm_1_1CallSite.html"><tt>CallSite</tt></a>.
-It is essentially a wrapper around an <tt>Instruction</tt> pointer, with some
-methods that provide functionality common to <tt>CallInst</tt>s and
-<tt>InvokeInst</tt>s.</p>
+<p>If you have a set-like data structure that is usually small and whose elements
+are reasonably small, a <tt>SmallSet<Type, N></tt> is a good choice. This set
+has space for N elements in place (thus, if the set is dynamically smaller than
+N, no malloc traffic is required) and accesses them with a simple linear search.
+When the set grows beyond 'N' elements, it allocates a more expensive representation that
+guarantees efficient access (for most types, it falls back to std::set, but for
+pointers it uses something far better, <a
+href="#dss_smallptrset">SmallPtrSet</a>).</p>
-<p>This class has "value semantics": it should be passed by value, not by
-reference and it should not be dynamically allocated or deallocated using
-<tt>operator new</tt> or <tt>operator delete</tt>. It is efficiently copyable,
-assignable and constructable, with costs equivalents to that of a bare pointer.
-If you look at its definition, it has only a single pointer member.</p>
+<p>The magic of this class is that it handles small sets extremely efficiently,
+but gracefully handles extremely large sets without loss of efficiency. The
+drawback is that the interface is quite small: it supports insertion, queries
+and erasing, but does not support iteration.</p>
</div>
-<!--_______________________________________________________________________-->
+<!-- _______________________________________________________________________ -->
<div class="doc_subsubsection">
- <a name="iterate_chains">Iterating over def-use & use-def chains</a>
+ <a name="dss_smallptrset">"llvm/ADT/SmallPtrSet.h"</a>
</div>
<div class="doc_text">
-<p>Frequently, we might have an instance of the <a
-href="/doxygen/classllvm_1_1Value.html">Value Class</a> and we want to
-determine which <tt>User</tt>s use the <tt>Value</tt>. The list of all
-<tt>User</tt>s of a particular <tt>Value</tt> is called a <i>def-use</i> chain.
-For example, let's say we have a <tt>Function*</tt> named <tt>F</tt> to a
-particular function <tt>foo</tt>. Finding all of the instructions that
-<i>use</i> <tt>foo</tt> is as simple as iterating over the <i>def-use</i> chain
-of <tt>F</tt>:</p>
+<p>SmallPtrSet has all the advantages of SmallSet (and a SmallSet of pointers is
+transparently implemented with a SmallPtrSet), but also supports iterators. If
+more than 'N' insertions are performed, a single quadratically
+probed hash table is allocated and grows as needed, providing extremely
+efficient access (constant time insertion/deleting/queries with low constant
+factors) and is very stingy with malloc traffic.</p>
-<div class="doc_code">
-<pre>
-Function* F = ...;
+<p>Note that, unlike std::set, the iterators of SmallPtrSet are invalidated
+whenever an insertion occurs. Also, the values visited by the iterators are not
+visited in sorted order.</p>
-for (Value::use_iterator i = F->use_begin(), e = F->use_end(); i != e; ++i)
- if (Instruction *Inst = dyn_cast<Instruction>(*i)) {
- llvm::cerr << "F is used in instruction:\n";
- llvm::cerr << *Inst << "\n";
- }
-</pre>
</div>
-<p>Alternately, it's common to have an instance of the <a
-href="/doxygen/classllvm_1_1User.html">User Class</a> and need to know what
-<tt>Value</tt>s are used by it. The list of all <tt>Value</tt>s used by a
-<tt>User</tt> is known as a <i>use-def</i> chain. Instances of class
-<tt>Instruction</tt> are common <tt>User</tt>s, so we might want to iterate over
-all of the values that a particular instruction uses (that is, the operands of
-the particular <tt>Instruction</tt>):</p>
+<!-- _______________________________________________________________________ -->
+<div class="doc_subsubsection">
+ <a name="dss_FoldingSet">"llvm/ADT/FoldingSet.h"</a>
+</div>
-<div class="doc_code">
-<pre>
-Instruction* pi = ...;
+<div class="doc_text">
-for (User::op_iterator i = pi->op_begin(), e = pi->op_end(); i != e; ++i) {
- Value* v = *i;
- // <i>...</i>
-}
-</pre>
-</div>
+<p>
+FoldingSet is an aggregate class that is really good at uniquing
+expensive-to-create or polymorphic objects. It is a combination of a chained
+hash table with intrusive links (uniqued objects are required to inherit from
+FoldingSetNode) that uses <a href="#dss_smallvector">SmallVector</a> as part of
+its ID process.</p>
+
+<p>Consider a case where you want to implement a "getOrCreateFoo" method for
+a complex object (for example, a node in the code generator). The client has a
+description of *what* it wants to generate (it knows the opcode and all the
+operands), but we don't want to 'new' a node, then try inserting it into a set
+only to find out it already exists, at which point we would have to delete it
+and return the node that already exists.
+</p>
-<!--
- def-use chains ("finding all users of"): Value::use_begin/use_end
- use-def chains ("finding all values used"): User::op_begin/op_end [op=operand]
--->
+<p>To support this style of client, FoldingSet perform a query with a
+FoldingSetNodeID (which wraps SmallVector) that can be used to describe the
+element that we want to query for. The query either returns the element
+matching the ID or it returns an opaque ID that indicates where insertion should
+take place. Construction of the ID usually does not require heap traffic.</p>
+
+<p>Because FoldingSet uses intrusive links, it can support polymorphic objects
+in the set (for example, you can have SDNode instances mixed with LoadSDNodes).
+Because the elements are individually allocated, pointers to the elements are
+stable: inserting or removing elements does not invalidate any pointers to other
+elements.
+</p>
</div>
-<!-- ======================================================================= -->
-<div class="doc_subsection">
- <a name="simplechanges">Making simple changes</a>
+<!-- _______________________________________________________________________ -->
+<div class="doc_subsubsection">
+ <a name="dss_set"><set></a>
</div>
<div class="doc_text">
-<p>There are some primitive transformation operations present in the LLVM
-infrastructure that are worth knowing about. When performing
-transformations, it's fairly common to manipulate the contents of basic
-blocks. This section describes some of the common methods for doing so
-and gives example code.</p>
+<p><tt>std::set</tt> is a reasonable all-around set class, which is decent at
+many things but great at nothing. std::set allocates memory for each element
+inserted (thus it is very malloc intensive) and typically stores three pointers
+per element in the set (thus adding a large amount of per-element space
+overhead). It offers guaranteed log(n) performance, which is not particularly
+fast from a complexity standpoint (particularly if the elements of the set are
+expensive to compare, like strings), and has extremely high constant factors for
+lookup, insertion and removal.</p>
+
+<p>The advantages of std::set are that its iterators are stable (deleting or
+inserting an element from the set does not affect iterators or pointers to other
+elements) and that iteration over the set is guaranteed to be in sorted order.
+If the elements in the set are large, then the relative overhead of the pointers
+and malloc traffic is not a big deal, but if the elements of the set are small,
+std::set is almost never a good choice.</p>
</div>
-<!--_______________________________________________________________________-->
+<!-- _______________________________________________________________________ -->
<div class="doc_subsubsection">
- <a name="schanges_creating">Creating and inserting new
- <tt>Instruction</tt>s</a>
+ <a name="dss_setvector">"llvm/ADT/SetVector.h"</a>
</div>
<div class="doc_text">
+<p>LLVM's SetVector<Type> is an adapter class that combines your choice of
+a set-like container along with a <a href="#ds_sequential">Sequential
+Container</a>. The important property
+that this provides is efficient insertion with uniquing (duplicate elements are
+ignored) with iteration support. It implements this by inserting elements into
+both a set-like container and the sequential container, using the set-like
+container for uniquing and the sequential container for iteration.
+</p>
-<p><i>Instantiating Instructions</i></p>
+<p>The difference between SetVector and other sets is that the order of
+iteration is guaranteed to match the order of insertion into the SetVector.
+This property is really important for things like sets of pointers. Because
+pointer values are non-deterministic (e.g. vary across runs of the program on
+different machines), iterating over the pointers in the set will
+not be in a well-defined order.</p>
-<p>Creation of <tt>Instruction</tt>s is straight-forward: simply call the
-constructor for the kind of instruction to instantiate and provide the necessary
-parameters. For example, an <tt>AllocaInst</tt> only <i>requires</i> a
-(const-ptr-to) <tt>Type</tt>. Thus:</p>
+<p>
+The drawback of SetVector is that it requires twice as much space as a normal
+set and has the sum of constant factors from the set-like container and the
+sequential container that it uses. Use it *only* if you need to iterate over
+the elements in a deterministic order. SetVector is also expensive to delete
+elements out of (linear time), unless you use it's "pop_back" method, which is
+faster.
+</p>
+
+<p>SetVector is an adapter class that defaults to using std::vector and std::set
+for the underlying containers, so it is quite expensive. However,
+<tt>"llvm/ADT/SetVector.h"</tt> also provides a SmallSetVector class, which
+defaults to using a SmallVector and SmallSet of a specified size. If you use
+this, and if your sets are dynamically smaller than N, you will save a lot of
+heap traffic.</p>
-<div class="doc_code">
-<pre>
-AllocaInst* ai = new AllocaInst(Type::IntTy);
-</pre>
</div>
-<p>will create an <tt>AllocaInst</tt> instance that represents the allocation of
-one integer in the current stack frame, at runtime. Each <tt>Instruction</tt>
-subclass is likely to have varying default parameters which change the semantics
-of the instruction, so refer to the <a
-href="/doxygen/classllvm_1_1Instruction.html">doxygen documentation for the subclass of
-Instruction</a> that you're interested in instantiating.</p>
+<!-- _______________________________________________________________________ -->
+<div class="doc_subsubsection">
+ <a name="dss_uniquevector">"llvm/ADT/UniqueVector.h"</a>
+</div>
-<p><i>Naming values</i></p>
+<div class="doc_text">
-<p>It is very useful to name the values of instructions when you're able to, as
-this facilitates the debugging of your transformations. If you end up looking
-at generated LLVM machine code, you definitely want to have logical names
-associated with the results of instructions! By supplying a value for the
-<tt>Name</tt> (default) parameter of the <tt>Instruction</tt> constructor, you
-associate a logical name with the result of the instruction's execution at
-runtime. For example, say that I'm writing a transformation that dynamically
-allocates space for an integer on the stack, and that integer is going to be
-used as some kind of index by some other code. To accomplish this, I place an
-<tt>AllocaInst</tt> at the first point in the first <tt>BasicBlock</tt> of some
-<tt>Function</tt>, and I'm intending to use it within the same
-<tt>Function</tt>. I might do:</p>
+<p>
+UniqueVector is similar to <a href="#dss_setvector">SetVector</a>, but it
+retains a unique ID for each element inserted into the set. It internally
+contains a map and a vector, and it assigns a unique ID for each value inserted
+into the set.</p>
+
+<p>UniqueVector is very expensive: its cost is the sum of the cost of
+maintaining both the map and vector, it has high complexity, high constant
+factors, and produces a lot of malloc traffic. It should be avoided.</p>
-<div class="doc_code">
-<pre>
-AllocaInst* pa = new AllocaInst(Type::IntTy, 0, "indexLoc");
-</pre>
</div>
-<p>where <tt>indexLoc</tt> is now the logical name of the instruction's
-execution value, which is a pointer to an integer on the runtime stack.</p>
-<p><i>Inserting instructions</i></p>
+<!-- _______________________________________________________________________ -->
+<div class="doc_subsubsection">
+ <a name="dss_otherset">Other Set-Like Container Options</a>
+</div>
-<p>There are essentially two ways to insert an <tt>Instruction</tt>
-into an existing sequence of instructions that form a <tt>BasicBlock</tt>:</p>
+<div class="doc_text">
-<ul>
- <li>Insertion into an explicit instruction list
+<p>
+The STL provides several other options, such as std::multiset and the various
+"hash_set" like containers (whether from C++ TR1 or from the SGI library).</p>
- <p>Given a <tt>BasicBlock* pb</tt>, an <tt>Instruction* pi</tt> within that
- <tt>BasicBlock</tt>, and a newly-created instruction we wish to insert
- before <tt>*pi</tt>, we do the following: </p>
+<p>std::multiset is useful if you're not interested in elimination of
+duplicates, but has all the drawbacks of std::set. A sorted vector (where you
+don't delete duplicate entries) or some other approach is almost always
+better.</p>
-<div class="doc_code">
-<pre>
-BasicBlock *pb = ...;
-Instruction *pi = ...;
-Instruction *newInst = new Instruction(...);
+<p>The various hash_set implementations (exposed portably by
+"llvm/ADT/hash_set") is a simple chained hashtable. This algorithm is as malloc
+intensive as std::set (performing an allocation for each element inserted,
+thus having really high constant factors) but (usually) provides O(1)
+insertion/deletion of elements. This can be useful if your elements are large
+(thus making the constant-factor cost relatively low) or if comparisons are
+expensive. Element iteration does not visit elements in a useful order.</p>
-pb->getInstList().insert(pi, newInst); // <i>Inserts newInst before pi in pb</i>
-</pre>
</div>
- <p>Appending to the end of a <tt>BasicBlock</tt> is so common that
- the <tt>Instruction</tt> class and <tt>Instruction</tt>-derived
- classes provide constructors which take a pointer to a
- <tt>BasicBlock</tt> to be appended to. For example code that
- looked like: </p>
-
-<div class="doc_code">
-<pre>
-BasicBlock *pb = ...;
-Instruction *newInst = new Instruction(...);
-
-pb->getInstList().push_back(newInst); // <i>Appends newInst to pb</i>
-</pre>
+<!-- ======================================================================= -->
+<div class="doc_subsection">
+ <a name="ds_map">Map-Like Containers (std::map, DenseMap, etc)</a>
</div>
- <p>becomes: </p>
+<div class="doc_text">
+Map-like containers are useful when you want to associate data to a key. As
+usual, there are a lot of different ways to do this. :)
+</div>
-<div class="doc_code">
-<pre>
-BasicBlock *pb = ...;
-Instruction *newInst = new Instruction(..., pb);
-</pre>
+<!-- _______________________________________________________________________ -->
+<div class="doc_subsubsection">
+ <a name="dss_sortedvectormap">A sorted 'vector'</a>
</div>
- <p>which is much cleaner, especially if you are creating
- long instruction streams.</p></li>
+<div class="doc_text">
- <li>Insertion into an implicit instruction list
+<p>
+If your usage pattern follows a strict insert-then-query approach, you can
+trivially use the same approach as <a href="#dss_sortedvectorset">sorted vectors
+for set-like containers</a>. The only difference is that your query function
+(which uses std::lower_bound to get efficient log(n) lookup) should only compare
+the key, not both the key and value. This yields the same advantages as sorted
+vectors for sets.
+</p>
+</div>
- <p><tt>Instruction</tt> instances that are already in <tt>BasicBlock</tt>s
- are implicitly associated with an existing instruction list: the instruction
- list of the enclosing basic block. Thus, we could have accomplished the same
- thing as the above code without being given a <tt>BasicBlock</tt> by doing:
- </p>
+<!-- _______________________________________________________________________ -->
+<div class="doc_subsubsection">
+ <a name="dss_stringmap">"llvm/ADT/StringMap.h"</a>
+</div>
-<div class="doc_code">
-<pre>
-Instruction *pi = ...;
-Instruction *newInst = new Instruction(...);
+<div class="doc_text">
-pi->getParent()->getInstList().insert(pi, newInst);
-</pre>
+<p>
+Strings are commonly used as keys in maps, and they are difficult to support
+efficiently: they are variable length, inefficient to hash and compare when
+long, expensive to copy, etc. StringMap is a specialized container designed to
+cope with these issues. It supports mapping an arbitrary range of bytes to an
+arbitrary other object.</p>
+
+<p>The StringMap implementation uses a quadratically-probed hash table, where
+the buckets store a pointer to the heap allocated entries (and some other
+stuff). The entries in the map must be heap allocated because the strings are
+variable length. The string data (key) and the element object (value) are
+stored in the same allocation with the string data immediately after the element
+object. This container guarantees the "<tt>(char*)(&Value+1)</tt>" points
+to the key string for a value.</p>
+
+<p>The StringMap is very fast for several reasons: quadratic probing is very
+cache efficient for lookups, the hash value of strings in buckets is not
+recomputed when lookup up an element, StringMap rarely has to touch the
+memory for unrelated objects when looking up a value (even when hash collisions
+happen), hash table growth does not recompute the hash values for strings
+already in the table, and each pair in the map is store in a single allocation
+(the string data is stored in the same allocation as the Value of a pair).</p>
+
+<p>StringMap also provides query methods that take byte ranges, so it only ever
+copies a string if a value is inserted into the table.</p>
</div>
- <p>In fact, this sequence of steps occurs so frequently that the
- <tt>Instruction</tt> class and <tt>Instruction</tt>-derived classes provide
- constructors which take (as a default parameter) a pointer to an
- <tt>Instruction</tt> which the newly-created <tt>Instruction</tt> should
- precede. That is, <tt>Instruction</tt> constructors are capable of
- inserting the newly-created instance into the <tt>BasicBlock</tt> of a
- provided instruction, immediately before that instruction. Using an
- <tt>Instruction</tt> constructor with a <tt>insertBefore</tt> (default)
- parameter, the above code becomes:</p>
-
-<div class="doc_code">
-<pre>
-Instruction* pi = ...;
-Instruction* newInst = new Instruction(..., pi);
-</pre>
+<!-- _______________________________________________________________________ -->
+<div class="doc_subsubsection">
+ <a name="dss_indexedmap">"llvm/ADT/IndexedMap.h"</a>
</div>
- <p>which is much cleaner, especially if you're creating a lot of
- instructions and adding them to <tt>BasicBlock</tt>s.</p></li>
-</ul>
+<div class="doc_text">
+<p>
+IndexedMap is a specialized container for mapping small dense integers (or
+values that can be mapped to small dense integers) to some other type. It is
+internally implemented as a vector with a mapping function that maps the keys to
+the dense integer range.
+</p>
+
+<p>
+This is useful for cases like virtual registers in the LLVM code generator: they
+have a dense mapping that is offset by a compile-time constant (the first
+virtual register ID).</p>
</div>
-<!--_______________________________________________________________________-->
+<!-- _______________________________________________________________________ -->
<div class="doc_subsubsection">
- <a name="schanges_deleting">Deleting <tt>Instruction</tt>s</a>
+ <a name="dss_densemap">"llvm/ADT/DenseMap.h"</a>
</div>
<div class="doc_text">
-<p>Deleting an instruction from an existing sequence of instructions that form a
-<a href="#BasicBlock"><tt>BasicBlock</tt></a> is very straight-forward. First,
-you must have a pointer to the instruction that you wish to delete. Second, you
-need to obtain the pointer to that instruction's basic block. You use the
-pointer to the basic block to get its list of instructions and then use the
-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->getParent();
+<p>
+DenseMap is a simple quadratically probed hash table. It excels at supporting
+small keys and values: it uses a single allocation to hold all of the pairs that
+are currently inserted in the map. DenseMap is a great way to map pointers to
+pointers, or map other small types to each other.
+</p>
-BB->getInstList().erase(I);
-</pre>
-</div>
+<p>
+There are several aspects of DenseMap that you should be aware of, however. The
+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
+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>
</div>
-<!--_______________________________________________________________________-->
+<!-- _______________________________________________________________________ -->
<div class="doc_subsubsection">
- <a name="schanges_replacing">Replacing an <tt>Instruction</tt> with another
- <tt>Value</tt></a>
+ <a name="dss_map"><map></a>
</div>
<div class="doc_text">
-<p><i>Replacing individual instructions</i></p>
+<p>
+std::map has similar characteristics to <a href="#dss_set">std::set</a>: it uses
+a single allocation per pair inserted into the map, it offers log(n) lookup with
+an extremely large constant factor, imposes a space penalty of 3 pointers per
+pair in the map, etc.</p>
-<p>Including "<a href="/doxygen/BasicBlockUtils_8h-source.html">llvm/Transforms/Utils/BasicBlockUtils.h</a>"
-permits use of two very useful replace functions: <tt>ReplaceInstWithValue</tt>
-and <tt>ReplaceInstWithInst</tt>.</p>
+<p>std::map is most useful when your keys or values are very large, if you need
+to iterate over the collection in sorted order, or if you need stable iterators
+into the map (i.e. they don't get invalidated if an insertion or deletion of
+another element takes place).</p>
-<h4><a name="schanges_deleting">Deleting <tt>Instruction</tt>s</a></h4>
+</div>
-<ul>
- <li><tt>ReplaceInstWithValue</tt>
+<!-- _______________________________________________________________________ -->
+<div class="doc_subsubsection">
+ <a name="dss_othermap">Other Map-Like Container Options</a>
+</div>
- <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
- <tt>AllocaInst</tt> that allocates memory for a single integer with a null
- pointer to an integer.</p>
+<div class="doc_text">
-<div class="doc_code">
-<pre>
-AllocaInst* instToReplace = ...;
-BasicBlock::iterator ii(instToReplace);
+<p>
+The STL provides several other options, such as std::multimap and the various
+"hash_map" like containers (whether from C++ TR1 or from the SGI library).</p>
-ReplaceInstWithValue(instToReplace->getParent()->getInstList(), ii,
- Constant::getNullValue(PointerType::get(Type::IntTy)));
-</pre></div></li>
+<p>std::multimap is useful if you want to map a key to multiple values, but has
+all the drawbacks of std::map. A sorted vector or some other approach is almost
+always better.</p>
- <li><tt>ReplaceInstWithInst</tt>
+<p>The various hash_map implementations (exposed portably by
+"llvm/ADT/hash_map") are simple chained hash tables. This algorithm is as
+malloc intensive as std::map (performing an allocation for each element
+inserted, thus having really high constant factors) but (usually) provides O(1)
+insertion/deletion of elements. This can be useful if your elements are large
+(thus making the constant-factor cost relatively low) or if comparisons are
+expensive. Element iteration does not visit elements in a useful order.</p>
- <p>This function replaces a particular instruction with another
- instruction. The following example illustrates the replacement of one
- <tt>AllocaInst</tt> with another.</p>
+</div>
-<div class="doc_code">
-<pre>
-AllocaInst* instToReplace = ...;
-BasicBlock::iterator ii(instToReplace);
-ReplaceInstWithInst(instToReplace->getParent()->getInstList(), ii,
- new AllocaInst(Type::IntTy, 0, "ptrToReplacedInt"));
-</pre></div></li>
-</ul>
+<!-- *********************************************************************** -->
+<div class="doc_section">
+ <a name="common">Helpful Hints for Common Operations</a>
+</div>
+<!-- *********************************************************************** -->
-<p><i>Replacing multiple uses of <tt>User</tt>s and <tt>Value</tt>s</i></p>
+<div class="doc_text">
-<p>You can use <tt>Value::replaceAllUsesWith</tt> and
-<tt>User::replaceUsesOfWith</tt> to change more than one use at a time. See the
-doxygen documentation for the <a href="/doxygen/classllvm_1_1Value.html">Value Class</a>
-and <a href="/doxygen/classllvm_1_1User.html">User Class</a>, respectively, for more
-information.</p>
-
-<!-- Value::replaceAllUsesWith User::replaceUsesOfWith Point out:
-include/llvm/Transforms/Utils/ especially BasicBlockUtils.h with:
-ReplaceInstWithValue, ReplaceInstWithInst -->
-
-</div>
-
-<!-- *********************************************************************** -->
-<div class="doc_section">
- <a name="advanced">Advanced Topics</a>
-</div>
-<!-- *********************************************************************** -->
+<p>This section describes how to perform some very simple transformations of
+LLVM code. This is meant to give examples of common idioms used, showing the
+practical side of LLVM transformations. <p> Because this is a "how-to" section,
+you should also read about the main classes that you will be working with. The
+<a href="#coreclasses">Core LLVM Class Hierarchy Reference</a> contains details
+and descriptions of the main classes that you should know about.</p>
-<div class="doc_text">
-<p>
-This section describes some of the advanced or obscure API's that most clients
-do not need to be aware of. These API's tend manage the inner workings of the
-LLVM system, and only need to be accessed in unusual circumstances.
-</p>
</div>
+<!-- NOTE: this section should be heavy on example code -->
<!-- ======================================================================= -->
<div class="doc_subsection">
- <a name="TypeResolve">LLVM Type Resolution</a>
+ <a name="inspection">Basic Inspection and Traversal Routines</a>
</div>
<div class="doc_text">
-<p>
-The LLVM type system has a very simple goal: allow clients to compare types for
-structural equality with a simple pointer comparison (aka a shallow compare).
-This goal makes clients much simpler and faster, and is used throughout the LLVM
-system.
-</p>
-
-<p>
-Unfortunately achieving this goal is not a simple matter. In particular,
-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,
-assembly parser, and linker also have to be aware of the inner workings of this
-system.
-</p>
+<p>The LLVM compiler infrastructure have many different data structures that may
+be traversed. Following the example of the C++ standard template library, the
+techniques used to traverse these various data structures are all basically the
+same. For a enumerable sequence of values, the <tt>XXXbegin()</tt> function (or
+method) returns an iterator to the start of the sequence, the <tt>XXXend()</tt>
+function returns an iterator pointing to one past the last valid element of the
+sequence, and there is some <tt>XXXiterator</tt> data type that is common
+between the two operations.</p>
-<p>
-For our purposes below, we need three concepts. First, an "Opaque Type" is
-exactly as defined in the <a href="LangRef.html#t_opaque">language
-reference</a>. Second an "Abstract Type" is any type which includes an
-opaque type as part of its type graph (for example "<tt>{ opaque, int }</tt>").
-Third, a concrete type is a type that is not an abstract type (e.g. "<tt>{ int,
-float }</tt>").
-</p>
+<p>Because the pattern for iteration is common across many different aspects of
+the program representation, the standard template library algorithms may be used
+on them, and it is easier to remember how to iterate. First we show a few common
+examples of the data structures that need to be traversed. Other data
+structures are traversed in very similar ways.</p>
</div>
-<!-- ______________________________________________________________________ -->
+<!-- _______________________________________________________________________ -->
<div class="doc_subsubsection">
- <a name="BuildRecType">Basic Recursive Type Construction</a>
+ <a name="iterate_function">Iterating over the </a><a
+ href="#BasicBlock"><tt>BasicBlock</tt></a>s in a <a
+ href="#Function"><tt>Function</tt></a>
</div>
<div class="doc_text">
-<p>
-Because the most common question is "how do I build a recursive type with LLVM",
-we answer it now and explain it as we go. Here we include enough to cause this
-to be emitted to an output .ll file:
-</p>
+<p>It's quite common to have a <tt>Function</tt> instance that you'd like to
+transform in some way; in particular, you'd like to manipulate its
+<tt>BasicBlock</tt>s. To facilitate this, you'll need to iterate over all of
+the <tt>BasicBlock</tt>s that constitute the <tt>Function</tt>. The following is
+an example that prints the name of a <tt>BasicBlock</tt> and the number of
+<tt>Instruction</tt>s it contains:</p>
<div class="doc_code">
<pre>
-%mylist = type { %mylist*, int }
+// <i>func is a pointer to a Function instance</i>
+for (Function::iterator i = func->begin(), e = func->end(); i != e; ++i)
+ // <i>Print out the name of the basic block if it has one, and then the</i>
+ // <i>number of instructions that it contains</i>
+ llvm::cerr << "Basic block (name=" << i->getName() << ") has "
+ << i->size() << " instructions.\n";
</pre>
</div>
-<p>
-To build this, use the following LLVM APIs:
-</p>
+<p>Note that i can be used as if it were a pointer for the purposes of
+invoking member functions of the <tt>Instruction</tt> class. This is
+because the indirection operator is overloaded for the iterator
+classes. In the above code, the expression <tt>i->size()</tt> is
+exactly equivalent to <tt>(*i).size()</tt> just like you'd expect.</p>
-<div class="doc_code">
-<pre>
-// <i>Create the initial outer struct</i>
-<a href="#PATypeHolder">PATypeHolder</a> StructTy = OpaqueType::get();
-std::vector<const Type*> Elts;
-Elts.push_back(PointerType::get(StructTy));
-Elts.push_back(Type::IntTy);
-StructType *NewSTy = StructType::get(Elts);
+</div>
-// <i>At this point, NewSTy = "{ opaque*, int }". Tell VMCore that</i>
-// <i>the struct and the opaque type are actually the same.</i>
-cast<OpaqueType>(StructTy.get())-><a href="#refineAbstractTypeTo">refineAbstractTypeTo</a>(NewSTy);
+<!-- _______________________________________________________________________ -->
+<div class="doc_subsubsection">
+ <a name="iterate_basicblock">Iterating over the </a><a
+ href="#Instruction"><tt>Instruction</tt></a>s in a <a
+ href="#BasicBlock"><tt>BasicBlock</tt></a>
+</div>
-// <i>NewSTy is potentially invalidated, but StructTy (a <a href="#PATypeHolder">PATypeHolder</a>) is</i>
-// <i>kept up-to-date</i>
-NewSTy = cast<StructType>(StructTy.get());
+<div class="doc_text">
-// <i>Add a name for the type to the module symbol table (optional)</i>
-MyModule->addTypeName("mylist", NewSTy);
+<p>Just like when dealing with <tt>BasicBlock</tt>s in <tt>Function</tt>s, it's
+easy to iterate over the individual instructions that make up
+<tt>BasicBlock</tt>s. Here's a code snippet that prints out each instruction in
+a <tt>BasicBlock</tt>:</p>
+
+<div class="doc_code">
+<pre>
+// <i>blk is a pointer to a BasicBlock instance</i>
+for (BasicBlock::iterator i = blk->begin(), e = blk->end(); i != e; ++i)
+ // <i>The next statement works since operator<<(ostream&,...)</i>
+ // <i>is overloaded for Instruction&</i>
+ llvm::cerr << *i << "\n";
</pre>
</div>
-<p>
-This code shows the basic approach used to build recursive types: build a
-non-recursive type using 'opaque', then use type unification to close the cycle.
-The type unification step is performed by the <tt><a
-ref="#refineAbstractTypeTo">refineAbstractTypeTo</a></tt> method, which is
-described next. After that, we describe the <a
-href="#PATypeHolder">PATypeHolder class</a>.
-</p>
+<p>However, this isn't really the best way to print out the contents of a
+<tt>BasicBlock</tt>! Since the ostream operators are overloaded for virtually
+anything you'll care about, you could have just invoked the print routine on the
+basic block itself: <tt>llvm::cerr << *blk << "\n";</tt>.</p>
</div>
-<!-- ______________________________________________________________________ -->
+<!-- _______________________________________________________________________ -->
<div class="doc_subsubsection">
- <a name="refineAbstractTypeTo">The <tt>refineAbstractTypeTo</tt> method</a>
+ <a name="iterate_institer">Iterating over the </a><a
+ href="#Instruction"><tt>Instruction</tt></a>s in a <a
+ href="#Function"><tt>Function</tt></a>
</div>
<div class="doc_text">
-<p>
-The <tt>refineAbstractTypeTo</tt> method starts the type unification process.
-While this method is actually a member of the DerivedType class, it is most
-often used on OpaqueType instances. Type unification is actually a recursive
-process. After unification, types can become structurally isomorphic to
-existing types, and all duplicates are deleted (to preserve pointer equality).
-</p>
-<p>
-In the example above, the OpaqueType object is definitely deleted.
-Additionally, if there is an "{ \2*, int}" type already created in the system,
-the pointer and struct type created are <b>also</b> deleted. Obviously whenever
-a type is deleted, any "Type*" pointers in the program are invalidated. As
-such, it is safest to avoid having <i>any</i> "Type*" pointers to abstract types
-live across a call to <tt>refineAbstractTypeTo</tt> (note that non-abstract
-types can never move or be deleted). To deal with this, the <a
-href="#PATypeHolder">PATypeHolder</a> class is used to maintain a stable
-reference to a possibly refined type, and the <a
-href="#AbstractTypeUser">AbstractTypeUser</a> class is used to update more
-complex datastructures.
-</p>
+<p>If you're finding that you commonly iterate over a <tt>Function</tt>'s
+<tt>BasicBlock</tt>s and then that <tt>BasicBlock</tt>'s <tt>Instruction</tt>s,
+<tt>InstIterator</tt> should be used instead. You'll need to include <a
+href="/doxygen/InstIterator_8h-source.html"><tt>llvm/Support/InstIterator.h</tt></a>,
+and then instantiate <tt>InstIterator</tt>s explicitly in your code. Here's a
+small example that shows how to dump all instructions in a function to the standard error stream:<p>
-</div>
+<div class="doc_code">
+<pre>
+#include "<a href="/doxygen/InstIterator_8h-source.html">llvm/Support/InstIterator.h</a>"
-<!-- ______________________________________________________________________ -->
-<div class="doc_subsubsection">
- <a name="PATypeHolder">The PATypeHolder Class</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 << *i << "\n";
+</pre>
</div>
-<div class="doc_text">
-<p>
-PATypeHolder is a form of a "smart pointer" for Type objects. When VMCore
-happily goes about nuking types that become isomorphic to existing types, it
-automatically updates all PATypeHolder objects to point to the new type. In the
-example above, this allows the code to maintain a pointer to the resultant
-resolved recursive type, even though the Type*'s are potentially invalidated.
-</p>
+<p>Easy, isn't it? You can also use <tt>InstIterator</tt>s to fill a
+work list with its initial contents. For example, if you wanted to
+initialize a work list to contain all instructions in a <tt>Function</tt>
+F, all you would need to do is something like:</p>
-<p>
-PATypeHolder is an extremely light-weight object that uses a lazy union-find
-implementation to update pointers. For example the pointer from a Value to its
-Type is maintained by PATypeHolder objects.
-</p>
+<div class="doc_code">
+<pre>
+std::set<Instruction*> worklist;
+worklist.insert(inst_begin(F), inst_end(F));
+</pre>
+</div>
+
+<p>The STL set <tt>worklist</tt> would now contain all instructions in the
+<tt>Function</tt> pointed to by F.</p>
</div>
-<!-- ______________________________________________________________________ -->
+<!-- _______________________________________________________________________ -->
<div class="doc_subsubsection">
- <a name="AbstractTypeUser">The AbstractTypeUser Class</a>
+ <a name="iterate_convert">Turning an iterator into a class pointer (and
+ vice-versa)</a>
</div>
<div class="doc_text">
-<p>
-Some data structures need more to perform more complex updates when types get
-resolved. The <a href="#SymbolTable">SymbolTable</a> class, for example, needs
-move and potentially merge type planes in its representation when a pointer
-changes.</p>
+<p>Sometimes, it'll be useful to grab a reference (or pointer) to a class
+instance when all you've got at hand is an iterator. Well, extracting
+a reference or a pointer from an iterator is very straight-forward.
+Assuming that <tt>i</tt> is a <tt>BasicBlock::iterator</tt> and <tt>j</tt>
+is a <tt>BasicBlock::const_iterator</tt>:</p>
-<p>
-To support this, a class can derive from the AbstractTypeUser class. This class
-allows it to get callbacks when certain types are resolved. To register to get
-callbacks for a particular type, the DerivedType::{add/remove}AbstractTypeUser
-methods can be called on a type. Note that these methods only work for <i>
-abstract</i> types. Concrete types (those that do not include an opaque objects
-somewhere) can never be refined.
-</p>
+<div class="doc_code">
+<pre>
+Instruction& inst = *i; // <i>Grab reference to instruction reference</i>
+Instruction* pinst = &*i; // <i>Grab pointer to instruction reference</i>
+const Instruction& inst = *j;
+</pre>
</div>
+<p>However, the iterators you'll be working with in the LLVM framework are
+special: they will automatically convert to a ptr-to-instance type whenever they
+need to. Instead of dereferencing the iterator and then taking the address of
+the result, you can simply assign the iterator to the proper pointer type and
+you get the dereference and address-of operation as a result of the assignment
+(behind the scenes, this is a result of overloading casting mechanisms). Thus
+the last line of the last example,</p>
-<!-- ======================================================================= -->
-<div class="doc_subsection">
- <a name="SymbolTable">The <tt>SymbolTable</tt> class</a>
+<div class="doc_code">
+<pre>
+Instruction* pinst = &*i;
+</pre>
</div>
-<div class="doc_text">
-<p>This class provides a symbol table that the <a
-href="#Function"><tt>Function</tt></a> and <a href="#Module">
-<tt>Module</tt></a> classes use for naming definitions. The symbol table can
-provide a name for any <a href="#Value"><tt>Value</tt></a>.
-<tt>SymbolTable</tt> is an abstract data type. It hides the data it contains
-and provides access to it through a controlled interface.</p>
-
-<p>Note that the <tt>SymbolTable</tt> class should not be directly accessed
-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
-an empty name) do not exist in the symbol table.
-</p>
-
-<p>To use the <tt>SymbolTable</tt> well, you need to understand the
-structure of the information it holds. The class contains two
-<tt>std::map</tt> objects. The first, <tt>pmap</tt>, is a map of
-<tt>Type*</tt> to maps of name (<tt>std::string</tt>) to <tt>Value*</tt>.
-Thus, Values are stored in two-dimensions and accessed by <tt>Type</tt> and
-name.</p>
+<p>is semantically equivalent to</p>
-<p>The interface of this class provides three basic types of operations:
-<ol>
- <li><em>Accessors</em>. Accessors provide read-only access to information
- such as finding a value for a name with the
- <a href="#SymbolTable_lookup">lookup</a> method.</li>
- <li><em>Mutators</em>. Mutators allow the user to add information to the
- <tt>SymbolTable</tt> with methods like
- <a href="#SymbolTable_insert"><tt>insert</tt></a>.</li>
- <li><em>Iterators</em>. Iterators allow the user to traverse the content
- of the symbol table in well defined ways, such as the method
- <a href="#SymbolTable_plane_begin"><tt>plane_begin</tt></a>.</li>
-</ol>
+<div class="doc_code">
+<pre>
+Instruction* pinst = i;
+</pre>
+</div>
+
+<p>It's also possible to turn a class pointer into the corresponding iterator,
+and this is a constant time operation (very efficient). The following code
+snippet illustrates use of the conversion constructors provided by LLVM
+iterators. By using these, you can explicitly grab the iterator of something
+without actually obtaining it via iteration over some structure:</p>
+
+<div class="doc_code">
+<pre>
+void printNextInstruction(Instruction* inst) {
+ BasicBlock::iterator it(inst);
+ ++it; // <i>After this line, it refers to the instruction after *inst</i>
+ if (it != inst->getParent()->end()) llvm::cerr << *it << "\n";
+}
+</pre>
+</div>
+
+</div>
+
+<!--_______________________________________________________________________-->
+<div class="doc_subsubsection">
+ <a name="iterate_complex">Finding call sites: a slightly more complex
+ example</a>
+</div>
+
+<div class="doc_text">
+
+<p>Say that you're writing a FunctionPass and would like to count all the
+locations in the entire module (that is, across every <tt>Function</tt>) where a
+certain function (i.e., some <tt>Function</tt>*) is already in scope. As you'll
+learn later, you may want to use an <tt>InstVisitor</tt> to accomplish this in a
+much more straight-forward manner, but this example will allow us to explore how
+you'd do it if you didn't have <tt>InstVisitor</tt> around. In pseudo-code, this
+is what we want to do:</p>
+
+<div class="doc_code">
+<pre>
+initialize callCounter to zero
+for each Function f in the Module
+ for each BasicBlock b in f
+ for each Instruction i in b
+ if (i is a CallInst and calls the given function)
+ increment callCounter
+</pre>
+</div>
+
+<p>And the actual code is (remember, because we're writing a
+<tt>FunctionPass</tt>, our <tt>FunctionPass</tt>-derived class simply has to
+override the <tt>runOnFunction</tt> method):</p>
+
+<div class="doc_code">
+<pre>
+Function* targetFunc = ...;
+
+class OurFunctionPass : public FunctionPass {
+ public:
+ OurFunctionPass(): callCounter(0) { }
+
+ virtual runOnFunction(Function& F) {
+ for (Function::iterator b = F.begin(), be = F.end(); b != be; ++b) {
+ for (BasicBlock::iterator i = b->begin(); ie = b->end(); i != ie; ++i) {
+ if (<a href="#CallInst">CallInst</a>* callInst = <a href="#isa">dyn_cast</a><<a
+ href="#CallInst">CallInst</a>>(&*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>
+
+ if (callInst->getCalledFunction() == targetFunc)
+ ++callCounter;
+ }
+ }
+ }
+ }
+
+ private:
+ unsigned callCounter;
+};
+</pre>
+</div>
+
+</div>
+
+<!--_______________________________________________________________________-->
+<div class="doc_subsubsection">
+ <a name="calls_and_invokes">Treating calls and invokes the same way</a>
+</div>
+
+<div class="doc_text">
+
+<p>You may have noticed that the previous example was a bit oversimplified in
+that it did not deal with call sites generated by 'invoke' instructions. In
+this, and in other situations, you may find that you want to treat
+<tt>CallInst</tt>s and <tt>InvokeInst</tt>s the same way, even though their
+most-specific common base class is <tt>Instruction</tt>, which includes lots of
+less closely-related things. For these cases, LLVM provides a handy wrapper
+class called <a
+href="http://llvm.org/doxygen/classllvm_1_1CallSite.html"><tt>CallSite</tt></a>.
+It is essentially a wrapper around an <tt>Instruction</tt> pointer, with some
+methods that provide functionality common to <tt>CallInst</tt>s and
+<tt>InvokeInst</tt>s.</p>
+
+<p>This class has "value semantics": it should be passed by value, not by
+reference and it should not be dynamically allocated or deallocated using
+<tt>operator new</tt> or <tt>operator delete</tt>. It is efficiently copyable,
+assignable and constructable, with costs equivalents to that of a bare pointer.
+If you look at its definition, it has only a single pointer member.</p>
+
+</div>
+
+<!--_______________________________________________________________________-->
+<div class="doc_subsubsection">
+ <a name="iterate_chains">Iterating over def-use & use-def chains</a>
+</div>
+
+<div class="doc_text">
+
+<p>Frequently, we might have an instance of the <a
+href="/doxygen/classllvm_1_1Value.html">Value Class</a> and we want to
+determine which <tt>User</tt>s use the <tt>Value</tt>. The list of all
+<tt>User</tt>s of a particular <tt>Value</tt> is called a <i>def-use</i> chain.
+For example, let's say we have a <tt>Function*</tt> named <tt>F</tt> to a
+particular function <tt>foo</tt>. Finding all of the instructions that
+<i>use</i> <tt>foo</tt> is as simple as iterating over the <i>def-use</i> chain
+of <tt>F</tt>:</p>
+
+<div class="doc_code">
+<pre>
+Function* F = ...;
+
+for (Value::use_iterator i = F->use_begin(), e = F->use_end(); i != e; ++i)
+ if (Instruction *Inst = dyn_cast<Instruction>(*i)) {
+ llvm::cerr << "F is used in instruction:\n";
+ llvm::cerr << *Inst << "\n";
+ }
+</pre>
+</div>
+
+<p>Alternately, it's common to have an instance of the <a
+href="/doxygen/classllvm_1_1User.html">User Class</a> and need to know what
+<tt>Value</tt>s are used by it. The list of all <tt>Value</tt>s used by a
+<tt>User</tt> is known as a <i>use-def</i> chain. Instances of class
+<tt>Instruction</tt> are common <tt>User</tt>s, so we might want to iterate over
+all of the values that a particular instruction uses (that is, the operands of
+the particular <tt>Instruction</tt>):</p>
+
+<div class="doc_code">
+<pre>
+Instruction* pi = ...;
+
+for (User::op_iterator i = pi->op_begin(), e = pi->op_end(); i != e; ++i) {
+ Value* v = *i;
+ // <i>...</i>
+}
+</pre>
+</div>
+
+<!--
+ def-use chains ("finding all users of"): Value::use_begin/use_end
+ use-def chains ("finding all values used"): User::op_begin/op_end [op=operand]
+-->
+
+</div>
+
+<!-- ======================================================================= -->
+<div class="doc_subsection">
+ <a name="simplechanges">Making simple changes</a>
+</div>
+
+<div class="doc_text">
+
+<p>There are some primitive transformation operations present in the LLVM
+infrastructure that are worth knowing about. When performing
+transformations, it's fairly common to manipulate the contents of basic
+blocks. This section describes some of the common methods for doing so
+and gives example code.</p>
+
+</div>
+
+<!--_______________________________________________________________________-->
+<div class="doc_subsubsection">
+ <a name="schanges_creating">Creating and inserting new
+ <tt>Instruction</tt>s</a>
+</div>
+
+<div class="doc_text">
+
+<p><i>Instantiating Instructions</i></p>
+
+<p>Creation of <tt>Instruction</tt>s is straight-forward: simply call the
+constructor for the kind of instruction to instantiate and provide the necessary
+parameters. For example, an <tt>AllocaInst</tt> only <i>requires</i> a
+(const-ptr-to) <tt>Type</tt>. Thus:</p>
+
+<div class="doc_code">
+<pre>
+AllocaInst* ai = new AllocaInst(Type::IntTy);
+</pre>
+</div>
+
+<p>will create an <tt>AllocaInst</tt> instance that represents the allocation of
+one integer in the current stack frame, at run time. Each <tt>Instruction</tt>
+subclass is likely to have varying default parameters which change the semantics
+of the instruction, so refer to the <a
+href="/doxygen/classllvm_1_1Instruction.html">doxygen documentation for the subclass of
+Instruction</a> that you're interested in instantiating.</p>
+
+<p><i>Naming values</i></p>
+
+<p>It is very useful to name the values of instructions when you're able to, as
+this facilitates the debugging of your transformations. If you end up looking
+at generated LLVM machine code, you definitely want to have logical names
+associated with the results of instructions! By supplying a value for the
+<tt>Name</tt> (default) parameter of the <tt>Instruction</tt> constructor, you
+associate a logical name with the result of the instruction's execution at
+run time. For example, say that I'm writing a transformation that dynamically
+allocates space for an integer on the stack, and that integer is going to be
+used as some kind of index by some other code. To accomplish this, I place an
+<tt>AllocaInst</tt> at the first point in the first <tt>BasicBlock</tt> of some
+<tt>Function</tt>, and I'm intending to use it within the same
+<tt>Function</tt>. I might do:</p>
+
+<div class="doc_code">
+<pre>
+AllocaInst* pa = new AllocaInst(Type::IntTy, 0, "indexLoc");
+</pre>
+</div>
+
+<p>where <tt>indexLoc</tt> is now the logical name of the instruction's
+execution value, which is a pointer to an integer on the run time stack.</p>
+
+<p><i>Inserting instructions</i></p>
+
+<p>There are essentially two ways to insert an <tt>Instruction</tt>
+into an existing sequence of instructions that form a <tt>BasicBlock</tt>:</p>
+
+<ul>
+ <li>Insertion into an explicit instruction list
+
+ <p>Given a <tt>BasicBlock* pb</tt>, an <tt>Instruction* pi</tt> within that
+ <tt>BasicBlock</tt>, and a newly-created instruction we wish to insert
+ before <tt>*pi</tt>, we do the following: </p>
+
+<div class="doc_code">
+<pre>
+BasicBlock *pb = ...;
+Instruction *pi = ...;
+Instruction *newInst = new Instruction(...);
+
+pb->getInstList().insert(pi, newInst); // <i>Inserts newInst before pi in pb</i>
+</pre>
+</div>
+
+ <p>Appending to the end of a <tt>BasicBlock</tt> is so common that
+ the <tt>Instruction</tt> class and <tt>Instruction</tt>-derived
+ classes provide constructors which take a pointer to a
+ <tt>BasicBlock</tt> to be appended to. For example code that
+ looked like: </p>
+
+<div class="doc_code">
+<pre>
+BasicBlock *pb = ...;
+Instruction *newInst = new Instruction(...);
+
+pb->getInstList().push_back(newInst); // <i>Appends newInst to pb</i>
+</pre>
+</div>
+
+ <p>becomes: </p>
+
+<div class="doc_code">
+<pre>
+BasicBlock *pb = ...;
+Instruction *newInst = new Instruction(..., pb);
+</pre>
+</div>
+
+ <p>which is much cleaner, especially if you are creating
+ long instruction streams.</p></li>
+
+ <li>Insertion into an implicit instruction list
+
+ <p><tt>Instruction</tt> instances that are already in <tt>BasicBlock</tt>s
+ are implicitly associated with an existing instruction list: the instruction
+ list of the enclosing basic block. Thus, we could have accomplished the same
+ thing as the above code without being given a <tt>BasicBlock</tt> by doing:
+ </p>
+
+<div class="doc_code">
+<pre>
+Instruction *pi = ...;
+Instruction *newInst = new Instruction(...);
+
+pi->getParent()->getInstList().insert(pi, newInst);
+</pre>
+</div>
+
+ <p>In fact, this sequence of steps occurs so frequently that the
+ <tt>Instruction</tt> class and <tt>Instruction</tt>-derived classes provide
+ constructors which take (as a default parameter) a pointer to an
+ <tt>Instruction</tt> which the newly-created <tt>Instruction</tt> should
+ precede. That is, <tt>Instruction</tt> constructors are capable of
+ inserting the newly-created instance into the <tt>BasicBlock</tt> of a
+ provided instruction, immediately before that instruction. Using an
+ <tt>Instruction</tt> constructor with a <tt>insertBefore</tt> (default)
+ parameter, the above code becomes:</p>
+
+<div class="doc_code">
+<pre>
+Instruction* pi = ...;
+Instruction* newInst = new Instruction(..., pi);
+</pre>
+</div>
+
+ <p>which is much cleaner, especially if you're creating a lot of
+ instructions and adding them to <tt>BasicBlock</tt>s.</p></li>
+</ul>
+
+</div>
+
+<!--_______________________________________________________________________-->
+<div class="doc_subsubsection">
+ <a name="schanges_deleting">Deleting <tt>Instruction</tt>s</a>
+</div>
+
+<div class="doc_text">
+
+<p>Deleting an instruction from an existing sequence of instructions that form a
+<a href="#BasicBlock"><tt>BasicBlock</tt></a> is very straight-forward. First,
+you must have a pointer to the instruction that you wish to delete. Second, you
+need to obtain the pointer to that instruction's basic block. You use the
+pointer to the basic block to get its list of instructions and then use the
+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->getParent();
+
+BB->getInstList().erase(I);
+</pre>
+</div>
+
+</div>
+
+<!--_______________________________________________________________________-->
+<div class="doc_subsubsection">
+ <a name="schanges_replacing">Replacing an <tt>Instruction</tt> with another
+ <tt>Value</tt></a>
+</div>
+
+<div class="doc_text">
+
+<p><i>Replacing individual instructions</i></p>
+
+<p>Including "<a href="/doxygen/BasicBlockUtils_8h-source.html">llvm/Transforms/Utils/BasicBlockUtils.h</a>"
+permits use of two very useful replace functions: <tt>ReplaceInstWithValue</tt>
+and <tt>ReplaceInstWithInst</tt>.</p>
+
+<h4><a name="schanges_deleting">Deleting <tt>Instruction</tt>s</a></h4>
+
+<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
+ <tt>AllocaInst</tt> that allocates memory for a single integer with a null
+ pointer to an integer.</p>
+
+<div class="doc_code">
+<pre>
+AllocaInst* instToReplace = ...;
+BasicBlock::iterator ii(instToReplace);
+
+ReplaceInstWithValue(instToReplace->getParent()->getInstList(), ii,
+ Constant::getNullValue(PointerType::get(Type::IntTy)));
+</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>
+
+<div class="doc_code">
+<pre>
+AllocaInst* instToReplace = ...;
+BasicBlock::iterator ii(instToReplace);
+
+ReplaceInstWithInst(instToReplace->getParent()->getInstList(), ii,
+ new AllocaInst(Type::IntTy, 0, "ptrToReplacedInt"));
+</pre></div></li>
+</ul>
+
+<p><i>Replacing multiple uses of <tt>User</tt>s and <tt>Value</tt>s</i></p>
+
+<p>You can use <tt>Value::replaceAllUsesWith</tt> and
+<tt>User::replaceUsesOfWith</tt> to change more than one use at a time. See the
+doxygen documentation for the <a href="/doxygen/classllvm_1_1Value.html">Value Class</a>
+and <a href="/doxygen/classllvm_1_1User.html">User Class</a>, respectively, for more
+information.</p>
+
+<!-- Value::replaceAllUsesWith User::replaceUsesOfWith Point out:
+include/llvm/Transforms/Utils/ especially BasicBlockUtils.h with:
+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->eraseFromParent();
+</pre>
+</div>
+
+</div>
+
+<!-- *********************************************************************** -->
+<div class="doc_section">
+ <a name="advanced">Advanced Topics</a>
+</div>
+<!-- *********************************************************************** -->
+
+<div class="doc_text">
+<p>
+This section describes some of the advanced or obscure API's that most clients
+do not need to be aware of. These API's tend manage the inner workings of the
+LLVM system, and only need to be accessed in unusual circumstances.
+</p>
+</div>
+
+<!-- ======================================================================= -->
+<div class="doc_subsection">
+ <a name="TypeResolve">LLVM Type Resolution</a>
+</div>
+
+<div class="doc_text">
+
+<p>
+The LLVM type system has a very simple goal: allow clients to compare types for
+structural equality with a simple pointer comparison (aka a shallow compare).
+This goal makes clients much simpler and faster, and is used throughout the LLVM
+system.
+</p>
+
+<p>
+Unfortunately achieving this goal is not a simple matter. In particular,
+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 bitcode reader,
+assembly parser, and linker also have to be aware of the inner workings of this
+system.
+</p>
+
+<p>
+For our purposes below, we need three concepts. First, an "Opaque Type" is
+exactly as defined in the <a href="LangRef.html#t_opaque">language
+reference</a>. Second an "Abstract Type" is any type which includes an
+opaque type as part of its type graph (for example "<tt>{ opaque, i32 }</tt>").
+Third, a concrete type is a type that is not an abstract type (e.g. "<tt>{ i32,
+float }</tt>").
+</p>
+
+</div>
+
+<!-- ______________________________________________________________________ -->
+<div class="doc_subsubsection">
+ <a name="BuildRecType">Basic Recursive Type Construction</a>
+</div>
+
+<div class="doc_text">
+
+<p>
+Because the most common question is "how do I build a recursive type with LLVM",
+we answer it now and explain it as we go. Here we include enough to cause this
+to be emitted to an output .ll file:
+</p>
+
+<div class="doc_code">
+<pre>
+%mylist = type { %mylist*, i32 }
+</pre>
+</div>
+
+<p>
+To build this, use the following LLVM APIs:
+</p>
+
+<div class="doc_code">
+<pre>
+// <i>Create the initial outer struct</i>
+<a href="#PATypeHolder">PATypeHolder</a> StructTy = OpaqueType::get();
+std::vector<const Type*> Elts;
+Elts.push_back(PointerType::get(StructTy));
+Elts.push_back(Type::IntTy);
+StructType *NewSTy = StructType::get(Elts);
+
+// <i>At this point, NewSTy = "{ opaque*, i32 }". Tell VMCore that</i>
+// <i>the struct and the opaque type are actually the same.</i>
+cast<OpaqueType>(StructTy.get())-><a href="#refineAbstractTypeTo">refineAbstractTypeTo</a>(NewSTy);
+
+// <i>NewSTy is potentially invalidated, but StructTy (a <a href="#PATypeHolder">PATypeHolder</a>) is</i>
+// <i>kept up-to-date</i>
+NewSTy = cast<StructType>(StructTy.get());
+
+// <i>Add a name for the type to the module symbol table (optional)</i>
+MyModule->addTypeName("mylist", NewSTy);
+</pre>
+</div>
+
+<p>
+This code shows the basic approach used to build recursive types: build a
+non-recursive type using 'opaque', then use type unification to close the cycle.
+The type unification step is performed by the <tt><a
+href="#refineAbstractTypeTo">refineAbstractTypeTo</a></tt> method, which is
+described next. After that, we describe the <a
+href="#PATypeHolder">PATypeHolder class</a>.
+</p>
+
+</div>
+
+<!-- ______________________________________________________________________ -->
+<div class="doc_subsubsection">
+ <a name="refineAbstractTypeTo">The <tt>refineAbstractTypeTo</tt> method</a>
+</div>
+
+<div class="doc_text">
+<p>
+The <tt>refineAbstractTypeTo</tt> method starts the type unification process.
+While this method is actually a member of the DerivedType class, it is most
+often used on OpaqueType instances. Type unification is actually a recursive
+process. After unification, types can become structurally isomorphic to
+existing types, and all duplicates are deleted (to preserve pointer equality).
+</p>
+
+<p>
+In the example above, the OpaqueType object is definitely deleted.
+Additionally, if there is an "{ \2*, i32}" type already created in the system,
+the pointer and struct type created are <b>also</b> deleted. Obviously whenever
+a type is deleted, any "Type*" pointers in the program are invalidated. As
+such, it is safest to avoid having <i>any</i> "Type*" pointers to abstract types
+live across a call to <tt>refineAbstractTypeTo</tt> (note that non-abstract
+types can never move or be deleted). To deal with this, the <a
+href="#PATypeHolder">PATypeHolder</a> class is used to maintain a stable
+reference to a possibly refined type, and the <a
+href="#AbstractTypeUser">AbstractTypeUser</a> class is used to update more
+complex datastructures.
+</p>
+
+</div>
+
+<!-- ______________________________________________________________________ -->
+<div class="doc_subsubsection">
+ <a name="PATypeHolder">The PATypeHolder Class</a>
+</div>
+
+<div class="doc_text">
+<p>
+PATypeHolder is a form of a "smart pointer" for Type objects. When VMCore
+happily goes about nuking types that become isomorphic to existing types, it
+automatically updates all PATypeHolder objects to point to the new type. In the
+example above, this allows the code to maintain a pointer to the resultant
+resolved recursive type, even though the Type*'s are potentially invalidated.
+</p>
+
+<p>
+PATypeHolder is an extremely light-weight object that uses a lazy union-find
+implementation to update pointers. For example the pointer from a Value to its
+Type is maintained by PATypeHolder objects.
+</p>
+
+</div>
+
+<!-- ______________________________________________________________________ -->
+<div class="doc_subsubsection">
+ <a name="AbstractTypeUser">The AbstractTypeUser Class</a>
+</div>
+
+<div class="doc_text">
+
+<p>
+Some data structures need more to perform more complex updates when types get
+resolved. To support this, a class can derive from the AbstractTypeUser class.
+This class
+allows it to get callbacks when certain types are resolved. To register to get
+callbacks for a particular type, the DerivedType::{add/remove}AbstractTypeUser
+methods can be called on a type. Note that these methods only work for <i>
+ abstract</i> types. Concrete types (those that do not include any opaque
+objects) can never be refined.
+</p>
+</div>
+
+
+<!-- ======================================================================= -->
+<div class="doc_subsection">
+ <a name="SymbolTable">The <tt>ValueSymbolTable</tt> and
+ <tt>TypeSymbolTable</tt> classes</a>
+</div>
+
+<div class="doc_text">
+<p>The <tt><a href="http://llvm.org/doxygen/classllvm_1_1ValueSymbolTable.html">
+ValueSymbolTable</a></tt> class provides a symbol table that the <a
+href="#Function"><tt>Function</tt></a> and <a href="#Module">
+<tt>Module</tt></a> classes use for naming value definitions. The symbol table
+can provide a name for any <a href="#Value"><tt>Value</tt></a>.
+The <tt><a href="http://llvm.org/doxygen/classllvm_1_1TypeSymbolTable.html">
+TypeSymbolTable</a></tt> class is used by the <tt>Module</tt> class to store
+names for types.</p>
+
+<p>Note that the <tt>SymbolTable</tt> class should not be directly accessed
+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
+an empty name) do not exist in the symbol table.
+</p>
+
+<p>These symbol tables support iteration over the values/types in the symbol
+table with <tt>begin/end/iterator</tt> and supports querying to see if a
+specific name is in the symbol table (with <tt>lookup</tt>). The
+<tt>ValueSymbolTable</tt> class exposes no public mutator methods, instead,
+simply call <tt>setName</tt> on a value, which will autoinsert it into the
+appropriate symbol table. For types, use the Module::addTypeName method to
+insert entries into the symbol table.</p>
+
+</div>
+
+
+
+<!-- *********************************************************************** -->
+<div class="doc_section">
+ <a name="coreclasses">The Core LLVM Class Hierarchy Reference </a>
+</div>
+<!-- *********************************************************************** -->
+
+<div class="doc_text">
+<p><tt>#include "<a href="/doxygen/Type_8h-source.html">llvm/Type.h</a>"</tt>
+<br>doxygen info: <a href="/doxygen/classllvm_1_1Type.html">Type Class</a></p>
-<h3>Accessors</h3>
-<dl>
- <dt><tt>Value* lookup(const Type* Ty, const std::string& name) const</tt>:
- </dt>
- <dd>The <tt>lookup</tt> method searches the type plane given by the
- <tt>Ty</tt> parameter for a <tt>Value</tt> with the provided <tt>name</tt>.
- If a suitable <tt>Value</tt> is not found, null is returned.</dd>
-
- <dt><tt>bool isEmpty() const</tt>:</dt>
- <dd>This function returns true if both the value and types maps are
- empty</dd>
-</dl>
+<p>The Core LLVM classes are the primary means of representing the program
+being inspected or transformed. The core LLVM classes are defined in
+header files in the <tt>include/llvm/</tt> directory, and implemented in
+the <tt>lib/VMCore</tt> directory.</p>
-<h3>Mutators</h3>
-<dl>
- <dt><tt>void insert(Value *Val)</tt>:</dt>
- <dd>This method adds the provided value to the symbol table. The Value must
- have both a name and a type which are extracted and used to place the value
- in the correct type plane under the value's name.</dd>
-
- <dt><tt>void insert(const std::string& Name, Value *Val)</tt>:</dt>
- <dd> Inserts a constant or type into the symbol table with the specified
- name. There can be a many to one mapping between names and constants
- or types.</dd>
-
- <dt><tt>void remove(Value* Val)</tt>:</dt>
- <dd> This method removes a named value from the symbol table. The
- type and name of the Value are extracted from \p N and used to
- lookup the Value in the correct type plane. If the Value is
- not in the symbol table, this method silently ignores the
- request.</dd>
-
- <dt><tt>Value* remove(const std::string& Name, Value *Val)</tt>:</dt>
- <dd> Remove a constant or type with the specified name from the
- symbol table.</dd>
-
- <dt><tt>Value *remove(const value_iterator& It)</tt>:</dt>
- <dd> Removes a specific value from the symbol table.
- Returns the removed value.</dd>
-
- <dt><tt>bool strip()</tt>:</dt>
- <dd> This method will strip the symbol table of its names leaving
- the type and values. </dd>
-
- <dt><tt>void clear()</tt>:</dt>
- <dd>Empty the symbol table completely.</dd>
-</dl>
+</div>
-<h3>Iteration</h3>
-<p>The following functions describe three types of iterators you can obtain
-the beginning or end of the sequence for both const and non-const. It is
-important to keep track of the different kinds of iterators. There are
-three idioms worth pointing out:</p>
-
-<table>
- <tr><th>Units</th><th>Iterator</th><th>Idiom</th></tr>
- <tr>
- <td align="left">Planes Of name/Value maps</td><td>PI</td>
- <td align="left"><pre><tt>
-for (SymbolTable::plane_const_iterator PI = ST.plane_begin(),
- PE = ST.plane_end(); PI != PE; ++PI ) {
- PI->first // <i>This is the Type* of the plane</i>
- PI->second // <i>This is the SymbolTable::ValueMap of name/Value pairs</i>
-}
- </tt></pre></td>
- </tr>
- <tr>
- <td align="left">name/Value pairs in a plane</td><td>VI</td>
- <td align="left"><pre><tt>
-for (SymbolTable::value_const_iterator VI = ST.value_begin(SomeType),
- VE = ST.value_end(SomeType); VI != VE; ++VI ) {
- VI->first // <i>This is the name of the Value</i>
- VI->second // <i>This is the Value* value associated with the name</i>
-}
- </tt></pre></td>
- </tr>
-</table>
+<!-- ======================================================================= -->
+<div class="doc_subsection">
+ <a name="Type">The <tt>Type</tt> class and Derived Types</a>
+</div>
-<p>Using the recommended iterator names and idioms will help you avoid
-making mistakes. Of particular note, make sure that whenever you use
-value_begin(SomeType) that you always compare the resulting iterator
-with value_end(SomeType) not value_end(SomeOtherType) or else you
-will loop infinitely.</p>
+<div class="doc_text">
-<dl>
+ <p><tt>Type</tt> is a superclass of all type classes. Every <tt>Value</tt> has
+ a <tt>Type</tt>. <tt>Type</tt> cannot be instantiated directly but only
+ through its subclasses. Certain primitive types (<tt>VoidType</tt>,
+ <tt>LabelType</tt>, <tt>FloatType</tt> and <tt>DoubleType</tt>) have hidden
+ subclasses. They are hidden because they offer no useful functionality beyond
+ what the <tt>Type</tt> class offers except to distinguish themselves from
+ other subclasses of <tt>Type</tt>.</p>
+ <p>All other types are subclasses of <tt>DerivedType</tt>. Types can be
+ named, but this is not a requirement. There exists exactly
+ one instance of a given shape at any one time. This allows type equality to
+ be performed with address equality of the Type Instance. That is, given two
+ <tt>Type*</tt> values, the types are identical if the pointers are identical.
+ </p>
+</div>
- <dt><tt>plane_iterator plane_begin()</tt>:</dt>
- <dd>Get an iterator that starts at the beginning of the type planes.
- The iterator will iterate over the Type/ValueMap pairs in the
- type planes. </dd>
+<!-- _______________________________________________________________________ -->
+<div class="doc_subsubsection">
+ <a name="m_Value">Important Public Methods</a>
+</div>
- <dt><tt>plane_const_iterator plane_begin() const</tt>:</dt>
- <dd>Get a const_iterator that starts at the beginning of the type
- planes. The iterator will iterate over the Type/ValueMap pairs
- in the type planes. </dd>
+<div class="doc_text">
- <dt><tt>plane_iterator plane_end()</tt>:</dt>
- <dd>Get an iterator at the end of the type planes. This serves as
- the marker for end of iteration over the type planes.</dd>
+<ul>
+ <li><tt>bool isInteger() const</tt>: Returns true for any integer type.</li>
- <dt><tt>plane_const_iterator plane_end() const</tt>:</dt>
- <dd>Get a const_iterator at the end of the type planes. This serves as
- the marker for end of iteration over the type planes.</dd>
+ <li><tt>bool isFloatingPoint()</tt>: Return true if this is one of the two
+ floating point types.</li>
- <dt><tt>value_iterator value_begin(const Type *Typ)</tt>:</dt>
- <dd>Get an iterator that starts at the beginning of a type plane.
- The iterator will iterate over the name/value pairs in the type plane.
- Note: The type plane must already exist before using this.</dd>
+ <li><tt>bool isAbstract()</tt>: Return true if the type is abstract (contains
+ an OpaqueType anywhere in its definition).</li>
- <dt><tt>value_const_iterator value_begin(const Type *Typ) const</tt>:</dt>
- <dd>Get a const_iterator that starts at the beginning of a type plane.
- The iterator will iterate over the name/value pairs in the type plane.
- Note: The type plane must already exist before using this.</dd>
+ <li><tt>bool isSized()</tt>: Return true if the type has known size. Things
+ that don't have a size are abstract types, labels and void.</li>
- <dt><tt>value_iterator value_end(const Type *Typ)</tt>:</dt>
- <dd>Get an iterator to the end of a type plane. This serves as the marker
- for end of iteration of the type plane.
- Note: The type plane must already exist before using this.</dd>
+</ul>
+</div>
- <dt><tt>value_const_iterator value_end(const Type *Typ) const</tt>:</dt>
- <dd>Get a const_iterator to the end of a type plane. This serves as the
- marker for end of iteration of the type plane.
- Note: the type plane must already exist before using this.</dd>
+<!-- _______________________________________________________________________ -->
+<div class="doc_subsubsection">
+ <a name="m_Value">Important Derived Types</a>
+</div>
+<div class="doc_text">
+<dl>
+ <dt><tt>IntegerType</tt></dt>
+ <dd>Subclass of DerivedType that represents integer types of any bit width.
+ Any bit width between <tt>IntegerType::MIN_INT_BITS</tt> (1) and
+ <tt>IntegerType::MAX_INT_BITS</tt> (~8 million) can be represented.
+ <ul>
+ <li><tt>static const IntegerType* get(unsigned NumBits)</tt>: get an integer
+ type of a specific bit width.</li>
+ <li><tt>unsigned getBitWidth() const</tt>: Get the bit width of an integer
+ type.</li>
+ </ul>
+ </dd>
+ <dt><tt>SequentialType</tt></dt>
+ <dd>This is subclassed by ArrayType and PointerType
+ <ul>
+ <li><tt>const Type * getElementType() const</tt>: Returns the type of each
+ of the elements in the sequential type. </li>
+ </ul>
+ </dd>
+ <dt><tt>ArrayType</tt></dt>
+ <dd>This is a subclass of SequentialType and defines the interface for array
+ types.
+ <ul>
+ <li><tt>unsigned getNumElements() const</tt>: Returns the number of
+ elements in the array. </li>
+ </ul>
+ </dd>
+ <dt><tt>PointerType</tt></dt>
+ <dd>Subclass of SequentialType for pointer types.</dd>
+ <dt><tt>VectorType</tt></dt>
+ <dd>Subclass of SequentialType for vector types. A
+ vector type is similar to an ArrayType but is distinguished because it is
+ a first class type wherease ArrayType is not. Vector types are used for
+ vector operations and are usually small vectors of of an integer or floating
+ point type.</dd>
+ <dt><tt>StructType</tt></dt>
+ <dd>Subclass of DerivedTypes for struct types.</dd>
+ <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
+ function</li>
+ <li><tt> const Type * getReturnType() const</tt>: Returns the
+ return type of the function.</li>
+ <li><tt>const Type * getParamType (unsigned i)</tt>: Returns
+ the type of the ith parameter.</li>
+ <li><tt> const unsigned getNumParams() const</tt>: Returns the
+ number of formal parameters.</li>
+ </ul>
+ </dd>
+ <dt><tt>OpaqueType</tt></dt>
+ <dd>Sublcass of DerivedType for abstract types. This class
+ defines no content and is used as a placeholder for some other type. Note
+ that OpaqueType is used (temporarily) during type resolution for forward
+ references of types. Once the referenced type is resolved, the OpaqueType
+ is replaced with the actual type. OpaqueType can also be used for data
+ abstraction. At link time opaque types can be resolved to actual types
+ of the same name.</dd>
+</dl>
+</div>
- <dt><tt>plane_const_iterator find(const Type* Typ ) const</tt>:</dt>
- <dd>This method returns a plane_const_iterator for iteration over
- the type planes starting at a specific plane, given by \p Ty.</dd>
- <dt><tt>plane_iterator find( const Type* Typ </tt>:</dt>
- <dd>This method returns a plane_iterator for iteration over the
- type planes starting at a specific plane, given by \p Ty.</dd>
-</dl>
+<!-- ======================================================================= -->
+<div class="doc_subsection">
+ <a name="Module">The <tt>Module</tt> class</a>
</div>
+<div class="doc_text">
+<p><tt>#include "<a
+href="/doxygen/Module_8h-source.html">llvm/Module.h</a>"</tt><br> doxygen info:
+<a href="/doxygen/classllvm_1_1Module.html">Module Class</a></p>
+
+<p>The <tt>Module</tt> class represents the top level structure present in LLVM
+programs. An LLVM module is effectively either a translation unit of the
+original program or a combination of several translation units merged by the
+linker. The <tt>Module</tt> class keeps track of a list of <a
+href="#Function"><tt>Function</tt></a>s, a list of <a
+href="#GlobalVariable"><tt>GlobalVariable</tt></a>s, and a <a
+href="#SymbolTable"><tt>SymbolTable</tt></a>. Additionally, it contains a few
+helpful member functions that try to make common operations easy.</p>
-<!-- *********************************************************************** -->
-<div class="doc_section">
- <a name="coreclasses">The Core LLVM Class Hierarchy Reference </a>
</div>
-<!-- *********************************************************************** -->
+
+<!-- _______________________________________________________________________ -->
+<div class="doc_subsubsection">
+ <a name="m_Module">Important Public Members of the <tt>Module</tt> class</a>
+</div>
<div class="doc_text">
-<p>The Core LLVM classes are the primary means of representing the program
-being inspected or transformed. The core LLVM classes are defined in
-header files in the <tt>include/llvm/</tt> directory, and implemented in
-the <tt>lib/VMCore</tt> directory.</p>
+<ul>
+ <li><tt>Module::Module(std::string name = "")</tt></li>
+</ul>
+
+<p>Constructing a <a href="#Module">Module</a> is easy. You can optionally
+provide a name for it (probably based on the name of the translation unit).</p>
+
+<ul>
+ <li><tt>Module::iterator</tt> - Typedef for function list iterator<br>
+ <tt>Module::const_iterator</tt> - Typedef for const_iterator.<br>
+
+ <tt>begin()</tt>, <tt>end()</tt>
+ <tt>size()</tt>, <tt>empty()</tt>
+
+ <p>These are forwarding methods that make it easy to access the contents of
+ a <tt>Module</tt> object's <a href="#Function"><tt>Function</tt></a>
+ list.</p></li>
+
+ <li><tt>Module::FunctionListType &getFunctionList()</tt>
+
+ <p> Returns the list of <a href="#Function"><tt>Function</tt></a>s. This is
+ necessary to use when you need to update the list or perform a complex
+ action that doesn't have a forwarding method.</p>
+
+ <p><!-- Global Variable --></p></li>
+</ul>
+
+<hr>
+
+<ul>
+ <li><tt>Module::global_iterator</tt> - Typedef for global variable list iterator<br>
+
+ <tt>Module::const_global_iterator</tt> - Typedef for const_iterator.<br>
+
+ <tt>global_begin()</tt>, <tt>global_end()</tt>
+ <tt>global_size()</tt>, <tt>global_empty()</tt>
+
+ <p> These are forwarding methods that make it easy to access the contents of
+ a <tt>Module</tt> object's <a
+ href="#GlobalVariable"><tt>GlobalVariable</tt></a> list.</p></li>
+
+ <li><tt>Module::GlobalListType &getGlobalList()</tt>
+
+ <p>Returns the list of <a
+ href="#GlobalVariable"><tt>GlobalVariable</tt></a>s. This is necessary to
+ use when you need to update the list or perform a complex action that
+ doesn't have a forwarding method.</p>
+
+ <p><!-- Symbol table stuff --> </p></li>
+</ul>
+
+<hr>
+
+<ul>
+ <li><tt><a href="#SymbolTable">SymbolTable</a> *getSymbolTable()</tt>
+
+ <p>Return a reference to the <a href="#SymbolTable"><tt>SymbolTable</tt></a>
+ for this <tt>Module</tt>.</p>
+
+ <p><!-- Convenience methods --></p></li>
+</ul>
+
+<hr>
+
+<ul>
+ <li><tt><a href="#Function">Function</a> *getFunction(const std::string
+ &Name, const <a href="#FunctionType">FunctionType</a> *Ty)</tt>
+
+ <p>Look up the specified function in the <tt>Module</tt> <a
+ href="#SymbolTable"><tt>SymbolTable</tt></a>. If it does not exist, return
+ <tt>null</tt>.</p></li>
+
+ <li><tt><a href="#Function">Function</a> *getOrInsertFunction(const
+ std::string &Name, const <a href="#FunctionType">FunctionType</a> *T)</tt>
+
+ <p>Look up the specified function in the <tt>Module</tt> <a
+ href="#SymbolTable"><tt>SymbolTable</tt></a>. If it does not exist, add an
+ external declaration for the function and return it.</p></li>
+
+ <li><tt>std::string getTypeName(const <a href="#Type">Type</a> *Ty)</tt>
+
+ <p>If there is at least one entry in the <a
+ href="#SymbolTable"><tt>SymbolTable</tt></a> for the specified <a
+ href="#Type"><tt>Type</tt></a>, return it. Otherwise return the empty
+ string.</p></li>
+
+ <li><tt>bool addTypeName(const std::string &Name, const <a
+ href="#Type">Type</a> *Ty)</tt>
+
+ <p>Insert an entry in the <a href="#SymbolTable"><tt>SymbolTable</tt></a>
+ mapping <tt>Name</tt> to <tt>Ty</tt>. If there is already an entry for this
+ name, true is returned and the <a
+ href="#SymbolTable"><tt>SymbolTable</tt></a> is not modified.</p></li>
+</ul>
</div>
+
<!-- ======================================================================= -->
<div class="doc_subsection">
<a name="Value">The <tt>Value</tt> class</a>
</div>
-<div>
+<div class="doc_text">
<p><tt>#include "<a href="/doxygen/Value_8h-source.html">llvm/Value.h</a>"</tt>
<br>
<div class="doc_code">
<pre>
-%<b>foo</b> = add int 1, 2
+%<b>foo</b> = add i32 1, 2
</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
and it has no name</p></li>
</ul>
-</div>
-
-<!-- ======================================================================= -->
-<div class="doc_subsection">
- <a name="BasicBlock">The <tt>BasicBlock</tt> class</a>
-</div>
-
-<div class="doc_text">
-
-<p><tt>#include "<a
-href="/doxygen/BasicBlock_8h-source.html">llvm/BasicBlock.h</a>"</tt><br>
-doxygen info: <a href="/doxygen/structllvm_1_1BasicBlock.html">BasicBlock
-Class</a><br>
-Superclass: <a href="#Value"><tt>Value</tt></a></p>
-
-<p>This class represents a single entry multiple exit section of the code,
-commonly known as a basic block by the compiler community. The
-<tt>BasicBlock</tt> class maintains a list of <a
-href="#Instruction"><tt>Instruction</tt></a>s, which form the body of the block.
-Matching the language definition, the last element of this list of instructions
-is always a terminator instruction (a subclass of the <a
-href="#TerminatorInst"><tt>TerminatorInst</tt></a> class).</p>
-
-<p>In addition to tracking the list of instructions that make up the block, the
-<tt>BasicBlock</tt> class also keeps track of the <a
-href="#Function"><tt>Function</tt></a> that it is embedded into.</p>
-
-<p>Note that <tt>BasicBlock</tt>s themselves are <a
-href="#Value"><tt>Value</tt></a>s, because they are referenced by instructions
-like branches and can go in the switch tables. <tt>BasicBlock</tt>s have type
-<tt>label</tt>.</p>
-
-</div>
-
-<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection">
- <a name="m_BasicBlock">Important Public Members of the <tt>BasicBlock</tt>
- class</a>
-</div>
-
-<div class="doc_text">
-
-<ul>
-
-<li><tt>BasicBlock(const std::string &Name = "", </tt><tt><a
- href="#Function">Function</a> *Parent = 0)</tt>
-
-<p>The <tt>BasicBlock</tt> constructor is used to create new basic blocks for
-insertion into a function. The constructor optionally takes a name for the new
-block, and a <a href="#Function"><tt>Function</tt></a> to insert it into. If
-the <tt>Parent</tt> parameter is specified, the new <tt>BasicBlock</tt> is
-automatically inserted at the end of the specified <a
-href="#Function"><tt>Function</tt></a>, if not specified, the BasicBlock must be
-manually inserted into the <a href="#Function"><tt>Function</tt></a>.</p></li>
-
-<li><tt>BasicBlock::iterator</tt> - Typedef for instruction list iterator<br>
-<tt>BasicBlock::const_iterator</tt> - Typedef for const_iterator.<br>
-<tt>begin()</tt>, <tt>end()</tt>, <tt>front()</tt>, <tt>back()</tt>,
-<tt>size()</tt>, <tt>empty()</tt>
-STL-style functions for accessing the instruction list.
-
-<p>These methods and typedefs are forwarding functions that have the same
-semantics as the standard library methods of the same names. These methods
-expose the underlying instruction list of a basic block in a way that is easy to
-manipulate. To get the full complement of container operations (including
-operations to update the list), you must use the <tt>getInstList()</tt>
-method.</p></li>
-
-<li><tt>BasicBlock::InstListType &getInstList()</tt>
-
-<p>This method is used to get access to the underlying container that actually
-holds the Instructions. This method must be used when there isn't a forwarding
-function in the <tt>BasicBlock</tt> class for the operation that you would like
-to perform. Because there are no forwarding functions for "updating"
-operations, you need to use this if you want to update the contents of a
-<tt>BasicBlock</tt>.</p></li>
+</div>
-<li><tt><a href="#Function">Function</a> *getParent()</tt>
+<!-- ======================================================================= -->
+<div class="doc_subsection">
+ <a name="Constant">The <tt>Constant</tt> class and subclasses</a>
+</div>
-<p> Returns a pointer to <a href="#Function"><tt>Function</tt></a> the block is
-embedded into, or a null pointer if it is homeless.</p></li>
+<div class="doc_text">
-<li><tt><a href="#TerminatorInst">TerminatorInst</a> *getTerminator()</tt>
+<p>Constant represents a base class for different types of constants. It
+is subclassed by ConstantInt, ConstantArray, etc. for representing
+the various types of Constants. <a href="#GlobalValue">GlobalValue</a> is also
+a subclass, which represents the address of a global variable or function.
+</p>
-<p> Returns a pointer to the terminator instruction that appears at the end of
-the <tt>BasicBlock</tt>. If there is no terminator instruction, or if the last
-instruction in the block is not a terminator, then a null pointer is
-returned.</p></li>
+</div>
+<!-- _______________________________________________________________________ -->
+<div class="doc_subsubsection">Important Subclasses of Constant </div>
+<div class="doc_text">
+<ul>
+ <li>ConstantInt : This subclass of Constant represents an integer constant of
+ any width.
+ <ul>
+ <li><tt>const APInt& getValue() const</tt>: Returns the underlying
+ value of this constant, an APInt value.</li>
+ <li><tt>int64_t getSExtValue() const</tt>: Converts the underlying APInt
+ value to an int64_t via sign extension. If the value (not the bit width)
+ of the APInt is too large to fit in an int64_t, an assertion will result.
+ For this reason, use of this method is discouraged.</li>
+ <li><tt>uint64_t getZExtValue() const</tt>: Converts the underlying APInt
+ value to a uint64_t via zero extension. IF the value (not the bit width)
+ of the APInt is too large to fit in a uint64_t, an assertion will result.
+ For this reason, use of this method is discouraged.</li>
+ <li><tt>static ConstantInt* get(const APInt& Val)</tt>: Returns the
+ ConstantInt object that represents the value provided by <tt>Val</tt>.
+ The type is implied as the IntegerType that corresponds to the bit width
+ of <tt>Val</tt>.</li>
+ <li><tt>static ConstantInt* get(const Type *Ty, uint64_t Val)</tt>:
+ Returns the ConstantInt object that represents the value provided by
+ <tt>Val</tt> for integer type <tt>Ty</tt>.</li>
+ </ul>
+ </li>
+ <li>ConstantFP : This class represents a floating point constant.
+ <ul>
+ <li><tt>double getValue() const</tt>: Returns the underlying value of
+ this constant. </li>
+ </ul>
+ </li>
+ <li>ConstantArray : This represents a constant array.
+ <ul>
+ <li><tt>const std::vector<Use> &getValues() const</tt>: Returns
+ a vector of component constants that makeup this array. </li>
+ </ul>
+ </li>
+ <li>ConstantStruct : This represents a constant struct.
+ <ul>
+ <li><tt>const std::vector<Use> &getValues() const</tt>: Returns
+ a vector of component constants that makeup this array. </li>
+ </ul>
+ </li>
+ <li>GlobalValue : This represents either a global variable or a function. In
+ either case, the value is a constant fixed address (after linking).
+ </li>
</ul>
-
</div>
+
<!-- ======================================================================= -->
<div class="doc_subsection">
<a name="GlobalValue">The <tt>GlobalValue</tt> class</a>
when using the <tt>GetElementPtrInst</tt> instruction because this pointer must
be dereferenced first. For example, if you have a <tt>GlobalVariable</tt> (a
subclass of <tt>GlobalValue)</tt> that is an array of 24 ints, type <tt>[24 x
-int]</tt>, then the <tt>GlobalVariable</tt> is a pointer to that array. Although
+i32]</tt>, then the <tt>GlobalVariable</tt> is a pointer to that array. Although
the address of the first element of this array and the value of the
<tt>GlobalVariable</tt> are the same, they have different types. The
-<tt>GlobalVariable</tt>'s type is <tt>[24 x int]</tt>. The first element's type
-is <tt>int.</tt> Because of this, accessing a global value requires you to
+<tt>GlobalVariable</tt>'s type is <tt>[24 x i32]</tt>. The first element's type
+is <tt>i32.</tt> Because of this, accessing a global value requires you to
dereference the pointer with <tt>GetElementPtrInst</tt> first, then its elements
can be accessed. This is explained in the <a href="LangRef.html#globalvars">LLVM
Language Reference Manual</a>.</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
<tt>size()</tt>, <tt>empty()</tt>
<p>These are forwarding methods that make it easy to access the contents of
- a <tt>Function</tt> object's <a href="#BasicBlock"><tt>BasicBlock</tt></a>
- list.</p></li>
-
- <li><tt>Function::BasicBlockListType &getBasicBlockList()</tt>
-
- <p>Returns the list of <a href="#BasicBlock"><tt>BasicBlock</tt></a>s. This
- is necessary to use when you need to update the list or perform a complex
- action that doesn't have a forwarding method.</p></li>
-
- <li><tt>Function::arg_iterator</tt> - Typedef for the argument list
-iterator<br>
- <tt>Function::const_arg_iterator</tt> - Typedef for const_iterator.<br>
-
- <tt>arg_begin()</tt>, <tt>arg_end()</tt>
- <tt>arg_size()</tt>, <tt>arg_empty()</tt>
-
- <p>These are forwarding methods that make it easy to access the contents of
- a <tt>Function</tt> object's <a href="#Argument"><tt>Argument</tt></a>
- list.</p></li>
-
- <li><tt>Function::ArgumentListType &getArgumentList()</tt>
-
- <p>Returns the list of <a href="#Argument"><tt>Argument</tt></a>s. This is
- necessary to use when you need to update the list or perform a complex
- action that doesn't have a forwarding method.</p></li>
-
- <li><tt><a href="#BasicBlock">BasicBlock</a> &getEntryBlock()</tt>
-
- <p>Returns the entry <a href="#BasicBlock"><tt>BasicBlock</tt></a> for the
- function. Because the entry block for the function is always the first
- block, this returns the first block of the <tt>Function</tt>.</p></li>
-
- <li><tt><a href="#Type">Type</a> *getReturnType()</tt><br>
- <tt><a href="#FunctionType">FunctionType</a> *getFunctionType()</tt>
-
- <p>This traverses the <a href="#Type"><tt>Type</tt></a> of the
- <tt>Function</tt> and returns the return type of the function, or the <a
- href="#FunctionType"><tt>FunctionType</tt></a> of the actual
- function.</p></li>
-
- <li><tt><a href="#SymbolTable">SymbolTable</a> *getSymbolTable()</tt>
-
- <p> Return a pointer to the <a href="#SymbolTable"><tt>SymbolTable</tt></a>
- for this <tt>Function</tt>.</p></li>
-</ul>
-
-</div>
-
-<!-- ======================================================================= -->
-<div class="doc_subsection">
- <a name="GlobalVariable">The <tt>GlobalVariable</tt> class</a>
-</div>
-
-<div class="doc_text">
-
-<p><tt>#include "<a
-href="/doxygen/GlobalVariable_8h-source.html">llvm/GlobalVariable.h</a>"</tt>
-<br>
-doxygen info: <a href="/doxygen/classllvm_1_1GlobalVariable.html">GlobalVariable
- Class</a><br>
-Superclasses: <a href="#GlobalValue"><tt>GlobalValue</tt></a>,
-<a href="#Constant"><tt>Constant</tt></a>,
-<a href="#User"><tt>User</tt></a>,
-<a href="#Value"><tt>Value</tt></a></p>
-
-<p>Global variables are represented with the (suprise suprise)
-<tt>GlobalVariable</tt> class. Like functions, <tt>GlobalVariable</tt>s are also
-subclasses of <a href="#GlobalValue"><tt>GlobalValue</tt></a>, and as such are
-always referenced by their address (global values must live in memory, so their
-"name" refers to their constant address). See
-<a href="#GlobalValue"><tt>GlobalValue</tt></a> for more on this. Global
-variables may have an initial value (which must be a
-<a href="#Constant"><tt>Constant</tt></a>), and if they have an initializer,
-they may be marked as "constant" themselves (indicating that their contents
-never change at runtime).</p>
-</div>
-
-<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection">
- <a name="m_GlobalVariable">Important Public Members of the
- <tt>GlobalVariable</tt> class</a>
-</div>
-
-<div class="doc_text">
-
-<ul>
- <li><tt>GlobalVariable(const </tt><tt><a href="#Type">Type</a> *Ty, bool
- isConstant, LinkageTypes& Linkage, <a href="#Constant">Constant</a>
- *Initializer = 0, const std::string &Name = "", Module* Parent = 0)</tt>
-
- <p>Create a new global variable of the specified type. If
- <tt>isConstant</tt> is true then the global variable will be marked as
- unchanging for the program. The Linkage parameter specifies the type of
- linkage (internal, external, weak, linkonce, appending) for the variable. If
- the linkage is InternalLinkage, WeakLinkage, or LinkOnceLinkage, then
- the resultant global variable will have internal linkage. AppendingLinkage
- concatenates together all instances (in different translation units) of the
- variable into a single variable but is only applicable to arrays. See
- the <a href="LangRef.html#modulestructure">LLVM Language Reference</a> for
- further details on linkage types. Optionally an initializer, a name, and the
- module to put the variable into may be specified for the global variable as
- well.</p></li>
-
- <li><tt>bool isConstant() const</tt>
-
- <p>Returns true if this is a global variable that is known not to
- be modified at runtime.</p></li>
-
- <li><tt>bool hasInitializer()</tt>
-
- <p>Returns true if this <tt>GlobalVariable</tt> has an intializer.</p></li>
-
- <li><tt><a href="#Constant">Constant</a> *getInitializer()</tt>
-
- <p>Returns the intial value for a <tt>GlobalVariable</tt>. It is not legal
- to call this method if there is no initializer.</p></li>
-</ul>
-
-</div>
-
-<!-- ======================================================================= -->
-<div class="doc_subsection">
- <a name="Module">The <tt>Module</tt> class</a>
-</div>
-
-<div class="doc_text">
-
-<p><tt>#include "<a
-href="/doxygen/Module_8h-source.html">llvm/Module.h</a>"</tt><br> doxygen info:
-<a href="/doxygen/classllvm_1_1Module.html">Module Class</a></p>
-
-<p>The <tt>Module</tt> class represents the top level structure present in LLVM
-programs. An LLVM module is effectively either a translation unit of the
-original program or a combination of several translation units merged by the
-linker. The <tt>Module</tt> class keeps track of a list of <a
-href="#Function"><tt>Function</tt></a>s, a list of <a
-href="#GlobalVariable"><tt>GlobalVariable</tt></a>s, and a <a
-href="#SymbolTable"><tt>SymbolTable</tt></a>. Additionally, it contains a few
-helpful member functions that try to make common operations easy.</p>
-
-</div>
-
-<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection">
- <a name="m_Module">Important Public Members of the <tt>Module</tt> class</a>
-</div>
-
-<div class="doc_text">
-
-<ul>
- <li><tt>Module::Module(std::string name = "")</tt></li>
-</ul>
-
-<p>Constructing a <a href="#Module">Module</a> is easy. You can optionally
-provide a name for it (probably based on the name of the translation unit).</p>
-
-<ul>
- <li><tt>Module::iterator</tt> - Typedef for function list iterator<br>
- <tt>Module::const_iterator</tt> - Typedef for const_iterator.<br>
-
- <tt>begin()</tt>, <tt>end()</tt>
- <tt>size()</tt>, <tt>empty()</tt>
-
- <p>These are forwarding methods that make it easy to access the contents of
- a <tt>Module</tt> object's <a href="#Function"><tt>Function</tt></a>
- list.</p></li>
-
- <li><tt>Module::FunctionListType &getFunctionList()</tt>
-
- <p> Returns the list of <a href="#Function"><tt>Function</tt></a>s. This is
- necessary to use when you need to update the list or perform a complex
- action that doesn't have a forwarding method.</p>
-
- <p><!-- Global Variable --></p></li>
-</ul>
-
-<hr>
-
-<ul>
- <li><tt>Module::global_iterator</tt> - Typedef for global variable list iterator<br>
-
- <tt>Module::const_global_iterator</tt> - Typedef for const_iterator.<br>
-
- <tt>global_begin()</tt>, <tt>global_end()</tt>
- <tt>global_size()</tt>, <tt>global_empty()</tt>
-
- <p> These are forwarding methods that make it easy to access the contents of
- a <tt>Module</tt> object's <a
- href="#GlobalVariable"><tt>GlobalVariable</tt></a> list.</p></li>
-
- <li><tt>Module::GlobalListType &getGlobalList()</tt>
-
- <p>Returns the list of <a
- href="#GlobalVariable"><tt>GlobalVariable</tt></a>s. This is necessary to
- use when you need to update the list or perform a complex action that
- doesn't have a forwarding method.</p>
-
- <p><!-- Symbol table stuff --> </p></li>
-</ul>
+ a <tt>Function</tt> object's <a href="#BasicBlock"><tt>BasicBlock</tt></a>
+ list.</p></li>
-<hr>
+ <li><tt>Function::BasicBlockListType &getBasicBlockList()</tt>
-<ul>
- <li><tt><a href="#SymbolTable">SymbolTable</a> *getSymbolTable()</tt>
+ <p>Returns the list of <a href="#BasicBlock"><tt>BasicBlock</tt></a>s. This
+ is necessary to use when you need to update the list or perform a complex
+ action that doesn't have a forwarding method.</p></li>
- <p>Return a reference to the <a href="#SymbolTable"><tt>SymbolTable</tt></a>
- for this <tt>Module</tt>.</p>
+ <li><tt>Function::arg_iterator</tt> - Typedef for the argument list
+iterator<br>
+ <tt>Function::const_arg_iterator</tt> - Typedef for const_iterator.<br>
- <p><!-- Convenience methods --></p></li>
-</ul>
+ <tt>arg_begin()</tt>, <tt>arg_end()</tt>
+ <tt>arg_size()</tt>, <tt>arg_empty()</tt>
-<hr>
+ <p>These are forwarding methods that make it easy to access the contents of
+ a <tt>Function</tt> object's <a href="#Argument"><tt>Argument</tt></a>
+ list.</p></li>
-<ul>
- <li><tt><a href="#Function">Function</a> *getFunction(const std::string
- &Name, const <a href="#FunctionType">FunctionType</a> *Ty)</tt>
+ <li><tt>Function::ArgumentListType &getArgumentList()</tt>
- <p>Look up the specified function in the <tt>Module</tt> <a
- href="#SymbolTable"><tt>SymbolTable</tt></a>. If it does not exist, return
- <tt>null</tt>.</p></li>
+ <p>Returns the list of <a href="#Argument"><tt>Argument</tt></a>s. This is
+ necessary to use when you need to update the list or perform a complex
+ action that doesn't have a forwarding method.</p></li>
- <li><tt><a href="#Function">Function</a> *getOrInsertFunction(const
- std::string &Name, const <a href="#FunctionType">FunctionType</a> *T)</tt>
+ <li><tt><a href="#BasicBlock">BasicBlock</a> &getEntryBlock()</tt>
- <p>Look up the specified function in the <tt>Module</tt> <a
- href="#SymbolTable"><tt>SymbolTable</tt></a>. If it does not exist, add an
- external declaration for the function and return it.</p></li>
+ <p>Returns the entry <a href="#BasicBlock"><tt>BasicBlock</tt></a> for the
+ function. Because the entry block for the function is always the first
+ block, this returns the first block of the <tt>Function</tt>.</p></li>
- <li><tt>std::string getTypeName(const <a href="#Type">Type</a> *Ty)</tt>
+ <li><tt><a href="#Type">Type</a> *getReturnType()</tt><br>
+ <tt><a href="#FunctionType">FunctionType</a> *getFunctionType()</tt>
- <p>If there is at least one entry in the <a
-
href="#SymbolTable"><tt>SymbolTable</tt></a> for the specified <a
- href="#Type"><tt>Type</tt></a>, return it. Otherwise return the empty
- string.</p></li>
+ <p>This traverses the <a href="#Type"><tt>Type</tt></a> of the
+
<tt>Function</tt> and returns the return type of the function, or the <a
+ href="#FunctionType"><tt>FunctionType</tt></a> of the actual
+ function.</p></li>
- <li><tt>bool addTypeName(const std::string &Name, const <a
- href="#Type">Type</a> *Ty)</tt>
+ <li><tt><a href="#SymbolTable">SymbolTable</a> *getSymbolTable()</tt>
- <p>Insert an entry in the <a href="#SymbolTable"><tt>SymbolTable</tt></a>
- mapping <tt>Name</tt> to <tt>Ty</tt>. If there is already an entry for this
- name, true is returned and the <a
- href="#SymbolTable"><tt>SymbolTable</tt></a> is not modified.</p></li>
+ <p> Return a pointer to the <a href="#SymbolTable"><tt>SymbolTable</tt></a>
+ for this <tt>Function</tt>.</p></li>
</ul>
</div>
<!-- ======================================================================= -->
<div class="doc_subsection">
- <a name="Constant">The <tt>Constant</tt> class and subclasses</a>
+ <a name="GlobalVariable">The <tt>GlobalVariable</tt> class</a>
</div>
<div class="doc_text">
-<p>Constant represents a base class for different types of constants. It
-is subclassed by ConstantInt, ConstantArray, etc. for representing
-the various types of Constants.</p>
+<p><tt>#include "<a
+href="/doxygen/GlobalVariable_8h-source.html">llvm/GlobalVariable.h</a>"</tt>
+<br>
+doxygen info: <a href="/doxygen/classllvm_1_1GlobalVariable.html">GlobalVariable
+ Class</a><br>
+Superclasses: <a href="#GlobalValue"><tt>GlobalValue</tt></a>,
+<a href="#Constant"><tt>Constant</tt></a>,
+<a href="#User"><tt>User</tt></a>,
+<a href="#Value"><tt>Value</tt></a></p>
+<p>Global variables are represented with the (suprise suprise)
+<tt>GlobalVariable</tt> class. Like functions, <tt>GlobalVariable</tt>s are also
+subclasses of <a href="#GlobalValue"><tt>GlobalValue</tt></a>, and as such are
+always referenced by their address (global values must live in memory, so their
+"name" refers to their constant address). See
+<a href="#GlobalValue"><tt>GlobalValue</tt></a> for more on this. Global
+variables may have an initial value (which must be a
+<a href="#Constant"><tt>Constant</tt></a>), and if they have an initializer,
+they may be marked as "constant" themselves (indicating that their contents
+never change at runtime).</p>
</div>
<!-- _______________________________________________________________________ -->
<div class="doc_subsubsection">
- <a name="m_Constant">Important Public Methods</a>
-</div>
-<div class="doc_text">
+ <a name="m_GlobalVariable">Important Public Members of the
+ <tt>GlobalVariable</tt> class</a>
</div>
-<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection">Important Subclasses of Constant </div>
<div class="doc_text">
+
<ul>
- <li>ConstantInt : This subclass of Constant represents an integer constant of
- any width, including boolean (1 bit integer).
- <ul>
- <li><tt>int64_t getSExtValue() const</tt>: Returns the underlying value of
- this constant as a sign extended signed integer value.</li>
- <li><tt>uint64_t getZExtValue() const</tt>: Returns the underlying value
- of this constant as a zero extended unsigned integer value.</li>
- <li><tt>static ConstantInt* get(const Type *Ty, uint64_t Val)</tt>:
- Returns the ConstantInt object that represents the value provided by
- <tt>Val</tt> for integer type <tt>Ty</tt>.</li>
- </ul>
- </li>
- <li>ConstantFP : This class represents a floating point constant.
- <ul>
- <li><tt>double getValue() const</tt>: Returns the underlying value of
- this constant. </li>
- </ul>
- </li>
- <ul>
- <li><tt>bool getValue() const</tt>: Returns the underlying value of this
- constant. </li>
- </ul>
- </li>
- <li>ConstantArray : This represents a constant array.
- <ul>
- <li><tt>const std::vector<Use> &getValues() const</tt>: Returns
- a vector of component constants that makeup this array. </li>
- </ul>
- </li>
- <li>ConstantStruct : This represents a constant struct.
- <ul>
- <li><tt>const std::vector<Use> &getValues() const</tt>: Returns
- a vector of component constants that makeup this array. </li>
- </ul>
- </li>
- <li>GlobalValue : This represents either a global variable or a function. In
- either case, the value is a constant fixed address (after linking).
- </li>
+ <li><tt>GlobalVariable(const </tt><tt><a href="#Type">Type</a> *Ty, bool
+ isConstant, LinkageTypes& Linkage, <a href="#Constant">Constant</a>
+ *Initializer = 0, const std::string &Name = "", Module* Parent = 0)</tt>
+
+ <p>Create a new global variable of the specified type. If
+ <tt>isConstant</tt> is true then the global variable will be marked as
+ unchanging for the program. The Linkage parameter specifies the type of
+ linkage (internal, external, weak, linkonce, appending) for the variable. If
+ the linkage is InternalLinkage, WeakLinkage, or LinkOnceLinkage, then
+ the resultant global variable will have internal linkage. AppendingLinkage
+ concatenates together all instances (in different translation units) of the
+ variable into a single variable but is only applicable to arrays. See
+ the <a href="LangRef.html#modulestructure">LLVM Language Reference</a> for
+ further details on linkage types. Optionally an initializer, a name, and the
+ module to put the variable into may be specified for the global variable as
+ well.</p></li>
+
+ <li><tt>bool isConstant() const</tt>
+
+ <p>Returns true if this is a global variable that is known not to
+ be modified at runtime.</p></li>
+
+ <li><tt>bool hasInitializer()</tt>
+
+ <p>Returns true if this <tt>GlobalVariable</tt> has an intializer.</p></li>
+
+ <li><tt><a href="#Constant">Constant</a> *getInitializer()</tt>
+
+ <p>Returns the intial value for a <tt>GlobalVariable</tt>. It is not legal
+ to call this method if there is no initializer.</p></li>
</ul>
+
</div>
+
<!-- ======================================================================= -->
<div class="doc_subsection">
- <a name="Type">The <tt>Type</tt> class and Derived Types</a>
+ <a name="BasicBlock">The <tt>BasicBlock</tt> class</a>
</div>
<div class="doc_text">
-<p>Type as noted earlier is also a subclass of a Value class. Any primitive
-type (like int, short etc) in LLVM is an instance of Type Class. All other
-types are instances of subclasses of type like FunctionType, ArrayType
-etc. DerivedType is the interface for all such dervied types including
-FunctionType, ArrayType, PointerType, StructType. Types can have names. They can
-be recursive (StructType). There exists exactly one instance of any type
-structure at a time. This allows using pointer equality of Type *s for comparing
-types.</p>
+<p><tt>#include "<a
+href="/doxygen/BasicBlock_8h-source.html">llvm/BasicBlock.h</a>"</tt><br>
+doxygen info: <a href="/doxygen/structllvm_1_1BasicBlock.html">BasicBlock
+Class</a><br>
+Superclass: <a href="#Value"><tt>Value</tt></a></p>
+
+<p>This class represents a single entry multiple exit section of the code,
+commonly known as a basic block by the compiler community. The
+<tt>BasicBlock</tt> class maintains a list of <a
+href="#Instruction"><tt>Instruction</tt></a>s, which form the body of the block.
+Matching the language definition, the last element of this list of instructions
+is always a terminator instruction (a subclass of the <a
+href="#TerminatorInst"><tt>TerminatorInst</tt></a> class).</p>
+
+<p>In addition to tracking the list of instructions that make up the block, the
+<tt>BasicBlock</tt> class also keeps track of the <a
+href="#Function"><tt>Function</tt></a> that it is embedded into.</p>
+
+<p>Note that <tt>BasicBlock</tt>s themselves are <a
+href="#Value"><tt>Value</tt></a>s, because they are referenced by instructions
+like branches and can go in the switch tables. <tt>BasicBlock</tt>s have type
+<tt>label</tt>.</p>
</div>
<!-- _______________________________________________________________________ -->
<div class="doc_subsubsection">
- <a name="m_Value">Important Public Methods</a>
+ <a name="m_BasicBlock">Important Public Members of the <tt>BasicBlock</tt>
+ class</a>
</div>
<div class="doc_text">
-
<ul>
- <li><tt>bool isInteger() const</tt>: True for any integer type.</li>
- <li><tt>bool isIntegral() const</tt>: Returns true if this is an integral
- type, which is either Bool type or one of the Integer types.</li>
+<li><tt>BasicBlock(const std::string &Name = "", </tt><tt><a
+ href="#Function">Function</a> *Parent = 0)</tt>
- <li><tt>bool isFloatingPoint()</tt>: Return true if this is one of the two
- floating point types.</li>
+<p>The <tt>BasicBlock</tt> constructor is used to create new basic blocks for
+insertion into a function. The constructor optionally takes a name for the new
+block, and a <a href="#Function"><tt>Function</tt></a> to insert it into. If
+the <tt>Parent</tt> parameter is specified, the new <tt>BasicBlock</tt> is
+automatically inserted at the end of the specified <a
+href="#Function"><tt>Function</tt></a>, if not specified, the BasicBlock must be
+manually inserted into the <a href="#Function"><tt>Function</tt></a>.</p></li>
- <li><tt>isLosslesslyConvertableTo (const Type *Ty) const</tt>: Return true if
- this type can be converted to 'Ty' without any reinterpretation of bits. For
- example, uint to int or one pointer type to another.</li>
-</ul>
-</div>
+<li><tt>BasicBlock::iterator</tt> - Typedef for instruction list iterator<br>
+<tt>BasicBlock::const_iterator</tt> - Typedef for const_iterator.<br>
+<tt>begin()</tt>, <tt>end()</tt>, <tt>front()</tt>, <tt>back()</tt>,
+<tt>size()</tt>, <tt>empty()</tt>
+STL-style functions for accessing the instruction list.
+
+<p>These methods and typedefs are forwarding functions that have the same
+semantics as the standard library methods of the same names. These methods
+expose the underlying instruction list of a basic block in a way that is easy to
+manipulate. To get the full complement of container operations (including
+operations to update the list), you must use the <tt>getInstList()</tt>
+method.</p></li>
+
+<li><tt>BasicBlock::InstListType &getInstList()</tt>
+
+<p>This method is used to get access to the underlying container that actually
+holds the Instructions. This method must be used when there isn't a forwarding
+function in the <tt>BasicBlock</tt> class for the operation that you would like
+to perform. Because there are no forwarding functions for "updating"
+operations, you need to use this if you want to update the contents of a
+<tt>BasicBlock</tt>.</p></li>
+
+<li><tt><a href="#Function">Function</a> *getParent()</tt>
+
+<p> Returns a pointer to <a href="#Function"><tt>Function</tt></a> the block is
+embedded into, or a null pointer if it is homeless.</p></li>
+
+<li><tt><a href="#TerminatorInst">TerminatorInst</a> *getTerminator()</tt>
+
+<p> Returns a pointer to the terminator instruction that appears at the end of
+the <tt>BasicBlock</tt>. If there is no terminator instruction, or if the last
+instruction in the block is not a terminator, then a null pointer is
+returned.</p></li>
-<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection">
- <a name="m_Value">Important Derived Types</a>
-</div>
-<div class="doc_text">
-<ul>
- <li>SequentialType : This is subclassed by ArrayType and PointerType
- <ul>
- <li><tt>const Type * getElementType() const</tt>: Returns the type of each
- of the elements in the sequential type. </li>
- </ul>
- </li>
- <li>ArrayType : This is a subclass of SequentialType and defines interface for
- array types.
- <ul>
- <li><tt>unsigned getNumElements() const</tt>: Returns the number of
- elements in the array. </li>
- </ul>
- </li>
- <li>PointerType : Subclass of SequentialType for pointer types. </li>
- <li>StructType : subclass of DerivedTypes for struct types </li>
- <li>FunctionType : subclass of DerivedTypes for function types.
- <ul>
- <li><tt>bool isVarArg() const</tt>: Returns true if its a vararg
- function</li>
- <li><tt> const Type * getReturnType() const</tt>: Returns the
- return type of the function.</li>
- <li><tt>const Type * getParamType (unsigned i)</tt>: Returns
- the type of the ith parameter.</li>
- <li><tt> const unsigned getNumParams() const</tt>: Returns the
- number of formal parameters.</li>
- </ul>
- </li>
</ul>
+
</div>
+
<!-- ======================================================================= -->
<div class="doc_subsection">
<a name="Argument">The <tt>Argument</tt> class</a>
projects / oota-llvm.git / blobdiff