when defining a function which should be able to efficiently accept concatenated
strings.
+.. _function_apis:
+
+Passing functions and other callable objects
+--------------------------------------------
+
+Sometimes you may want a function to be passed a callback object. In order to
+support lambda expressions and other function objects, you should not use the
+traditional C approach of taking a function pointer and an opaque cookie:
+
+.. code-block:: c++
+
+ void takeCallback(bool (*Callback)(Function *, void *), void *Cookie);
+
+Instead, use one of the following approaches:
+
+Function template
+^^^^^^^^^^^^^^^^^
+
+If you don't mind putting the definition of your function into a header file,
+make it a function template that is templated on the callable type.
+
+.. code-block:: c++
+
+ template<typename Callable>
+ void takeCallback(Callable Callback) {
+ Callback(1, 2, 3);
+ }
+
+The ``function_ref`` class template
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The ``function_ref``
+(`doxygen <http://llvm.org/doxygen/classllvm_1_1function_ref.html>`__) class
+template represents a reference to a callable object, templated over the type
+of the callable. This is a good choice for passing a callback to a function,
+if you don't need to hold onto the callback after the function returns. In this
+way, ``function_ref`` is to ``std::function`` as ``StringRef`` is to
+``std::string``.
+
+``function_ref<Ret(Param1, Param2, ...)>`` can be implicitly constructed from
+any callable object that can be called with arguments of type ``Param1``,
+``Param2``, ..., and returns a value that can be converted to type ``Ret``.
+For example:
+
+.. code-block:: c++
+
+ void visitBasicBlocks(Function *F, function_ref<bool (BasicBlock*)> Callback) {
+ for (BasicBlock &BB : *F)
+ if (Callback(&BB))
+ return;
+ }
+
+can be called using:
+
+.. code-block:: c++
+
+ visitBasicBlocks(F, [&](BasicBlock *BB) {
+ if (process(BB))
+ return isEmpty(BB);
+ return false;
+ });
+
+Note that a ``function_ref`` object contains pointers to external memory, so it
+is not generally safe to store an instance of the class (unless you know that
+the external storage will not be freed). If you need this ability, consider
+using ``std::function``. ``function_ref`` is small enough that it should always
+be passed by value.
+
.. _DEBUG:
The ``DEBUG()`` macro and ``-debug`` option
Sometimes you may find yourself in a situation where enabling ``-debug`` just
turns on **too much** information (such as when working on the code generator).
If you want to enable debug information with more fine-grained control, you
-define the ``DEBUG_TYPE`` macro and the ``-debug`` only option as follows:
+can define the ``DEBUG_TYPE`` macro and use the ``-debug-only`` option as
+follows:
.. code-block:: c++
DAG.viewGraph()`` to pop up a window. Alternatively, you can sprinkle calls to
these functions in your code in places you want to debug.
-Getting this to work requires a small amount of configuration. On Unix systems
+Getting this to work requires a small amount of setup. On Unix systems
with X11, install the `graphviz <http://www.graphviz.org>`_ 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 `Graphviz program
+sure 'dot' and 'gv' are in your path. If you are running on Mac OS X, download
+and install the Mac OS X `Graphviz program
<http://www.pixelglow.com/graphviz/>`_ and add
``/Applications/Graphviz.app/Contents/MacOS/`` (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.
+your path. The programs need not be present when configuring, building or
+running LLVM and can simply be installed when needed during an active debug
+session.
``SelectionDAG`` has been extended to make it easier to locate *interesting*
nodes in large complex graphs. From gdb, if you ``call DAG.setGraphColor(node,
.. note::
- Prefer to use ``SmallVectorImpl<T>`` in interfaces.
+ Prefer to use ``SmallVectorImpl<T>`` as a parameter type.
In APIs that don't care about the "small size" (most?), prefer to use
the ``SmallVectorImpl<T>`` class, which is basically just the "vector
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.
+efficiently queried with a standard binary search (e.g.
+``std::lower_bound``; if you want the whole range of elements comparing
+equal, use ``std::equal_range``).
.. _dss_smallset:
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
+elements out of (linear time), unless you use its "pop_back" method, which is
faster.
``SetVector`` is an adapter class that defaults to using ``std::vector`` and a
.. _dss_valuemap:
-llvm/ADT/ValueMap.h
+llvm/IR/ValueMap.h
^^^^^^^^^^^^^^^^^^^
ValueMap is a wrapper around a :ref:`DenseMap <dss_densemap>` mapping
iteration over maps of pointers.
It is implemented by mapping from key to an index in a vector of key,value
-pairs. This provides fast lookup and iteration, but has two main drawbacks: The
-key is stored twice and it doesn't support removing elements.
+pairs. This provides fast lookup and iteration, but has two main drawbacks:
+the key is stored twice and removing elements takes linear time. If it is
+necessary to remove elements, it's best to remove them in bulk using
+``remove_if()``.
.. _dss_inteqclasses:
If you're finding that you commonly iterate over a ``Function``'s
``BasicBlock``\ s and then that ``BasicBlock``'s ``Instruction``\ s,
``InstIterator`` should be used instead. You'll need to include
-``llvm/Support/InstIterator.h`` (`doxygen
-<http://llvm.org/doxygen/InstIterator_8h-source.html>`__) and then instantiate
+``llvm/IR/InstIterator.h`` (`doxygen
+<http://llvm.org/doxygen/InstIterator_8h.html>`__) and then instantiate
``InstIterator``\ 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:
.. code-block:: c++
- #include "llvm/Support/InstIterator.h"
+ #include "llvm/IR/InstIterator.h"
// F is a pointer to a Function instance
for (inst_iterator I = inst_begin(F), E = inst_end(F); I != E; ++I)
Function *F = ...;
- for (Value::use_iterator i = F->use_begin(), e = F->use_end(); i != e; ++i)
- if (Instruction *Inst = dyn_cast<Instruction>(*i)) {
+ for (User *U : GV->users()) {
+ if (Instruction *Inst = dyn_cast<Instruction>(U)) {
errs() << "F is used in instruction:\n";
errs() << *Inst << "\n";
}
-Note that dereferencing a ``Value::use_iterator`` is not a very cheap operation.
-Instead of performing ``*i`` above several times, consider doing it only once in
-the loop body and reusing its result.
-
Alternatively, it's common to have an instance of the ``User`` Class (`doxygen
<http://llvm.org/doxygen/classllvm_1_1User.html>`__) and need to know what
``Value``\ s are used by it. The list of all ``Value``\ s used by a ``User`` is
Instruction *pi = ...;
- for (User::op_iterator i = pi->op_begin(), e = pi->op_end(); i != e; ++i) {
- Value *v = *i;
+ for (Use &U : pi->operands()) {
+ Value *v = U.get();
// ...
}
*Inserting instructions*
-There are essentially two ways to insert an ``Instruction`` into an existing
+There are essentially three ways to insert an ``Instruction`` into an existing
sequence of instructions that form a ``BasicBlock``:
* Insertion into an explicit instruction list
which is much cleaner, especially if you're creating a lot of instructions and
adding them to ``BasicBlock``\ s.
+* Insertion using an instance of ``IRBuilder``
+
+ Inserting several ``Instruction``\ s can be quite laborious using the previous
+ methods. The ``IRBuilder`` is a convenience class that can be used to add
+ several instructions to the end of a ``BasicBlock`` or before a particular
+ ``Instruction``. It also supports constant folding and renaming named
+ registers (see ``IRBuilder``'s template arguments).
+
+ The example below demonstrates a very simple use of the ``IRBuilder`` where
+ three instructions are inserted before the instruction ``pi``. The first two
+ instructions are Call instructions and third instruction multiplies the return
+ value of the two calls.
+
+ .. code-block:: c++
+
+ Instruction *pi = ...;
+ IRBuilder<> Builder(pi);
+ CallInst* callOne = Builder.CreateCall(...);
+ CallInst* callTwo = Builder.CreateCall(...);
+ Value* result = Builder.CreateMul(callOne, callTwo);
+
+ The example below is similar to the above example except that the created
+ ``IRBuilder`` inserts instructions at the end of the ``BasicBlock`` ``pb``.
+
+ .. code-block:: c++
+
+ BasicBlock *pb = ...;
+ IRBuilder<> Builder(pb);
+ CallInst* callOne = Builder.CreateCall(...);
+ CallInst* callTwo = Builder.CreateCall(...);
+ Value* result = Builder.CreateMul(callOne, callTwo);
+
+ See :doc:`tutorial/LangImpl3` for a practical use of the ``IRBuilder``.
+
+
.. _schanges_deleting:
Deleting Instructions
using the resultant compiler to build a copy of LLVM with multithreading
support.
-.. _startmultithreaded:
-
-Entering and Exiting Multithreaded Mode
----------------------------------------
-
-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 ``llvm_start_multithreaded()`` before making
-any concurrent LLVM API calls. To subsequently tear down these structures, use
-the ``llvm_stop_multithreaded()`` call. You can also use the
-``llvm_is_multithreaded()`` call to check the status of multithreaded mode.
-
-Note that both of these calls must be made *in isolation*. That is to say that
-no other LLVM API calls may be executing at any time during the execution of
-``llvm_start_multithreaded()`` or ``llvm_stop_multithreaded``. It's is the
-client's responsibility to enforce this isolation.
-
-The return value of ``llvm_start_multithreaded()`` 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 *will* be safe for hosting
-threaded applications in the JIT, though :ref:`care must be taken
-<jitthreading>` to ensure that side exits and the like do not accidentally
-result in concurrent LLVM API calls.
-
.. _shutdown:
Ending Execution with ``llvm_shutdown()``
-----------------------------------------
When you are done using the LLVM APIs, you should call ``llvm_shutdown()`` to
-deallocate memory used for internal structures. This will also invoke
-``llvm_stop_multithreaded()`` if LLVM is operating in multithreaded mode. As
-such, ``llvm_shutdown()`` requires the same isolation guarantees as
-``llvm_stop_multithreaded()``.
-
-Note that, if you use scope-based shutdown, you can use the
-``llvm_shutdown_obj`` class, which calls ``llvm_shutdown()`` in its destructor.
+deallocate memory used for internal structures.
.. _managedstatic:
------------------------------------------
``ManagedStatic`` is a utility class in LLVM used to implement static
-initialization of static resources, such as the global type tables. Before the
-invocation of ``llvm_shutdown()``, it implements a simple lazy initialization
-scheme. Once ``llvm_start_multithreaded()`` returns, however, it uses
+initialization of static resources, such as the global type tables. In a
+single-threaded environment, it implements a simple lazy initialization scheme.
+When LLVM is compiled with support for multi-threading, however, it uses
double-checked locking to implement thread-safe lazy initialization.
-Note that, because no other threads are allowed to issue LLVM API calls before
-``llvm_start_multithreaded()`` returns, it is possible to have
-``ManagedStatic``\ s of ``llvm::sys::Mutex``\ s.
-
-The ``llvm_acquire_global_lock()`` and ``llvm_release_global_lock`` 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!
-
.. _llvmcontext:
Achieving Isolation with ``LLVMContext``
The Core LLVM Class Hierarchy Reference
=======================================
-``#include "llvm/Type.h"``
+``#include "llvm/IR/Type.h"``
header source: `Type.h <http://llvm.org/doxygen/Type_8h-source.html>`_
The ``Module`` class
--------------------
-``#include "llvm/Module.h"``
+``#include "llvm/IR/Module.h"``
header source: `Module.h <http://llvm.org/doxygen/Module_8h-source.html>`_
The ``Value`` class
-------------------
-``#include "llvm/Value.h"``
+``#include "llvm/IR/Value.h"``
header source: `Value.h <http://llvm.org/doxygen/Value_8h-source.html>`_
The ``User`` class
------------------
-``#include "llvm/User.h"``
+``#include "llvm/IR/User.h"``
header source: `User.h <http://llvm.org/doxygen/User_8h-source.html>`_
The ``Instruction`` class
-------------------------
-``#include "llvm/Instruction.h"``
+``#include "llvm/IR/Instruction.h"``
header source: `Instruction.h
<http://llvm.org/doxygen/Instruction_8h-source.html>`_
The ``GlobalValue`` class
-------------------------
-``#include "llvm/GlobalValue.h"``
+``#include "llvm/IR/GlobalValue.h"``
header source: `GlobalValue.h
<http://llvm.org/doxygen/GlobalValue_8h-source.html>`_
The ``Function`` class
----------------------
-``#include "llvm/Function.h"``
+``#include "llvm/IR/Function.h"``
header source: `Function.h <http://llvm.org/doxygen/Function_8h-source.html>`_
The ``GlobalVariable`` class
----------------------------
-``#include "llvm/GlobalVariable.h"``
+``#include "llvm/IR/GlobalVariable.h"``
header source: `GlobalVariable.h
<http://llvm.org/doxygen/GlobalVariable_8h-source.html>`_
The ``BasicBlock`` class
------------------------
-``#include "llvm/BasicBlock.h"``
+``#include "llvm/IR/BasicBlock.h"``
header source: `BasicBlock.h
<http://llvm.org/doxygen/BasicBlock_8h-source.html>`_
projects / oota-llvm.git / blobdiff