From: Duncan P. N. Exon Smith Date: Thu, 26 Jul 2018 21:29:54 +0000 (+0000) Subject: ADT: Document advantages of SmallVector over std::vector X-Git-Tag: llvmorg-7.0.0-rc1~477 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=0f81faed05c3c7c1fbaf6af402411c99d715cf56;p=platform%2Fupstream%2Fllvm.git ADT: Document advantages of SmallVector 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 llvm-svn: 338071 --- diff --git a/llvm/docs/ProgrammersManual.rst b/llvm/docs/ProgrammersManual.rst index 198225d..d801618 100644 --- a/llvm/docs/ProgrammersManual.rst +++ b/llvm/docs/ProgrammersManual.rst @@ -1435,7 +1435,7 @@ order (so you can do pointer arithmetic between elements), supports efficient 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 stack. SmallVector also provides a nice portable and efficient replacement for ``alloca``. +SmallVector has grown a few other minor advantages over std::vector, causing +``SmallVector`` to be preferred over ``std::vector``. + +#. std::vector is exception-safe, and some implementations have pessimizations + that copy elements when SmallVector would move them. + +#. SmallVector understands ``isPodLike`` 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`` as a parameter type. @@ -1482,12 +1497,10 @@ SmallVector also provides a nice portable and efficient replacement for ^^^^^^^^ -``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`` is well loved and respected. However, ``SmallVector`` +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: diff --git a/llvm/docs/ReleaseNotes.rst b/llvm/docs/ReleaseNotes.rst index ad8b447..a6942c0 100644 --- a/llvm/docs/ReleaseNotes.rst +++ b/llvm/docs/ReleaseNotes.rst @@ -101,6 +101,14 @@ Non-comprehensive list of changes in this release * 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`` shrank from ``sizeof(void*) * 4 + sizeof(T)`` to + ``sizeof(void*) + sizeof(unsigned) * 2``, smaller than ``std::vector`` 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