Concurrent vector container. More...
#include <concurrent_vector.h>
Inheritance diagram for tbb::concurrent_vector< T, A >:
Public Types | |
| typedef internal::concurrent_vector_base_v3::size_type | size_type |
| typedef internal::allocator_base< T, A >::allocator_type | allocator_type |
| typedef T | value_type |
| typedef ptrdiff_t | difference_type |
| typedef T & | reference |
| typedef const T & | const_reference |
| typedef T * | pointer |
| typedef const T * | const_pointer |
| typedef internal::vector_iterator< concurrent_vector, T > | iterator |
| typedef internal::vector_iterator< concurrent_vector, const T > | const_iterator |
| typedef std::reverse_iterator< iterator > | reverse_iterator |
| typedef std::reverse_iterator< const_iterator > | const_reverse_iterator |
| typedef generic_range_type< iterator > | range_type |
| typedef generic_range_type< const_iterator > | const_range_type |
Public Member Functions | |
| concurrent_vector (const allocator_type &a=allocator_type()) | |
| Construct empty vector. | |
| concurrent_vector (const concurrent_vector &vector, const allocator_type &a=allocator_type()) | |
| Copying constructor. | |
| template<class M > | |
| concurrent_vector (const concurrent_vector< T, M > &vector, const allocator_type &a=allocator_type()) | |
| Copying constructor for vector with different allocator type. | |
| concurrent_vector (size_type n) | |
| Construction with initial size specified by argument n. | |
| concurrent_vector (size_type n, const_reference t, const allocator_type &a=allocator_type()) | |
| Construction with initial size specified by argument n, initialization by copying of t, and given allocator instance. | |
| template<class I > | |
| concurrent_vector (I first, I last, const allocator_type &a=allocator_type()) | |
| Construction with copying iteration range and given allocator instance. | |
| concurrent_vector & | operator= (const concurrent_vector &vector) |
| Assignment. | |
| template<class M > | |
| concurrent_vector & | operator= (const concurrent_vector< T, M > &vector) |
| Assignment for vector with different allocator type. | |
| iterator | grow_by (size_type delta) |
| Grow by "delta" elements. More... | |
| iterator | grow_by (size_type delta, const_reference t) |
| Grow by "delta" elements using copying constructor. More... | |
| template<typename I > | |
| iterator | grow_by (I first, I last) |
| Returns iterator pointing to the first new element. More... | |
| iterator | grow_to_at_least (size_type n) |
| Append minimal sequence of elements such that size()>=n. More... | |
| iterator | grow_to_at_least (size_type n, const_reference t) |
| Analogous to grow_to_at_least( size_type n ) with exception that the new elements are initialized by copying of t instead of default construction. More... | |
| iterator | push_back (const_reference item) |
| Push item. More... | |
| reference | operator[] (size_type index) |
| Get reference to element at given index. More... | |
| const_reference | operator[] (size_type index) const |
| Get const reference to element at given index. | |
| reference | at (size_type index) |
| Get reference to element at given index. Throws exceptions on errors. | |
| const_reference | at (size_type index) const |
| Get const reference to element at given index. Throws exceptions on errors. | |
| range_type | range (size_t grainsize=1) |
| Get range for iterating with parallel algorithms. | |
| const_range_type | range (size_t grainsize=1) const |
| Get const range for iterating with parallel algorithms. | |
| size_type | size () const |
| Return size of vector. It may include elements under construction. | |
| bool | empty () const |
| Return false if vector is not empty or has elements under construction at least. | |
| size_type | capacity () const |
| Maximum size to which array can grow without allocating more memory. Concurrent allocations are not included in the value. | |
| void | reserve (size_type n) |
| Allocate enough space to grow to size n without having to allocate more memory later. More... | |
| void | resize (size_type n) |
| Resize the vector. Not thread-safe. | |
| void | resize (size_type n, const_reference t) |
| Resize the vector, copy t for new elements. Not thread-safe. | |
| void | shrink_to_fit () |
| Optimize memory usage and fragmentation. | |
| size_type | max_size () const |
| Upper bound on argument to reserve. | |
| iterator | begin () |
| start iterator | |
| iterator | end () |
| end iterator | |
| const_iterator | begin () const |
| start const iterator | |
| const_iterator | end () const |
| end const iterator | |
| const_iterator | cbegin () const |
| start const iterator | |
| const_iterator | cend () const |
| end const iterator | |
| reverse_iterator | rbegin () |
| reverse start iterator | |
| reverse_iterator | rend () |
| reverse end iterator | |
| const_reverse_iterator | rbegin () const |
| reverse start const iterator | |
| const_reverse_iterator | rend () const |
| reverse end const iterator | |
| const_reverse_iterator | crbegin () const |
| reverse start const iterator | |
| const_reverse_iterator | crend () const |
| reverse end const iterator | |
| reference | front () |
| the first item | |
| const_reference | front () const |
| the first item const | |
| reference | back () |
| the last item | |
| const_reference | back () const |
| the last item const | |
| allocator_type | get_allocator () const |
| return allocator object | |
| void | assign (size_type n, const_reference t) |
| assign n items by copying t item | |
| template<class I > | |
| void | assign (I first, I last) |
| assign range [first, last) | |
| void | swap (concurrent_vector &vector) |
| swap two instances | |
| void | clear () |
| Clear container while keeping memory allocated. More... | |
| ~concurrent_vector () | |
| Clear and destroy vector. | |
| const internal::concurrent_vector_base_v3 & | internal_vector_base () const |
| template<typename I > | |
| void | copy_range (void *dst, const void *p_type_erased_iterator, size_type n) |
Friends | |
| template<typename C , typename U > | |
| class | internal::vector_iterator |
Detailed Description
template<typename T, class A>
class tbb::concurrent_vector< T, A >
Concurrent vector container.
concurrent_vector is a container having the following main properties:
- It provides random indexed access to its elements. The index of the first element is 0.
- It ensures safe concurrent growing its size (different threads can safely append new elements).
- Adding new elements does not invalidate existing iterators and does not change indices of existing items.
- Compatibility
- The class meets all Container Requirements and Reversible Container Requirements from C++ Standard (See ISO/IEC 14882:2003(E), clause 23.1). But it doesn't meet Sequence Requirements due to absence of insert() and erase() methods.
- Exception Safety
- Methods working with memory allocation and/or new elements construction can throw an exception if allocator fails to allocate memory or element's default constructor throws one. Concurrent vector's element of type T must conform to the following requirements:
- Throwing an exception is forbidden for destructor of T.
- Default constructor of T must not throw an exception OR its non-virtual destructor must safely work when its object memory is zero-initialized.
- If an exception happens inside growth or assignment operation, an instance of the vector becomes invalid unless it is stated otherwise in the method documentation. Invalid state means:
- There are no guarantees that all items were initialized by a constructor. The rest of items is zero-filled, including item where exception happens.
- An invalid vector instance cannot be repaired; it is unable to grow anymore.
- Size and capacity reported by the vector are incorrect, and calculated as if the failed operation were successful.
- Attempt to access not allocated elements using operator[] or iterators results in access violation or segmentation fault exception, and in case of using at() method a C++ exception is thrown.
- Fragmentation
- Unlike an STL vector, a concurrent_vector does not move existing elements if it needs to allocate more memory. The container is divided into a series of contiguous arrays of elements. The first reservation, growth, or assignment operation determines the size of the first array. Using small number of elements as initial size incurs fragmentation that may increase element access time. Internal layout can be optimized by method compact() that merges several smaller arrays into one solid.
- Changes since TBB 2.1
- Fixed guarantees of concurrent_vector::size() and grow_to_at_least() methods to assure elements are allocated.
- Methods end()/rbegin()/back() are partly thread-safe since they use size() to get the end of vector
- Added resize() methods (not thread-safe)
- Added cbegin/cend/crbegin/crend methods
- Changed return type of methods grow* and push_back to iterator
- Changes since TBB 2.0
- Implemented exception-safety guarantees
- Added template argument for allocator
- Added allocator argument in constructors
- Faster index calculation
- First growth call specifies a number of segments to be merged in the first allocation.
- Fixed memory blow up for swarm of vector's instances of small size
- Added grow_by(size_type n, const_reference t) growth using copying constructor to init new items.
- Added STL-like constructors.
- Added operators ==, < and derivatives
- Added at() method, approved for using after an exception was thrown inside the vector
- Added get_allocator() method.
- Added assign() methods
- Added compact() method to defragment first segments
- Added swap() method
- range() defaults on grainsize = 1 supporting auto grainsize algorithms.
Member Function Documentation
§ clear()
template<typename T, class A>
|
inline |
Clear container while keeping memory allocated.
To free up the memory, use in conjunction with method compact(). Not thread safe
§ grow_by() [1/3]
template<typename T, class A>
|
inline |
Grow by "delta" elements.
Returns iterator pointing to the first new element.
§ grow_by() [2/3]
template<typename T, class A>
|
inline |
Grow by "delta" elements using copying constructor.
Returns iterator pointing to the first new element.
§ grow_by() [3/3]
template<typename T, class A>
template<typename I >
|
inline |
Returns iterator pointing to the first new element.
§ grow_to_at_least() [1/2]
template<typename T, class A>
|
inline |
Append minimal sequence of elements such that size()>=n.
The new elements are default constructed. Blocks until all elements in range [0..n) are allocated. May return while other elements are being constructed by other threads. Returns iterator that points to beginning of appended sequence. If no elements were appended, returns iterator pointing to nth element.
§ grow_to_at_least() [2/2]
template<typename T, class A>
|
inline |
Analogous to grow_to_at_least( size_type n ) with exception that the new elements are initialized by copying of t instead of default construction.
§ operator[]()
template<typename T, class A>
|
inline |
Get reference to element at given index.
This method is thread-safe for concurrent reads, and also while growing the vector, as long as the calling thread has checked that index < size().
§ push_back()
template<typename T, class A>
|
inline |
Push item.
Returns iterator pointing to the new element.
§ reserve()
template<typename T, class A>
|
inline |
Allocate enough space to grow to size n without having to allocate more memory later.
Like most of the methods provided for STL compatibility, this method is not thread safe. The capacity afterwards may be bigger than the requested reservation.
The documentation for this class was generated from the following file:
- external/tbb/include/tbb/concurrent_vector.h
