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 1 year, 2 months 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.
14361436
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``.
14511451
1452 SmallVector has grown a few other minor advantages over std::vector, causing
1453 ``SmallVector`` to be preferred over ``std::vector``.
1454
1455 #. std::vector is exception-safe, and some implementations have pessimizations
1456 that copy elements when SmallVector would move them.
1457
1458 #. SmallVector understands ``isPodLike`` and uses realloc aggressively.
1459
1460 #. Many LLVM APIs take a SmallVectorImpl as an out parameter (see the note
1461 below).
1462
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.
1466
14521467 .. note::
14531468
14541469 Prefer to use ``SmallVectorImpl`` as a parameter type.
14811496
14821497 ^^^^^^^^
14831498
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 :).
14901503
14911504 One worthwhile note about std::vector: avoid code like this:
14921505
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.
102102
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).
110
103111 * Note..
104112
105113 .. NOTE