concurrent_vector Class

 

The concurrent_vector class is a sequence container class that allows random access to any element. It enables concurrency-safe append, element access, iterator access, and iterator traversal operations.

template<typename T, class _Ax>
class concurrent_vector: protected details::_Allocator_base<T,
    _Ax>,
 private details::_Concurrent_vector_base_v4;

Parameters

T
The data type of the elements to be stored in the vector.

_Ax
The type that represents the stored allocator object that encapsulates details about the allocation and deallocation of memory for the concurrent vector. This argument is optional and the default value is allocator<``T``>.

Public Typedefs

NameDescription
allocator_typeA type that represents the allocator class for the concurrent vector.
const_iteratorA type that provides a random-access iterator that can read a const element in a concurrent vector.
const_pointerA type that provides a pointer to a const element in a concurrent vector.
const_referenceA type that provides a reference to a const element stored in a concurrent vector for reading and performing const operations.
const_reverse_iteratorA type that provides a random-access iterator that can read any const element in the concurrent vector.
difference_typeA type that provides the signed distance between two elements in a concurrent vector.
iteratorA type that provides a random-access iterator that can read any element in a concurrent vector. Modification of an element using the iterator is not concurrency-safe.
pointerA type that provides a pointer to an element in a concurrent vector.
referenceA type that provides a reference to an element stored in a concurrent vector.
reverse_iteratorA type that provides a random-access iterator that can read any element in a reversed concurrent vector. Modification of an element using the iterator is not concurrency-safe.
size_typeA type that counts the number of elements in a concurrent vector.
value_typeA type that represents the data type stored in a concurrent vector.

Public Constructors

NameDescription
concurrent_vector::concurrent_vector ConstructorOverloaded. Constructs a concurrent vector.
concurrent_vector::~concurrent_vector DestructorErases all elements and destroys this concurrent vector.

Public Methods

NameDescription
concurrent_vector::assign MethodOverloaded. Erases the elements of the concurrent vector and assigns to it either _N copies of _Item, or values specified by the iterator range [ _Begin, _End). This method is not concurrency-safe.
concurrent_vector::at MethodOverloaded. Provides access to the element at the given index in the concurrent vector. This method is concurrency-safe for read operations, and also while growing the vector, as long as you have ensured that the value _Index is less than the size of the concurrent vector.
concurrent_vector::back MethodOverloaded. Returns a reference or a const reference to the last element in the concurrent vector. If the concurrent vector is empty, the return value is undefined. This method is concurrency-safe.
concurrent_vector::begin MethodOverloaded. Returns an iterator of type iterator or const_iterator to the beginning of the concurrent vector. This method is concurrency-safe.
concurrent_vector::capacity MethodReturns the maximum size to which the concurrent vector can grow without having to allocate more memory. This method is concurrency-safe.
concurrent_vector::cbegin MethodReturns an iterator of type const_iterator to the beginning of the concurrent vector. This method is concurrency-safe.
concurrent_vector::cend MethodReturns an iterator of type const_iterator to the end of the concurrent vector. This method is concurrency-safe.
concurrent_vector::clear MethodErases all elements in the concurrent vector. This method is not concurrency-safe.
concurrent_vector::crbegin MethodReturns an iterator of type const_reverse_iterator to the beginning of the concurrent vector. This method is concurrency-safe.
concurrent_vector::crend MethodReturns an iterator of type const_reverse_iterator to the end of the concurrent vector. This method is concurrency-safe.
concurrent_vector::empty MethodTests if the concurrent vector is empty at the time this method is called. This method is concurrency-safe.
concurrent_vector::end MethodOverloaded. Returns an iterator of type iterator or const_iterator to the end of the concurrent vector. This method is concurrency-safe.
concurrent_vector::front MethodOverloaded. Returns a reference or a const reference to the first element in the concurrent vector. If the concurrent vector is empty, the return value is undefined. This method is concurrency-safe.
concurrent_vector::get_allocator MethodReturns a copy of the allocator used to construct the concurrent vector. This method is concurrency-safe.
concurrent_vector::grow_by MethodOverloaded. Grows this concurrent vector by _Delta elements. This method is concurrency-safe.
concurrent_vector::grow_to_at_least MethodGrows this concurrent vector until it has at least _N elements. This method is concurrency-safe.
concurrent_vector::max_size MethodReturns the maximum number of elements the concurrent vector can hold. This method is concurrency-safe.
concurrent_vector::push_back MethodOverloaded. Appends the given item to the end of the concurrent vector. This method is concurrency-safe.
concurrent_vector::rbegin MethodOverloaded. Returns an iterator of type reverse_iterator or const_reverse_iterator to the beginning of the concurrent vector. This method is concurrency-safe.
concurrent_vector::rend MethodOverloaded. Returns an iterator of type reverse_iterator or const_reverse_iterator to the end of the concurrent vector. This method is concurrency-safe.
concurrent_vector::reserve MethodAllocates enough space to grow the concurrent vector to size _N without having to allocate more memory later. This method is not concurrency-safe.
concurrent_vector::resize MethodOverloaded. Changes the size of the concurrent vector to the requested size, deleting or adding elements as necessary. This method is not concurrency-safe.
concurrent_vector::shrink_to_fit MethodCompacts the internal representation of the concurrent vector to reduce fragmentation and optimize memory usage. This method is not concurrency-safe.
concurrent_vector::size MethodReturns the number of elements in the concurrent vector. This method is concurrency-safe.
concurrent_vector::swap MethodSwaps the contents of two concurrent vectors. This method is not concurrency-safe.

