X-Git-Url: http://plrg.eecs.uci.edu/git/?a=blobdiff_plain;f=docs%2FProgrammersManual.rst;h=46ec15f93a3236a65079e88254eb4f21704bee71;hb=362510890ff2e1838450bb6ab91ef4e465c1d3a8;hp=7864165617a038838af96b3a827a7a1ba52c63d4;hpb=4991289b33f04f308bf5495a51518f850aa31cfa;p=oota-llvm.git diff --git a/docs/ProgrammersManual.rst b/docs/ProgrammersManual.rst index 7864165617a..46ec15f93a3 100644 --- a/docs/ProgrammersManual.rst +++ b/docs/ProgrammersManual.rst @@ -263,6 +263,74 @@ 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. In this +way, ``function_ref`` is to ``std::function`` as ``StringRef`` is to +``std::string``. + +``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). 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 @@ -315,7 +383,8 @@ Fine grained debug info with ``DEBUG_TYPE`` and the ``-debug-only`` 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++ @@ -473,14 +542,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 +1242,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 +1388,7 @@ type used. .. _dss_valuemap: -llvm/ADT/ValueMap.h +llvm/IR/ValueMap.h ^^^^^^^^^^^^^^^^^^^ ValueMap is a wrapper around a :ref:`DenseMap ` mapping @@ -1367,8 +1437,10 @@ order, making it an easy (but somewhat expensive) solution for non-deterministic 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: @@ -1559,14 +1631,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 +1810,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 +1827,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(); // ... } @@ -1848,7 +1916,7 @@ which is a pointer to an integer on the run time stack. *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 @@ -1918,6 +1986,41 @@ sequence of instructions that form a ``BasicBlock``: 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 @@ -2065,46 +2168,13 @@ 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. -.. _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 -` 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: @@ -2112,20 +2182,11 @@ Lazy Initialization with ``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`` @@ -2421,7 +2482,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 +2585,7 @@ Important Derived Types The ``Module`` class -------------------- -``#include "llvm/Module.h"`` +``#include "llvm/IR/Module.h"`` header source: `Module.h `_ @@ -2611,7 +2672,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 +2763,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 +2809,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 +2957,7 @@ Important Subclasses of Constant The ``GlobalValue`` class ------------------------- -``#include "llvm/GlobalValue.h"`` +``#include "llvm/IR/GlobalValue.h"`` header source: `GlobalValue.h `_ @@ -2955,7 +3016,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 +3124,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 +3182,7 @@ Important Public Members of the ``GlobalVariable`` class The ``BasicBlock`` class ------------------------ -``#include "llvm/BasicBlock.h"`` +``#include "llvm/IR/BasicBlock.h"`` header source: `BasicBlock.h `_