1.. _parallel_for_each_semantics:
2
3parallel_for_each Body semantics and requirements
4=================================================
5
6.. contents::
7    :local:
8    :depth: 1
9
10Description
11***********
12
13This page clarifies `ParallelForEachBody <https://spec.oneapi.com/versions/latest/elements/oneTBB/source/named_requirements/algorithms/par_for_each_body.html>`_
14named requirements for ``tbb::parallel_for_each`` algorithm specification.
15
16.. code:: cpp
17
18    namespace oneapi {
19        namespace tbb {
20
21            template <typaname InputIterator, typename Body>
22            void parallel_for_each( InputIterator first, InputIterator last, Body body ); // overload (1)
23            template <typename InputIterator, typename Body>
24            void parallel_for_each( InputIterator first, InputIterator last, Body body, task_group_context& group ); // overload (2)
25
26            template <typename Container, typename Body>
27            void parallel_for_each( Container& c, Body body ); // overload (3)
28            template <typename Container, typename Body>
29            void parallel_for_each( Container& c, Body body, task_group_context& group ); // overload (4)
30
31            template <typename Container, typename Body>
32            void parallel_for_each( const Container& c, Body body ); // overload (5)
33            template <typename Container, typename Body>
34            void parallel_for_each( const Container& c, Body body, task_group_context& group ); // overload (6)
35
36        } // namespace tbb
37    } // namespace oneapi
38
39Terms
40-----
41
42* ``iterator`` determines the type of the iterator passed into ``parallel_for_each`` algorithm (which is ``InputIterator`` for overloads `(1)` and `(2)`
43  and ``decltype(std::begin(c))`` for overloads `(3) - (6)`)
44* ``value_type`` - the type ``typename std::iterator_traits<iterator>::value_type``
45* ``reference`` -  the type ``typename std::iterator_traits<iterator>::reference``.
46
47Requirements for different iterator types
48-----------------------------------------
49
50If the ``iterator`` satisfies `Input iterator` named requirements from [input.iterators] ISO C++ Standard section and do not satisfies
51`Forward iterator` named requirements from [forward.iterators] ISO C++ Standard section, ``tbb::parallel_for_each`` requires the execution
52of the ``body`` with an object of type ``const value_type&`` or ``value_type&&`` to be well-formed. If both forms are well-formed, an overload with
53rvalue reference will be preferred.
54
55.. caution::
56
57  If the ``Body`` only takes non-const lvalue reference to ``value_type``, named requirements above are violated and the program can be ill-formed.
58
59If the ``iterator`` satisfies `Forward iterator` named requirements from [forward.iterators] ISO C++ Standard section, ``tbb::parallel_for_each`` requires the execution of the ``body``
60with an object of type ``reference`` to be well-formed.
61
62Requirements for ``Body`` with ``feeder`` argument
63--------------------------------------------------
64
65Additional elements submitted into ``tbb::parallel_for_each`` through the ``feeder::add`` passes to the ``Body`` as rvalues and therefore the corresponding
66execution of the ``Body`` is required to be well-formed.
67