Public Operators

NameDescription
concurrent_vector::operator[] OperatorOverloaded. Provides access to the element at the given index in the concurrent vector. This method is concurrency-safe for read operations, and also while growing the vector, as long as the you have ensured that the value _Index is less than the size of the concurrent vector.
concurrent_vector::operator= OperatorOverloaded. Assigns the contents of another concurrent_vector object to this one. This method is not concurrency-safe.

For detailed information on the concurrent_vector class, see Parallel Containers and Objects.

_Concurrent_vector_base_v4

_Allocator_base

concurrent_vector

Header: concurrent_vector.h

Namespace: concurrency

Erases the elements of the concurrent vector and assigns to it either _N copies of _Item, or values specified by the iterator range [ _Begin, _End). This method is not concurrency-safe.

void assign(
    size_type _N,
    const_reference _Item);

template<class _InputIterator>
void assign(_InputIterator _Begin,
    _InputIterator _End);

Parameters

_InputIterator
The type of the specified iterator.

_N
The number of items to copy into the concurrent vector.

_Item
Reference to a value used to fill the concurrent vector.

_Begin
An iterator to the first element of the source range.

_End
An iterator to one past the last element of the source range.

Remarks

assign is not concurrency-safe. You must ensure that no other threads are invoking methods on the concurrent vector when you call this method.

Provides access to the element at the given index in the concurrent vector. This method is concurrency-safe for read operations, and also while growing the vector, as long as you have ensured that the value _Index is less than the size of the concurrent vector.

reference at(size_type _Index);

const_reference at(size_type _Index) const;

Parameters

_Index
The index of the element to be retrieved.

Return Value

A reference to the item at the given index.

Remarks

The version of the function at that returns a non- const reference cannot be used to concurrently write to the element from different threads. A different synchronization object should be used to synchronize concurrent read and write operations to the same data element.

The method throws out_of_range if _Index is greater than or equal to the size of the concurrent vector, and range_error if the index is for a broken portion of the vector. For details on how a vector can become broken, see Parallel Containers and Objects.

Returns a reference or a const reference to the last element in the concurrent vector. If the concurrent vector is empty, the return value is undefined. This method is concurrency-safe.

reference back();

const_reference back() const;

Return Value

A reference or a const reference to the last element in the concurrent vector.

Returns an iterator of type iterator or const_iterator to the beginning of the concurrent vector. This method is concurrency-safe.

iterator begin();

const_iterator begin() const;

Return Value

An iterator of type iterator or const_iterator to the beginning of the concurrent vector.

Returns the maximum size to which the concurrent vector can grow without having to allocate more memory. This method is concurrency-safe.

size_type capacity() const;

Return Value

The maximum size to which the concurrent vector can grow without having to allocate more memory.

Remarks

Unlike an STL vector, a concurrent_vector object does not move existing elements if it allocates more memory.

Returns an iterator of type const_iterator to the beginning of the concurrent vector. This method is concurrency-safe.

