.. _concurrent_vector_ug:
concurrent_vector
=================
``A concurrent_vector<T>`` is a dynamically growable array of ``T``. It
is safe to grow a ``concurrent_vector`` while other threads are also
operating on elements of it, or even growing it themselves. For safe
concurrent growing, ``concurrent_vector`` has three methods that support
common uses of dynamic arrays: ``push_back``, ``grow_by``, and
``grow_to_at_least``.
Method ``push_back(x)`` safely appends x to the array. Method
``grow_by(n)`` safely appends ``n`` consecutive elements initialized
with ``T()``. Both methods return an iterator pointing to the first
appended element. Each element is initialized with ``T()``. So for
example, the following routine safely appends a C string to a shared
vector:
::
void Append( concurrent_vector<char>& vector, const char* string ) {
size_t n = strlen(string)+1;
std::copy( string, string+n, vector.grow_by(n) );
}
The related method ``grow_to_at_least(n)``\ grows a vector to size ``n``
if it is shorter. Concurrent calls to the growth methods do not
necessarily return in the order that elements are appended to the
vector.
Method ``size()`` returns the number of elements in the vector, which
may include elements that are still undergoing concurrent construction
by methods ``push_back``, ``grow_by,`` or ``grow_to_at_least``. The
example uses std::copy and iterators, not ``strcpy and pointers``,
because elements in a ``concurrent_vector`` might not be at consecutive
addresses. It is safe to use the iterators while the
``concurrent_vector`` is being grown, as long as the iterators never go
past the current value of ``end()``. However, the iterator may reference
an element undergoing concurrent construction. You must synchronize
construction and access.
A ``concurrent_vector<T>`` never moves an element until the array is
cleared, which can be an advantage over the STL std::vector even for
single-threaded code. However, ``concurrent_vector`` does have more
overhead than std::vector. Use ``concurrent_vector`` only if you really
need the ability to dynamically resize it while other accesses are (or
might be) in flight, or require that an element never move.
.. CAUTION::
Operations on ``concurrent_vector`` are concurrency safe with respect
to *growing*, not for clearing or destroying a vector. Never invoke
method ``clear()`` if there are other operations in flight on the
``concurrent_vector``.
Generated by dwww version 1.15 on Thu May 23 02:18:32 CEST 2024.