[llvm] r338071 - ADT: Document advantages of SmallVector<T, 0> over std::vector
Duncan P. N. Exon Smith via llvm-commits
llvm-commits at lists.llvm.org
Thu Jul 26 14:29:54 PDT 2018
Author: dexonsmith
Date: Thu Jul 26 14:29:54 2018
New Revision: 338071
URL: http://llvm.org/viewvc/llvm-project?rev=338071&view=rev
Log:
ADT: Document advantages of SmallVector<T,0> over std::vector
In light of the recent changes to SmallVector in r335421, r337514, and
r337820, document its advantages over std::vector (see r175906 and
r266909).
Also add a release note.
https://reviews.llvm.org/D49748
Modified:
llvm/trunk/docs/ProgrammersManual.rst
llvm/trunk/docs/ReleaseNotes.rst
Modified: llvm/trunk/docs/ProgrammersManual.rst
URL: http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/ProgrammersManual.rst?rev=338071&r1=338070&r2=338071&view=diff
==============================================================================
--- llvm/trunk/docs/ProgrammersManual.rst (original)
+++ llvm/trunk/docs/ProgrammersManual.rst Thu Jul 26 14:29:54 2018
@@ -1435,7 +1435,7 @@ order (so you can do pointer arithmetic
push_back/pop_back operations, supports efficient random access to its elements,
etc.
-The advantage of SmallVector is that it allocates space for some number of
+The main advantage of SmallVector is that it allocates space for some number of
elements (N) **in the object itself**. Because of this, if the SmallVector is
dynamically smaller than N, no malloc is performed. This can be a big win in
cases where the malloc/free call is far more expensive than the code that
@@ -1450,6 +1450,21 @@ SmallVectors are most useful when on the
SmallVector also provides a nice portable and efficient replacement for
``alloca``.
+SmallVector has grown a few other minor advantages over std::vector, causing
+``SmallVector<Type, 0>`` to be preferred over ``std::vector<Type>``.
+
+#. std::vector is exception-safe, and some implementations have pessimizations
+ that copy elements when SmallVector would move them.
+
+#. SmallVector understands ``isPodLike<Type>`` and uses realloc aggressively.
+
+#. Many LLVM APIs take a SmallVectorImpl as an out parameter (see the note
+ below).
+
+#. SmallVector with N equal to 0 is smaller than std::vector on 64-bit
+ platforms, since it uses ``unsigned`` (instead of ``void*``) for its size
+ and capacity.
+
.. note::
Prefer to use ``SmallVectorImpl<T>`` as a parameter type.
@@ -1482,12 +1497,10 @@ SmallVector also provides a nice portabl
<vector>
^^^^^^^^
-``std::vector`` is well loved and respected. It is useful when SmallVector
-isn't: when the size of the vector is often large (thus the small optimization
-will rarely be a benefit) or if you will be allocating many instances of the
-vector itself (which would waste space for elements that aren't in the
-container). vector is also useful when interfacing with code that expects
-vectors :).
+``std::vector<T>`` is well loved and respected. However, ``SmallVector<T, 0>``
+is often a better option due to the advantages listed above. std::vector is
+still useful when you need to store more than ``UINT32_MAX`` elements or when
+interfacing with code that expects vectors :).
One worthwhile note about std::vector: avoid code like this:
Modified: llvm/trunk/docs/ReleaseNotes.rst
URL: http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/ReleaseNotes.rst?rev=338071&r1=338070&r2=338071&view=diff
==============================================================================
--- llvm/trunk/docs/ReleaseNotes.rst (original)
+++ llvm/trunk/docs/ReleaseNotes.rst Thu Jul 26 14:29:54 2018
@@ -101,6 +101,14 @@ Non-comprehensive list of changes in thi
* Early support for UBsan, X-Ray instrumentation and libFuzzer (x86 and x86_64) for OpenBSD. Support for MSan
(x86_64), X-Ray instrumentation and libFuzzer (x86 and x86_64) for FreeBSD.
+* ``SmallVector<T, 0>`` shrank from ``sizeof(void*) * 4 + sizeof(T)`` to
+ ``sizeof(void*) + sizeof(unsigned) * 2``, smaller than ``std::vector<T>`` on
+ 64-bit platforms. The maximum capacity is now restricted to ``UINT32_MAX``.
+ Since SmallVector doesn't have the exception-safety pessimizations some
+ implementations saddle std::vector with and is better at using ``realloc``,
+ it's now a better choice even on the heap (although when TinyPtrVector works,
+ it's even smaller).
+
* Note..
.. NOTE
More information about the llvm-commits
mailing list