tbb::concurrent_vector< T, A > Class Template Reference
[Containers]

Concurrent vector container. More...

#include <concurrent_vector.h>

List of all members.

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 std::reverse_iterator< iterator, T, T &, T * >	reverse_iterator
typedef std::reverse_iterator< const_iterator, T, const T &, const T * >	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.
size_type	grow_by (size_type delta)
	Grow by "delta" elements.
size_type	grow_by (size_type delta, const_reference t)
	Grow by "delta" elements using copying constuctor.
void	grow_to_at_least (size_type n)
	Grow array until it has at least n elements.
size_type	push_back (const_reference item)
	Push item.
reference	operator[] (size_type index)
	Get reference to element at given index.
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.
const_reference	at (size_type index) const
	Get const reference to element at given index.
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.
bool	empty () const
	Return size of vector.
size_type	capacity () const
	Maximum size to which array can grow without allocating more memory.
void	reserve (size_type n)
	Allocate enough space to grow to size n without having to allocate more memory later.
void	compact ()
	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
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
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.
	~concurrent_vector ()
	Clear and destroy vector.
const internal::concurrent_vector_base_v3 &	internal_vector_base () const
Friends
class	internal::vector_iterator
Classes
class	generic_range_type
class	internal_loop_guide
	Exception-aware helper class for filling a segment by exception-danger operators of user class.

---

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.

Otherwise, the program's behavior is undefined.

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 guaranties 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.

If a concurrent grow operation successfully completes, all the elements it has added to the vector will remain valid and accessible even if one of subsequent grow operations fails.

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.0

• Implemented exception-safety guaranties
• 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

template<typename T, class A>

void tbb::concurrent_vector< T, A >::clear

(

)

[inline]

Clear container while keeping memory allocated.

To free up the memory, use in conjunction with method compact(). Not thread safe

template<typename T, class A>

size_type tbb::concurrent_vector< T, A >::grow_by	(	size_type	delta,
		const_reference	t
	)			[inline]

Grow by "delta" elements using copying constuctor.

Returns old size.

template<typename T, class A>

size_type tbb::concurrent_vector< T, A >::grow_by

(

size_type

delta

)

[inline]

Grow by "delta" elements.

Returns old size.

template<typename T, class A>

reference tbb::concurrent_vector< T, A >::operator[]

(

size_type

index

)

[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().

template<typename T, class A>

void tbb::concurrent_vector< T, A >::reserve

(

size_type

n

)

[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:

• concurrent_vector.h

---

Copyright © 2005-2009 Intel Corporation. All Rights Reserved.

Intel, Pentium, Intel Xeon, Itanium, Intel XScale and VTune are registered trademarks or trademarks of Intel Corporation or its subsidiaries in the United States and other countries.

* Other names and brands may be claimed as the property of others.