1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
|
<!DOCTYPE html
PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<!-- saved from url=(0014)about:internet -->
<html xmlns:MSHelp="http://www.microsoft.com/MSHelp/" lang="en-us" xml:lang="en-us"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<meta name="DC.Type" content="reference">
<meta name="DC.Title" content="concurrent_vector">
<meta name="DC.subject" content="concurrent_vector">
<meta name="keywords" content="concurrent_vector">
<meta name="DC.Relation" scheme="URI" content="../../reference/containers_overview.htm">
<meta name="DC.Relation" scheme="URI" content="../../reference/containers_overview/concurrent_vector/construction_copy_and_assignment.htm">
<meta name="DC.Relation" scheme="URI" content="../../reference/containers_overview/concurrent_vector/whole_vector_operations.htm">
<meta name="DC.Relation" scheme="URI" content="../../reference/containers_overview/concurrent_vector/concurrent_growth.htm">
<meta name="DC.Relation" scheme="URI" content="../../reference/containers_overview/concurrent_vector/access.htm">
<meta name="DC.Relation" scheme="URI" content="../../reference/containers_overview/concurrent_vector/parallel_iteration.htm">
<meta name="DC.Relation" scheme="URI" content="../../reference/containers_overview/concurrent_vector/capacity_vector.htm">
<meta name="DC.Relation" scheme="URI" content="../../reference/containers_overview/concurrent_vector/iterators_vector.htm">
<meta name="DC.Format" content="XHTML">
<meta name="DC.Identifier" content="concurrent_vector">
<meta name="DC.Language" content="en-US">
<link rel="stylesheet" type="text/css" href="../../intel_css_styles.css">
<title>concurrent_vector</title>
</head>
<body id="concurrent_vector">
<!-- ==============(Start:NavScript)================= -->
<script src="..\..\NavScript.js" language="JavaScript1.2" type="text/javascript"></script>
<script language="JavaScript1.2" type="text/javascript">WriteNavLink(2);</script>
<!-- ==============(End:NavScript)================= -->
<a name="concurrent_vector"><!-- --></a>
<h1 class="topictitle1">concurrent_vector</h1>
<div>
<div class="section"><h2 class="sectiontitle">Summary</h2>
<p>Template class for vector that can be concurrently
grown and accessed.
</p>
</div>
<div class="section"><h2 class="sectiontitle">Syntax</h2>
<pre>template<typename T, class Alloc=cache_aligned_allocator<T> >
class concurrent_vector;</pre>
</div>
<div class="section"><h2 class="sectiontitle">Header</h2>
<pre> #include "tbb/concurrent_vector.h"</pre>
</div>
<div class="section"><h2 class="sectiontitle">Description</h2>
<p>A
<samp class="codeph">concurrent_vector</samp> is a container with the following
features:
</p>
<ul type="disc">
<li>
<p>Random access by index. The index of the first
element is zero.
</p>
</li>
<li>
<p>Multiple threads can grow the container and
append new elements concurrently.
</p>
</li>
<li>
<p>Growing the container does not invalidate
existing iterators or indices.
</p>
</li>
</ul>
<p>A
<samp class="codeph">concurrent_vector</samp> meets all requirements for a
Container and a Reversible Container as specified in the ISO C++ standard. It
does not meet the Sequence requirements due to absence of methods
<samp class="codeph">insert()</samp> and
<samp class="codeph">erase()</samp>.
</p>
</div>
<div class="section"><h2 class="sectiontitle">Members</h2>
<pre>namespace tbb {
template<typename T, typename Alloc=cache_aligned_allocator<T> >
class concurrent_vector {
public:
typedef size_t size_type;
typedef <em>allocator-A-rebound-for-T</em> 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 <em>implementation-defined</em> iterator;
typedef <em>implementation-defined</em> const_iterator;
typedef <em>implementation-defined</em> reverse_iterator;
typedef <em>implementation-defined</em> const_reverse_iterator;
// Parallel ranges
typedef <em>implementation-defined</em> range_type;
typedef <em>implementation-defined</em> const_range_type;
range_type range( size_t grainsize );
const_range_type range( size_t grainsize ) const;
// Constructors
explicit concurrent_vector( const allocator_type& a =
allocator_type() );
concurrent_vector( const concurrent_vector& x );
template<typename M>
concurrent_vector( const concurrent_vector<T, M>& x );
explicit concurrent_vector( size_type n,
const T& t=T(),
const allocator_type& a = allocator_type() );
template<typename InputIterator>
concurrent_vector(InputIterator first, InputIterator last,
const allocator_type& a=allocator_type());
//C++11 specific
concurrent_vector(std::initializer_list<T> il, const allocator_type &a = allocator_type())
// Assignment
concurrent_vector& operator=( const concurrent_vector& x );
template<class M>
concurrent_vector& operator=( const concurrent_vector<T, M>& x );
void assign( size_type n, const T& t );
template<class InputIterator >
void assign( InputIterator first, InputIterator last );
//C++11 specific
concurrent_vector& operator=( const std::initializer_list<T> &il);
void assign(std::initializer_list<T> il);
// Concurrent growth operations
iterator grow_by( size_type delta );
iterator grow_by( size_type delta, const T& t );
iterator grow_to_at_least( size_type n );
iterator push_back( const T& item );
// Items access
reference operator[]( size_type index );
const_reference operator[]( size_type index ) const;
reference at( size_type index );
const_reference at( size_type index ) const;
reference front();
const_reference front() const;
reference back();
const_reference back() const;
// Storage
bool empty() const;
size_type capacity() const;
size_type max_size() const;
size_type size() const;
allocator_type get_allocator() const;
// Non-concurrent operations on whole container
void reserve( size_type n );
void compact();
void swap( concurrent_vector& vector );
void clear();
~concurrent_vector();
// Iterators
iterator begin();
iterator end();
const_iterator begin() const;
const_iterator end() const;
reverse_iterator rbegin();
reverse_iterator rend();
const_reverse_iterator rbegin() const;
const_reverse_iterator rend() const;
// C++11 extensions
const_iterator cbegin() const;
const_iterator cend() const;
const_reverse_iterator crbegin() const;
const_reverse_iterator crend() const;
};
// Template functions
template<typename T, class A1, class A2>
bool operator==( const concurrent_vector<T, A1>& a,
const concurrent_vector<T, A2>& b );
template<typename T, class A1, class A2>
bool operator!=( const concurrent_vector<T, A1>& a,
const concurrent_vector<T, A2>& b );
template<typename T, class A1, class A2>
bool operator<( const concurrent_vector<T, A1>& a,
const concurrent_vector<T, A2>& b );
template<typename T, class A1, class A2>
bool operator>( const concurrent_vector<T, A1>& a,
const concurrent_vector<T, A2>& b );
template<typename T, class A1, class A2>
bool operator<=( const concurrent_vector<T, A1>& a,
const concurrent_vector<T, A2>& b );
template<typename T, class A1, class A2>
bool operator>=(const concurrent_vector<T, A1>& a,
const concurrent_vector<T, A2>& b );
template<typename T, class A>
void swap(concurrent_vector<T, A>& a, concurrent_vector<T, A>& b);
}</pre>
<div class="Note"><h3 class="NoteTipHead">
Note</h3>
<p> The rebinding of
<samp class="codeph">allocator_type</samp> follows practice established by both
the Microsoft and GNU implementations of
<samp class="codeph">std::vector</samp>.
</p>
</div>
<div class="Note"><h3 class="NoteTipHead">
Note</h3>
<p> The return types of the growth methods are
different in Intel® Threading Building Blocks (Intel® TBB) 2.2 than in prior
versions. See footnotes in the descriptions of the individual methods for
details.
</p>
</div>
</div>
<div class="section"><h2 class="sectiontitle">Exception Safety</h2>
<p>Concurrent growing is fundamentally incompatible
with ideal exception safety. Nonetheless,
<samp class="codeph">concurrent_vector</samp> offers a practical level of
exception safety.
</p>
<p>Element type T must meet the following
requirements:
</p>
<ul type="disc">
<li>
<p>Its destructor must not throw an exception.
</p>
</li>
<li>
<p>If its default constructor can throw an
exception, its destructor must be non-virtual and work correctly on zero-filled
memory.
</p>
</li>
</ul>
<p>Otherwise the program's behavior is undefined.
</p>
<p>Growth and vector assignment append a sequence of
elements to a vector. If an exception occurs, the impact on the vector depends
upon the cause of the exception:
</p>
<ul type="disc">
<li>
<p>If the exception is thrown by the constructor
of an element, then all subsequent elements in the appended sequence will be
zero-filled.
</p>
</li>
<li>
<p>Otherwise, the exception was thrown by the
vector's allocator. The vector becomes broken. Each element in the appended
sequence will be in one of three states:
</p>
</li>
</ul>
<ul type="disc" class="ul_2">
<li class="li_2">constructed
</li>
<li class="li_2">zero-filled>
</li>
<li class="li_2">unallocated in memory
</li>
</ul>
<p>Once a vector becomes broken, care must be taken
when accessing it:
</p>
<ul type="disc">
<li>
<p>Accessing an unallocated element with method at
causes an exception
<samp class="codeph">std::range_error</samp>. Any other way of accessing an
unallocated element has undefined behavior.
</p>
</li>
<li>
<p>The values of
<samp class="codeph">capacity()</samp> and
<samp class="codeph">size()</samp> may be less than expected.
</p>
</li>
<li>
<p>Access to a broken vector via<samp class="codeph">
back()</samp> has undefined behavior.
</p>
</li>
</ul>
<p>However, the following guarantees hold for broken
or unbroken vectors:
</p>
<ul type="disc">
<li>
<p>Let
<samp class="codeph"><em>k</em></samp> be an index of an unallocated element.
Then<samp class="codeph"> size()<= capacity()<=<em>k</em>
</samp>
</p>
</li>
<li>
<p>Growth operations never cause
<samp class="codeph">size()</samp> or
<samp class="codeph">capacity()</samp> to decrease.
</p>
</li>
</ul>
<p>If a concurrent growth operation successfully
completes, the appended sequence remains valid and accessible even if a
subsequent growth operations fails.
</p>
</div>
<div class="section"><h2 class="sectiontitle">Fragmentation</h2>
<p>Unlike a
<samp class="codeph">std::vector</samp>, a
<samp class="codeph">concurrent_vector</samp> never moves existing elements when
it grows. The container allocates a series of contiguous arrays. The first
reservation, growth, or assignment operation determines the size of the first
array. Using a small number of elements as initial size incurs fragmentation
across cache lines that may increase element access time. The method
<samp class="codeph">shrink_to_fit()</samp>merges several smaller arrays into a
single contiguous array, which may improve access time.
</p>
</div>
</div>
<div class="familylinks">
<div class="parentlink"><strong>Parent topic:</strong> <a href="../../reference/containers_overview.htm">Containers Overview</a></div>
</div>
<div>
<ul class="ullinks">
<li class="ulchildlink"><a href="../../reference/containers_overview/concurrent_vector/construction_copy_and_assignment.htm">Construction, Copy, and Assignment</a><br>
</li>
<li class="ulchildlink"><a href="../../reference/containers_overview/concurrent_vector/whole_vector_operations.htm">Whole Vector Operations</a><br>
</li>
<li class="ulchildlink"><a href="../../reference/containers_overview/concurrent_vector/concurrent_growth.htm">Concurrent Growth</a><br>
</li>
<li class="ulchildlink"><a href="../../reference/containers_overview/concurrent_vector/access.htm">Access</a><br>
</li>
<li class="ulchildlink"><a href="../../reference/containers_overview/concurrent_vector/parallel_iteration.htm">Parallel Iteration</a><br>
</li>
<li class="ulchildlink"><a href="../../reference/containers_overview/concurrent_vector/capacity_vector.htm">Capacity</a><br>
</li>
<li class="ulchildlink"><a href="../../reference/containers_overview/concurrent_vector/iterators_vector.htm">Iterators</a><br>
</li>
</ul>
</div>
</body>
</html>
|