const_iterator cbegin() const;

Return Value

An iterator of type const_iterator to the beginning of the concurrent vector.

Returns an iterator of type const_iterator to the end of the concurrent vector. This method is concurrency-safe.

const_iterator cend() const;

Return Value

An iterator of type const_iterator to the end of the concurrent vector.

Erases all elements in the concurrent vector. This method is not concurrency-safe.

void clear();

Remarks

clear is not concurrency-safe. You must ensure that no other threads are invoking methods on the concurrent vector when you call this method. clear does not free internal arrays. To free internal arrays, call the function shrink_to_fit after clear.

Constructs a concurrent vector.

explicit concurrent_vector(
    const allocator_type& _Al = allocator_type());

concurrent_vector(
    const concurrent_vector& _Vector);

template<class M>
concurrent_vector(
    const concurrent_vector<T,
    M>& _Vector,
    const allocator_type& _Al = allocator_type());

concurrent_vector(
    concurrent_vector&& _Vector);

explicit concurrent_vector(
    size_type _N);

concurrent_vector(
    size_type _N,
    const_reference _Item,
    const allocator_type& _Al = allocator_type());

template<class _InputIterator>
concurrent_vector(_InputIterator _Begin,
    _InputIterator _End,
    const allocator_type& _Al = allocator_type());

Parameters

M
The allocator type of the source vector.

_InputIterator
The type of the input iterator.

_Al
The allocator class to use with this object.

_Vector
The source concurrent_vector object to copy or move elements from.

_N
The initial capacity of the concurrent_vector object.

_Item
The value of elements in the constructed object.

_Begin
Position of the first element in the range of elements to be copied.

_End
Position of the first element beyond the range of elements to be copied.

Remarks

All constructors store an allocator object _Al and initialize the vector.

The first constructor specify an empty initial vector and explicitly specifies the allocator type. to be used.

The second and third constructors specify a copy of the concurrent vector _Vector.

The fourth constructor specifies a move of the concurrent vector _Vector.

The fifth constructor specifies a repetition of a specified number ( _N) of elements of the default value for class T.

The sixth constructor specifies a repetition of ( _N) elements of value _Item.

The last constructor specifies values supplied by the iterator range [ _Begin, _End).

Erases all elements and destroys this concurrent vector.

~concurrent_vector();

Returns an iterator of type const_reverse_iterator to the beginning of the concurrent vector. This method is concurrency-safe.

const_reverse_iterator crbegin() const;

Return Value

An iterator of type const_reverse_iterator to the beginning of the concurrent vector.

Returns an iterator of type const_reverse_iterator to the end of the concurrent vector. This method is concurrency-safe.

const_reverse_iterator crend() const;

Return Value

An iterator of type const_reverse_iterator to the end of the concurrent vector.

Tests if the concurrent vector is empty at the time this method is called. This method is concurrency-safe.

bool empty() const;

Return Value

true if the vector was empty at the moment the function was called, false otherwise.

Returns an iterator of type iterator or const_iterator to the end of the concurrent vector. This method is concurrency-safe.

iterator end();

const_iterator end() const;

Return Value

An iterator of type iterator or const_iterator to the end of the concurrent vector.

Returns a reference or a const reference to the first element in the concurrent vector. If the concurrent vector is empty, the return value is undefined. This method is concurrency-safe.

reference front();

const_reference front() const;

Return Value

A reference or a const reference to the first element in the concurrent vector.

Returns a copy of the allocator used to construct the concurrent vector. This method is concurrency-safe.

allocator_type get_allocator() const;

Return Value

A copy of the allocator used to construct the concurrent_vector object.

Grows this concurrent vector by _Delta elements. This method is concurrency-safe.

iterator grow_by(
    size_type _Delta);

iterator grow_by(
    size_type _Delta,
    const_reference _Item);

Parameters

_Delta
The number of elements to append to the object.

_Item
The value to initialize the new elements with.

Return Value

An iterator to first item appended.

Remarks

If _Item is not specified, the new elements are default constructed.

Grows this concurrent vector until it has at least _N elements. This method is concurrency-safe.

iterator grow_to_at_least(size_type _N);

Parameters

_N
The new minimum size for the concurrent_vector object.

Return Value

