X-Git-Url: http://demsky.eecs.uci.edu/git/?a=blobdiff_plain;f=docs%2FProgrammersManual.rst;h=8d9668e4eec7d3da9eca784435b75602dc77df25;hb=04de60e28f29613ea762fc7221197f7a2c4ade80;hp=7864165617a038838af96b3a827a7a1ba52c63d4;hpb=4991289b33f04f308bf5495a51518f850aa31cfa;p=oota-llvm.git diff --git a/docs/ProgrammersManual.rst b/docs/ProgrammersManual.rst index 7864165617a..8d9668e4eec 100644 --- a/docs/ProgrammersManual.rst +++ b/docs/ProgrammersManual.rst @@ -263,6 +263,78 @@ 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. +.. _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 + void takeCallback(Callable Callback) { + Callback(1, 2, 3); + } + +The ``function_ref`` class template +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The ``function_ref`` +(`doxygen `__) 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`` 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 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 @@ -473,14 +545,15 @@ methods. Within GDB, for example, you can usually use something like ``call 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 `_ 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 `_ 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, @@ -1172,7 +1245,7 @@ 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 +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 @@ -1318,7 +1391,7 @@ type used. .. _dss_valuemap: -llvm/ADT/ValueMap.h +llvm/IR/ValueMap.h ^^^^^^^^^^^^^^^^^^^ ValueMap is a wrapper around a :ref:`DenseMap ` mapping @@ -1559,14 +1632,14 @@ Iterating over the ``Instruction`` in a ``Function`` 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 -`__) and then instantiate +``llvm/IR/InstIterator.h`` (`doxygen +`__) 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) @@ -1738,16 +1811,12 @@ chain of ``F``: Function *F = ...; - for (Value::use_iterator i = F->use_begin(), e = F->use_end(); i != e; ++i) - if (Instruction *Inst = dyn_cast(*i)) { + for (User *U : GV->users()) { + if (Instruction *Inst = dyn_cast(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 `__) and need to know what ``Value``\ s are used by it. The list of all ``Value``\ s used by a ``User`` is @@ -1759,8 +1828,8 @@ instruction uses (that is, the operands of the particular ``Instruction``): 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(); // ... } @@ -2080,7 +2149,7 @@ the ``llvm_stop_multithreaded()`` call. You can also use the 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 @@ -2421,7 +2490,7 @@ place the ``vptr`` in the first word of the instances.) The Core LLVM Class Hierarchy Reference ======================================= -``#include "llvm/Type.h"`` +``#include "llvm/IR/Type.h"`` header source: `Type.h `_ @@ -2524,7 +2593,7 @@ Important Derived Types The ``Module`` class -------------------- -``#include "llvm/Module.h"`` +``#include "llvm/IR/Module.h"`` header source: `Module.h `_ @@ -2611,7 +2680,7 @@ Important Public Members of the ``Module`` class The ``Value`` class ------------------- -``#include "llvm/Value.h"`` +``#include "llvm/IR/Value.h"`` header source: `Value.h `_ @@ -2702,7 +2771,7 @@ Important Public Members of the ``Value`` class The ``User`` class ------------------ -``#include "llvm/User.h"`` +``#include "llvm/IR/User.h"`` header source: `User.h `_ @@ -2748,7 +2817,7 @@ interface and through an iterator based interface. The ``Instruction`` class ------------------------- -``#include "llvm/Instruction.h"`` +``#include "llvm/IR/Instruction.h"`` header source: `Instruction.h `_ @@ -2896,7 +2965,7 @@ Important Subclasses of Constant The ``GlobalValue`` class ------------------------- -``#include "llvm/GlobalValue.h"`` +``#include "llvm/IR/GlobalValue.h"`` header source: `GlobalValue.h `_ @@ -2955,7 +3024,7 @@ Important Public Members of the ``GlobalValue`` class The ``Function`` class ---------------------- -``#include "llvm/Function.h"`` +``#include "llvm/IR/Function.h"`` header source: `Function.h `_ @@ -3063,7 +3132,7 @@ Important Public Members of the ``Function`` The ``GlobalVariable`` class ---------------------------- -``#include "llvm/GlobalVariable.h"`` +``#include "llvm/IR/GlobalVariable.h"`` header source: `GlobalVariable.h `_ @@ -3121,7 +3190,7 @@ Important Public Members of the ``GlobalVariable`` class The ``BasicBlock`` class ------------------------ -``#include "llvm/BasicBlock.h"`` +``#include "llvm/IR/BasicBlock.h"`` header source: `BasicBlock.h `_