1.. _Containers:
2
3Containers
4==========
5
6
7|full_name| provides highly concurrent
8container classes. These containers can be used with raw Windows\* OS or
9Linux\* OS threads, or in conjunction with task-based programming.
10
11
12A concurrent container allows multiple threads to concurrently access
13and update items in the container. Typical C++ STL containers do not
14permit concurrent update; attempts to modify them concurrently often
15result in corrupting the container. STL containers can be wrapped in a
16mutex to make them safe for concurrent access, by letting only one
17thread operate on the container at a time, but that approach eliminates
18concurrency, thus restricting parallel speedup.
19
20
21Containers provided by oneTBB offer a much higher level of concurrency,
22via one or both of the following methods:
23
24
25-  **Fine-grained locking:** Multiple threads operate on the container
26   by locking only those portions they really need to lock. As long as
27   different threads access different portions, they can proceed
28   concurrently.
29
30
31-  **Lock-free techniques:** Different threads account and correct for
32   the effects of other interfering threads.
33
34
35Notice that highly-concurrent containers come at a cost. They typically
36have higher overheads than regular STL containers. Operations on
37highly-concurrent containers may take longer than for STL containers.
38Therefore, use highly-concurrent containers when the speedup from the
39additional concurrency that they enable outweighs their slower
40sequential performance.
41
42
43.. CAUTION::
44   As with most objects in C++, the constructor or destructor of a
45   container object must not be invoked concurrently with another
46   operation on the same object. Otherwise the resulting race may cause
47   the operation to be executed on an undefined object.
48
49.. toctree::
50   :maxdepth: 4
51
52   ../tbb_userguide/concurrent_hash_map
53   ../tbb_userguide/concurrent_vector_ug
54   ../tbb_userguide/Concurrent_Queue_Classes
55   ../tbb_userguide/Summary_of_Containers
56