llvm.org GIT mirror llvm / 235b4df
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 git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@338071 91177308-0d34-0410-b5e6-96231b3b80d8 Duncan P. N. Exon Smith 2 years ago
2 changed file(s) with 28 addition(s) and 7 deletion(s). Raw diff Collapse all Expand all
14341434 push_back/pop_back operations, supports efficient random access to its elements,
14351435 etc.
1437 The advantage of SmallVector is that it allocates space for some number of
1437 The main advantage of SmallVector is that it allocates space for some number of
14381438 elements (N) **in the object itself**. Because of this, if the SmallVector is
14391439 dynamically smaller than N, no malloc is performed. This can be a big win in
14401440 cases where the malloc/free call is far more expensive than the code that
14491449 SmallVector also provides a nice portable and efficient replacement for
14501450 ``alloca``.
1452 SmallVector has grown a few other minor advantages over std::vector, causing
1453 ``SmallVector`` to be preferred over ``std::vector``.
1455 #. std::vector is exception-safe, and some implementations have pessimizations
1456 that copy elements when SmallVector would move them.
1458 #. SmallVector understands ``isPodLike`` and uses realloc aggressively.
1460 #. Many LLVM APIs take a SmallVectorImpl as an out parameter (see the note
1461 below).
1463 #. SmallVector with N equal to 0 is smaller than std::vector on 64-bit
1464 platforms, since it uses ``unsigned`` (instead of ``void*``) for its size
1465 and capacity.
14521467 .. note::
14541469 Prefer to use ``SmallVectorImpl`` as a parameter type.
14821497 ^^^^^^^^
1484 ``std::vector`` is well loved and respected. It is useful when SmallVector
1485 isn't: when the size of the vector is often large (thus the small optimization
1486 will rarely be a benefit) or if you will be allocating many instances of the
1487 vector itself (which would waste space for elements that aren't in the
1488 container). vector is also useful when interfacing with code that expects
1489 vectors :).
1499 ``std::vector`` is well loved and respected. However, ``SmallVector``
1500 is often a better option due to the advantages listed above. std::vector is
1501 still useful when you need to store more than ``UINT32_MAX`` elements or when
1502 interfacing with code that expects vectors :).
14911504 One worthwhile note about std::vector: avoid code like this:
100100 * Early support for UBsan, X-Ray instrumentation and libFuzzer (x86 and x86_64) for OpenBSD. Support for MSan
101101 (x86_64), X-Ray instrumentation and libFuzzer (x86 and x86_64) for FreeBSD.
103 * ``SmallVector`` shrank from ``sizeof(void*) * 4 + sizeof(T)`` to
104 ``sizeof(void*) + sizeof(unsigned) * 2``, smaller than ``std::vector`` on
105 64-bit platforms. The maximum capacity is now restricted to ``UINT32_MAX``.
106 Since SmallVector doesn't have the exception-safety pessimizations some
107 implementations saddle std::vector with and is better at using ``realloc``,
108 it's now a better choice even on the heap (although when TinyPtrVector works,
109 it's even smaller).
103111 * Note..
105113 .. NOTE