SLPVectorizer: change the order in which we search for vectorization candidates....

[oota-llvm.git] / docs / ProgrammersManual.rst

diff --git a/docs/ProgrammersManual.rst b/docs/ProgrammersManual.rst
index 4fc459793301c7aaadfd1a1357810e6698009bc6..2910a2aa1c1990fa05c42992008554d142a327ed 100644 (file)
--- a/docs/ProgrammersManual.rst
+++ b/docs/ProgrammersManual.rst
@@ -626,6 +626,33 @@ SmallVectors are most useful when on the stack.
 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>
@@ -989,7 +1016,9 @@ coupled with a good choice of :ref:`sequential container <ds_sequential>`.
 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:
 
@@ -2392,7 +2421,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 <http://llvm.org/doxygen/Type_8h-source.html>`_
 
@@ -2495,7 +2524,7 @@ Important Derived Types
 The ``Module`` class
 --------------------
 
-``#include "llvm/Module.h"``
+``#include "llvm/IR/Module.h"``
 
 header source: `Module.h <http://llvm.org/doxygen/Module_8h-source.html>`_
 
@@ -2582,7 +2611,7 @@ Important Public Members of the ``Module`` class
 The ``Value`` class
 -------------------
 
-``#include "llvm/Value.h"``
+``#include "llvm/IR/Value.h"``
 
 header source: `Value.h <http://llvm.org/doxygen/Value_8h-source.html>`_
 
@@ -2673,7 +2702,7 @@ Important Public Members of the ``Value`` class
 The ``User`` class
 ------------------
 
-``#include "llvm/User.h"``
+``#include "llvm/IR/User.h"``
 
 header source: `User.h <http://llvm.org/doxygen/User_8h-source.html>`_
 
@@ -2719,7 +2748,7 @@ interface and through an iterator based interface.
 The ``Instruction`` class
 -------------------------
 
-``#include "llvm/Instruction.h"``
+``#include "llvm/IR/Instruction.h"``
 
 header source: `Instruction.h
 <http://llvm.org/doxygen/Instruction_8h-source.html>`_
@@ -2867,7 +2896,7 @@ Important Subclasses of Constant
 The ``GlobalValue`` class
 -------------------------
 
-``#include "llvm/GlobalValue.h"``
+``#include "llvm/IR/GlobalValue.h"``
 
 header source: `GlobalValue.h
 <http://llvm.org/doxygen/GlobalValue_8h-source.html>`_
@@ -2926,7 +2955,7 @@ Important Public Members of the ``GlobalValue`` class
 The ``Function`` class
 ----------------------
 
-``#include "llvm/Function.h"``
+``#include "llvm/IR/Function.h"``
 
 header source: `Function.h <http://llvm.org/doxygen/Function_8h-source.html>`_
 
@@ -3034,7 +3063,7 @@ Important Public Members of the ``Function``
 The ``GlobalVariable`` class
 ----------------------------
 
-``#include "llvm/GlobalVariable.h"``
+``#include "llvm/IR/GlobalVariable.h"``
 
 header source: `GlobalVariable.h
 <http://llvm.org/doxygen/GlobalVariable_8h-source.html>`_
@@ -3092,7 +3121,7 @@ Important Public Members of the ``GlobalVariable`` class
 The ``BasicBlock`` class
 ------------------------
 
-``#include "llvm/BasicBlock.h"``
+``#include "llvm/IR/BasicBlock.h"``
 
 header source: `BasicBlock.h
 <http://llvm.org/doxygen/BasicBlock_8h-source.html>`_