Vectray¶
Synopsis¶
#include "swoc/Vectray.h"
-
template<typename T, size_t N, class Allocator>
class Vectray¶
Vectray is a class intended to replace std::vector in situations where performance is critical.
An instance of Vectray contains a static array of size N which is used in preference to allocating
memory. If the number of instances is generally less than N then no memory allocation /
deallocation is done and the performance is as fast as a std::array. Unlike an array, if
the required memory exceeds the static limits the internal storage is changed to a std::vector
without data loss. Another key difference is the number of valid elements in the container can vary.
Performance gain from using this class depends upon
The static limit N being relatively small to minimize fixed costs.
Required storage usually fits within the static limits.
If allocation is commonly needed this will be slower than a std::vector because of
the additional cost of copying from static to dynamic memory.
The most common use case is for arrays that are usually only 1 or 2 elements (such as options
for a parameter) and only rarely longer. Vectray can then significantly reduce memory churn at small
cost.
The second common use case is for stack buffers of moderate size, such as logging buffers. Generally
these are selected to be large to enough to cover most cases, except for the occasional truncation.
In this case Vectray preserves the performance of the common case while providing an escape in the
rare circumstance of exceeding the buffer size.
As always, performance tuning is an art, not a science. Do not simply assume Vectray is a better choice
and use it to replace std::vector or std::array in general. Use where it looks helpful and do
measurements to verify.
Usage¶
Vectray acts as a combination of std::vector and std::aray and is declared like the latter.
For an instance that contains a single static element of type std::string
swoc::Vectray<std::string, 1> strings;
The static elements are not default constructed, but are constructed as needed.
Allocator¶
Generally this should be defaulted, but is exposed so a polymorphic memory resource based allocator can be used when needed.