"http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
+ <meta http-equiv="Content-type" content="text/html;charset=UTF-8">
<title>LLVM Programmer's Manual</title>
<link rel="stylesheet" href="llvm.css" type="text/css">
</head>
<ul>
<li><a href="#isa">The <tt>isa<></tt>, <tt>cast<></tt>
and <tt>dyn_cast<></tt> templates</a> </li>
+ <li><a href="#string_apis">Passing strings (the <tt>StringRef</tt>
+and <tt>Twine</tt> classes)</a>
+ <ul>
+ <li><a href="#StringRef">The <tt>StringRef</tt> class</a> </li>
+ <li><a href="#Twine">The <tt>Twine</tt> class</a> </li>
+ </ul>
+ </li>
<li><a href="#DEBUG">The <tt>DEBUG()</tt> macro and <tt>-debug</tt>
option</a>
<ul>
<li><a href="#dss_map"><map></a></li>
<li><a href="#dss_othermap">Other Map-Like Container Options</a></li>
</ul></li>
+ <li><a href="#ds_string">String-like containers</a>
+ <!--<ul>
+ todo
+ </ul>--></li>
<li><a href="#ds_bit">BitVector-like containers</a>
<ul>
<li><a href="#dss_bitvector">A dense bitvector</a></li>
</ul>
</li>
+ <li><a href="#threading">Threads and LLVM</a>
+ <ul>
+ <li><a href="#startmultithreaded">Entering and Exiting Multithreaded Mode
+ </a></li>
+ <li><a href="#shutdown">Ending execution with <tt>llvm_shutdown()</tt></a></li>
+ <li><a href="#managedstatic">Lazy initialization with <tt>ManagedStatic</tt></a></li>
+ </ul>
+ </li>
+
<li><a href="#advanced">Advanced Topics</a>
<ul>
<li><a href="#TypeResolve">LLVM Type Resolution</a>
<p>Written by <a href="mailto:sabre@nondot.org">Chris Lattner</a>,
<a href="mailto:dhurjati@cs.uiuc.edu">Dinakar Dhurjati</a>,
<a href="mailto:ggreif@gmail.com">Gabor Greif</a>,
- <a href="mailto:jstanley@cs.uiuc.edu">Joel Stanley</a> and
- <a href="mailto:rspencer@x10sys.com">Reid Spencer</a></p>
+ <a href="mailto:jstanley@cs.uiuc.edu">Joel Stanley</a>,
+ <a href="mailto:rspencer@x10sys.com">Reid Spencer</a> and
+ <a href="mailto:owen@apple.com">Owen Anderson</a></p>
</div>
<!-- *********************************************************************** -->
</div>
+
+<!-- ======================================================================= -->
+<div class="doc_subsection">
+ <a name="string_apis">Passing strings (the <tt>StringRef</tt>
+and <tt>Twine</tt> classes)</a>
+</div>
+
+<div class="doc_text">
+
+<p>Although LLVM generally does not do much string manipulation, we do have
+several important APIs which take strings. Two important examples are the
+Value class -- which has names for instructions, functions, etc. -- and the
+StringMap class which is used extensively in LLVM and Clang.</p>
+
+<p>These are generic classes, and they need to be able to accept strings which
+may have embedded null characters. Therefore, they cannot simply take
+a <tt>const char *</tt>, and taking a <tt>const std::string&</tt> requires
+clients to perform a heap allocation which is usually unnecessary. Instead,
+many LLVM APIs use a <tt>const StringRef&</tt> or a <tt>const
+Twine&</tt> for passing strings efficiently.</p>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<div class="doc_subsubsection">
+ <a name="StringRef">The <tt>StringRef</tt> class</a>
+</div>
+
+<div class="doc_text">
+
+<p>The <tt>StringRef</tt> data type represents a reference to a constant string
+(a character array and a length) and supports the common operations available
+on <tt>std:string</tt>, but does not require heap allocation.</p>
+
+<p>It can be implicitly constructed using a C style null-terminated string,
+an <tt>std::string</tt>, or explicitly with a character pointer and length.
+For example, the <tt>StringRef</tt> find function is declared as:</p>
+
+<div class="doc_code">
+ iterator find(const StringRef &Key);
+</div>
+
+<p>and clients can call it using any one of:</p>
+
+<div class="doc_code">
+<pre>
+ Map.find("foo"); <i>// Lookup "foo"</i>
+ Map.find(std::string("bar")); <i>// Lookup "bar"</i>
+ Map.find(StringRef("\0baz", 4)); <i>// Lookup "\0baz"</i>
+</pre>
+</div>
+
+<p>Similarly, APIs which need to return a string may return a <tt>StringRef</tt>
+instance, which can be used directly or converted to an <tt>std::string</tt>
+using the <tt>str</tt> member function. See
+"<tt><a href="/doxygen/classllvm_1_1StringRef_8h-source.html">llvm/ADT/StringRef.h</a></tt>"
+for more information.</p>
+
+<p>You should rarely use the <tt>StringRef</tt> class directly, because it contains
+pointers to external memory it is not generally safe to store an instance of the
+class (unless you know that the external storage will not be freed).</p>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<div class="doc_subsubsection">
+ <a name="Twine">The <tt>Twine</tt> class</a>
+</div>
+
+<div class="doc_text">
+
+<p>The <tt>Twine</tt> class is an efficient way for APIs to accept concatenated
+strings. For example, a common LLVM paradigm is to name one instruction based on
+the name of another instruction with a suffix, for example:</p>
+
+<div class="doc_code">
+<pre>
+ New = CmpInst::Create(<i>...</i>, SO->getName() + ".cmp");
+</pre>
+</div>
+
+<p>The <tt>Twine</tt> class is effectively a
+lightweight <a href="http://en.wikipedia.org/wiki/Rope_(computer_science)">rope</a>
+which points to temporary (stack allocated) objects. Twines can be implicitly
+constructed as the result of the plus operator applied to strings (i.e., a C
+strings, an <tt>std::string</tt>, or a <tt>StringRef</tt>). The twine delays the
+actual concatentation of strings until it is actually required, at which point
+it can be efficiently rendered directly into a character array. This avoids
+unnecessary heap allocation involved in constructing the temporary results of
+string concatenation. See
+"<tt><a href="/doxygen/classllvm_1_1Twine_8h-source.html">llvm/ADT/Twine.h</a></tt>"
+for more information.</p>
+
+<p>As with a <tt>StringRef</tt>, <tt>Twine</tt> objects point to external memory
+and should almost never be stored or mentioned directly. They are intended
+solely for use when defining a function which should be able to efficiently
+accept concatenated strings.</p>
+
+</div>
+
+
<!-- ======================================================================= -->
<div class="doc_subsection">
<a name="DEBUG">The <tt>DEBUG()</tt> macro and <tt>-debug</tt> option</a>
<div class="doc_code">
<pre>
-DOUT << "I am here!\n";
+DEBUG(errs() << "I am here!\n");
</pre>
</div>
<div class="doc_code">
<pre>
-DOUT << "No debug type\n";
#undef DEBUG_TYPE
+DEBUG(errs() << "No debug type\n");
#define DEBUG_TYPE "foo"
-DOUT << "'foo' debug type\n";
+DEBUG(errs() << "'foo' debug type\n");
#undef DEBUG_TYPE
#define DEBUG_TYPE "bar"
-DOUT << "'bar' debug type\n";
+DEBUG(errs() << "'bar' debug type\n"));
#undef DEBUG_TYPE
#define DEBUG_TYPE ""
-DOUT << "No debug type (2)\n";
+DEBUG(errs() << "No debug type (2)\n");
</pre>
</div>
for instruction scheduling to be enabled with <tt>-debug-type=InstrSched</tt>,
even if the source lives in multiple files.</p>
+<p>The <tt>DEBUG_WITH_TYPE</tt> macro is also available for situations where you
+would like to set <tt>DEBUG_TYPE</tt>, but only for one specific <tt>DEBUG</tt>
+statement. It takes an additional first parameter, which is the type to use. For
+example, the preceeding example could be written as:</p>
+
+
+<div class="doc_code">
+<pre>
+DEBUG_WITH_TYPE("", errs() << "No debug type\n");
+DEBUG_WITH_TYPE("foo", errs() << "'foo' debug type\n");
+DEBUG_WITH_TYPE("bar", errs() << "'bar' debug type\n"));
+DEBUG_WITH_TYPE("", errs() << "No debug type (2)\n");
+</pre>
+</div>
+
</div>
<!-- ======================================================================= -->
iteration, but do not support efficient look-up based on a key.
</li>
+<li>a <a href="#ds_string">string</a> container is a specialized sequential
+ container or reference structure that is used for character or byte
+ arrays.</li>
+
<li>a <a href="#ds_bit">bit</a> container provides an efficient way to store and
perform set operations on sets of numeric id's, while automatically
eliminating duplicates. Bit containers require a maximum of 1 bit for each
</div>
+<!-- ======================================================================= -->
+<div class="doc_subsection">
+ <a name="ds_string">String-like containers</a>
+</div>
+
+<div class="doc_text">
+
+<p>
+TODO: const char* vs stringref vs smallstring vs std::string. Describe twine,
+xref to #string_apis.
+</p>
+
+</div>
+
<!-- ======================================================================= -->
<div class="doc_subsection">
<a name="ds_bit">Bit storage containers (BitVector, SparseBitVector)</a>
<div class="doc_text">
<p>In generating IR, you may need some complex types. If you know these types
-statically, you can use <tt>TypeBuilder<...>::get()</tt>, defined
+statically, you can use <tt>TypeBuilder<...>::get()</tt>, defined
in <tt>llvm/Support/TypeBuilder.h</tt>, to retrieve them. <tt>TypeBuilder</tt>
has two forms depending on whether you're building types for cross-compilation
-or native library use. <tt>TypeBuilder<T, true></tt> requires
+or native library use. <tt>TypeBuilder<T, true></tt> requires
that <tt>T</tt> be independent of the host environment, meaning that it's built
out of types from
the <a href="/doxygen/namespacellvm_1_1types.html"><tt>llvm::types</tt></a>
namespace and pointers, functions, arrays, etc. built of
-those. <tt>TypeBuilder<T, false></tt> additionally allows native C types
+those. <tt>TypeBuilder<T, false></tt> additionally allows native C types
whose size may depend on the host compiler. For example,</p>
<div class="doc_code">
<pre>
-FunctionType *ft = TypeBuilder<types::i<8>(types::i<32>*), true>::get();
+FunctionType *ft = TypeBuilder<types::i<8>(types::i<32>*), true>::get();
</pre>
</div>
<div class="doc_code">
<pre>
-std::vector<const Type*> params;
+std::vector<const Type*> params;
params.push_back(PointerType::getUnqual(Type::Int32Ty));
FunctionType *ft = FunctionType::get(Type::Int8Ty, params, false);
</pre>
</div>
+<!-- *********************************************************************** -->
+<div class="doc_section">
+ <a name="threading">Threads and LLVM</a>
+</div>
+<!-- *********************************************************************** -->
+
+<div class="doc_text">
+<p>
+This section describes the interaction of the LLVM APIs with multithreading,
+both on the part of client applications, and in the JIT, in the hosted
+application.
+</p>
+
+<p>
+Note that LLVM's support for multithreading is still relatively young. Up
+through version 2.5, the execution of threaded hosted applications was
+supported, but not threaded client access to the APIs. While this use case is
+now supported, clients <em>must</em> adhere to the guidelines specified below to
+ensure proper operation in multithreaded mode.
+</p>
+
+<p>
+Note that, on Unix-like platforms, LLVM requires the presence of GCC's atomic
+intrinsics in order to support threaded operation. If you need a
+multhreading-capable LLVM on a platform without a suitably modern system
+compiler, consider compiling LLVM and LLVM-GCC in single-threaded mode, and
+using the resultant compiler to build a copy of LLVM with multithreading
+support.
+</p>
+</div>
+
+<!-- ======================================================================= -->
+<div class="doc_subsection">
+ <a name="startmultithreaded">Entering and Exiting Multithreaded Mode</a>
+</div>
+
+<div class="doc_text">
+
+<p>
+In order to properly protect its internal data structures while avoiding
+excessive locking overhead in the single-threaded case, the LLVM must intialize
+certain data structures necessary to provide guards around its internals. To do
+so, the client program must invoke <tt>llvm_start_multithreaded()</tt> before
+making any concurrent LLVM API calls. To subsequently tear down these
+structures, use the <tt>llvm_stop_multithreaded()</tt> call. You can also use
+the <tt>llvm_is_multithreaded()</tt> call to check the status of multithreaded
+mode.
+</p>
+
+<p>
+Note that both of these calls must be made <em>in isolation</em>. That is to
+say that no other LLVM API calls may be executing at any time during the
+execution of <tt>llvm_start_multithreaded()</tt> or <tt>llvm_stop_multithreaded
+</tt>. It's is the client's responsibility to enforce this isolation.
+</p>
+
+<p>
+The return value of <tt>llvm_start_multithreaded()</tt> indicates the success or
+failure of the initialization. Failure typically indicates that your copy of
+LLVM was built without multithreading support, typically because GCC atomic
+intrinsics were not found in your system compiler. In this case, the LLVM API
+will not be safe for concurrent calls. However, it <em>will</em> be safe for
+hosting threaded applications in the JIT, though care must be taken to ensure
+that side exits and the like do not accidentally result in concurrent LLVM API
+calls.
+</p>
+</div>
+
+<!-- ======================================================================= -->
+<div class="doc_subsection">
+ <a name="shutdown">Ending Execution with <tt>llvm_shutdown()</tt></a>
+</div>
+
+<div class="doc_text">
+<p>
+When you are done using the LLVM APIs, you should call <tt>llvm_shutdown()</tt>
+to deallocate memory used for internal structures. This will also invoke
+<tt>llvm_stop_multithreaded()</tt> if LLVM is operating in multithreaded mode.
+As such, <tt>llvm_shutdown()</tt> requires the same isolation guarantees as
+<tt>llvm_stop_multithreaded()</tt>.
+</p>
+
+<p>
+Note that, if you use scope-based shutdown, you can use the
+<tt>llvm_shutdown_obj</tt> class, which calls <tt>llvm_shutdown()</tt> in its
+destructor.
+</div>
+
+<!-- ======================================================================= -->
+<div class="doc_subsection">
+ <a name="managedstatic">Lazy Initialization with <tt>ManagedStatic</tt></a>
+</div>
+
+<div class="doc_text">
+<p>
+<tt>ManagedStatic</tt> is a utility class in LLVM used to implement static
+initialization of static resources, such as the global type tables. Before the
+invocation of <tt>llvm_shutdown()</tt>, it implements a simple lazy
+initialization scheme. Once <tt>llvm_start_multithreaded()</tt> returns,
+however, it uses double-checked locking to implement thread-safe lazy
+initialization.
+</p>
+
+<p>
+Note that, because no other threads are allowed to issue LLVM API calls before
+<tt>llvm_start_multithreaded()</tt> returns, it is possible to have
+<tt>ManagedStatic</tt>s of <tt>llvm::sys::Mutex</tt>s.
+</p>
+
+<p>
+The <tt>llvm_acquire_global_lock()</tt> and <tt>llvm_release_global_lock</tt>
+APIs provide access to the global lock used to implement the double-checked
+locking for lazy initialization. These should only be used internally to LLVM,
+and only if you know what you're doing!
+</p>
+</div>
+
<!-- *********************************************************************** -->
<div class="doc_section">
<a name="advanced">Advanced Topics</a>
<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
+doxygen info: <a href="/doxygen/classllvm_1_1BasicBlock.html">BasicBlock
Class</a><br>
Superclass: <a href="#Value"><tt>Value</tt></a></p>
projects / oota-llvm.git / blobdiff