:local:
.. warning::
- This is a work in progress.
-
-.. sectionauthor:: Chris Lattner <sabre@nondot.org>,
- Dinakar Dhurjati <dhurjati@cs.uiuc.edu>,
- Gabor Greif <ggreif@gmail.com>,
- Joel Stanley <jstanley@cs.uiuc.edu>,
- Reid Spencer <rspencer@x10sys.com> and
- Owen Anderson <owen@apple.com>
+ This is always a work in progress.
.. _introduction:
Here are some useful links:
-#. `Dinkumware C++ Library reference
- <http://www.dinkumware.com/manuals/#Standard C++ Library>`_ - an excellent
+#. `cppreference.com
+ <http://en.cppreference.com/w/>`_ - an excellent
reference for the STL and other parts of the standard C++ library.
#. `C++ In a Nutshell <http://www.tempest-sw.com/cpp/>`_ - This is an O'Reilly
<http://www.research.att.com/%7Ebs/C++.html>`_.
#. `Bruce Eckel's Thinking in C++, 2nd ed. Volume 2 Revision 4.0
- (even better, get the book) <http://64.78.49.204/>`_.
+ (even better, get the book)
+ <http://www.mindview.net/Books/TICPP/ThinkingInCPP2e.html>`_.
-You are also encouraged to take a look at the :ref:`LLVM Coding Standards
-<coding_standards>` guide which focuses on how to write maintainable code more
+You are also encouraged to take a look at the :doc:`LLVM Coding Standards
+<CodingStandards>` guide which focuses on how to write maintainable code more
than where to put your curly braces.
.. _resources:
These five templates can be used with any classes, whether they have a v-table
or not. If you want to add support for these templates, see the document
-:ref:`How to set up LLVM-style RTTI for your class hierarchy
-<how-to-set-up-llvm-style-rtti>`
+:doc:`How to set up LLVM-style RTTI for your class hierarchy
+<HowToSetUpLLVMStyleRTTI>`
.. _string_apis:
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,
SmallVector also provides a nice portable and efficient replacement for
``alloca``.
+.. note::
+
+ 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
+ header" (and methods) without the elements allocated after it. Note that
+ ``SmallVector<T, N>`` inherits from ``SmallVectorImpl<T>`` so the
+ conversion is implicit and costs nothing. E.g.
+
+ .. code-block:: c++
+
+ // BAD: Clients cannot pass e.g. SmallVector<Foo, 4>.
+ hardcodedSmallSize(SmallVector<Foo, 2> &Out);
+ // GOOD: Clients can pass any SmallVector<Foo, N>.
+ allowsAnySmallSize(SmallVectorImpl<Foo> &Out);
+
+ void someFunc() {
+ SmallVector<Foo, 8> Vec;
+ hardcodedSmallSize(Vec); // Error.
+ allowsAnySmallSize(Vec); // Works.
+ }
+
+ Even though it has "``Impl``" in the name, this is so widely used that
+ it really isn't "private to the implementation" anymore. A name like
+ ``SmallVectorHeader`` would be more appropriate.
+
.. _dss_vector:
<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:
and fast iteration over small sets. It is not intended for building composite
data structures.
+.. _dss_sparsemultiset:
+
+llvm/ADT/SparseMultiSet.h
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+SparseMultiSet adds multiset behavior to SparseSet, while retaining SparseSet's
+desirable attributes. Like SparseSet, it typically uses a lot of memory, but
+provides operations that are almost as fast as a vector. Typical keys are
+physical registers, virtual registers, or numbered basic blocks.
+
+SparseMultiSet is useful for algorithms that need very fast
+clear/find/insert/erase of the entire collection, and iteration over sets of
+elements sharing a key. It is often a more efficient choice than using composite
+data structures (e.g. vector-of-vectors, map-of-vectors). It is not intended for
+building composite data structures.
+
.. _dss_FoldingSet:
llvm/ADT/FoldingSet.h
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
A bit-encoding in the 2 LSBits (least significant bits) of the ``Use::Prev``
allows to find the start of the ``User`` object:
-* ``00`` –> binary digit 0
+* ``00`` --- binary digit 0
-* ``01`` –> binary digit 1
+* ``01`` --- binary digit 1
-* ``10`` –> stop and calculate (``s``)
+* ``10`` --- stop and calculate (``s``)
-* ``11`` –> full stop (``S``)
+* ``11`` --- full stop (``S``)
Given a ``Use*``, all we have to do is to walk till we get a stop and we either
have a ``User`` immediately behind or we have to walk to the next stop picking
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>`_