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.
+
+``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).
+``function_ref`` is small enough that it should always be passed by value.
+
+``std::function``
+^^^^^^^^^^^^^^^^^
+
+You cannot use ``std::function`` within LLVM code, because it is not supported
+by all our target toolchains.
+
+
.. _DEBUG:
The ``DEBUG()`` macro and ``-debug`` option
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,
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
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();
// ...
}
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
+``llvm_start_multithreaded()`` or ``llvm_stop_multithreaded``. It is the
client's responsibility to enforce this isolation.
The return value of ``llvm_start_multithreaded()`` indicates the success or
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