diff options
| -rw-r--r-- | llvm/docs/ProgrammersManual.rst | 27 | ||||
| -rw-r--r-- | llvm/docs/ReleaseNotes.rst | 8 |
2 files changed, 28 insertions, 7 deletions
diff --git a/llvm/docs/ProgrammersManual.rst b/llvm/docs/ProgrammersManual.rst index 198225dfc1f..d8016184c74 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<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 portable and efficient replacement for <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: diff --git a/llvm/docs/ReleaseNotes.rst b/llvm/docs/ReleaseNotes.rst index ad8b44783ed..a6942c01914 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<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 |