An iterator that points to beginning of appended sequence, or to the element at index _N if no elements were appended.

Returns the maximum number of elements the concurrent vector can hold. This method is concurrency-safe.

size_type max_size() const;

Return Value

The maximum number of elements the concurrent_vector object can hold.

Assigns the contents of another concurrent_vector object to this one. This method is not concurrency-safe.

concurrent_vector& operator= (
    const concurrent_vector& _Vector);

template<class M>
concurrent_vector& operator= (
    const concurrent_vector<T, M>& _Vector);

concurrent_vector& operator= (
    concurrent_vector&& _Vector);

Parameters

M
The allocator type of the source vector.

_Vector
The source concurrent_vector object.

Return Value

A reference to this concurrent_vector object.

Provides access to the element at the given index in the concurrent vector. This method is concurrency-safe for read operations, and also while growing the vector, as long as the you have ensured that the value _Index is less than the size of the concurrent vector.

reference operator[](size_type _Index);

const_reference operator[](size_type _Index) const;

Parameters

_Index
The index of the element to be retrieved.

Return Value

A reference to the item at the given index.

Remarks

The version of operator [] that returns a non- const reference cannot be used to concurrently write to the element from different threads. A different synchronization object should be used to synchronize concurrent read and write operations to the same data element.

No bounds checking is performed to ensure that _Index is a valid index into the concurrent vector.

Appends the given item to the end of the concurrent vector. This method is concurrency-safe.

iterator push_back(const_reference _Item);

iterator push_back(T&& _Item);

Parameters

_Item
The value to be appended.

Return Value

An iterator to item appended.

Returns an iterator of type reverse_iterator or const_reverse_iterator to the beginning of the concurrent vector. This method is concurrency-safe.

reverse_iterator rbegin();

const_reverse_iterator rbegin() const;

Return Value

An iterator of type reverse_iterator or const_reverse_iterator to the beginning of the concurrent vector.

Returns an iterator of type reverse_iterator or const_reverse_iterator to the end of the concurrent vector. This method is concurrency-safe.

reverse_iterator rend();

const_reverse_iterator rend() const;

Return Value

An iterator of type reverse_iterator or const_reverse_iterator to the end of the concurrent vector.

Allocates enough space to grow the concurrent vector to size _N without having to allocate more memory later. This method is not concurrency-safe.

void reserve(size_type _N);

Parameters

_N
The number of elements to reserve space for.

Remarks

reserve is not concurrency-safe. You must ensure that no other threads are invoking methods on the concurrent vector when you call this method. The capacity of the concurrent vector after the method returns may be bigger than the requested reservation.

Changes the size of the concurrent vector to the requested size, deleting or adding elements as necessary. This method is not concurrency-safe.

void resize(
    size_type _N);

void resize(
    size_type _N,
    const T& val);

Parameters

_N
The new size of the concurrent_vector.

val
The value of new elements added to the vector if the new size is larger than the original size. If the value is omitted, the new objects are assigned the default value for their type.

Remarks

If the size of the container is less than the requested size, elements are added to the vector until it reaches the requested size. If the size of the container is larger than the requested size, the elements closest to the end of the container are deleted until the container reaches the size _N. If the present size of the container is the same as the requested size, no action is taken.

resize is not concurrency safe. You must ensure that no other threads are invoking methods on the concurrent vector when you call this method.

Compacts the internal representation of the concurrent vector to reduce fragmentation and optimize memory usage. This method is not concurrency-safe.

void shrink_to_fit();

Remarks

This method will internally re-allocate memory move elements around, invalidating all the iterators. shrink_to_fit is not concurrency-safe. You must ensure that no other threads are invoking methods on the concurrent vector when you call this function.

Returns the number of elements in the concurrent vector. This method is concurrency-safe.

size_type size() const;

Return Value

The number of elements in this concurrent_vector object.

Remarks

The returned size is guaranteed to include all elements appended by calls to the function push_back, or grow operations that have completed prior to invoking this method. However, it may also include elements that are allocated but still under construction by concurrent calls to any of the growth methods.

Swaps the contents of two concurrent vectors. This method is not concurrency-safe.

void swap(concurrent_vector& _Vector);

Parameters

_Vector
The concurrent_vector object to swap contents with.

concurrency Namespace
Parallel Containers and Objects

Show: