parallel_for_each Body semantics and requirements

Description

This page clarifies ParallelForEachBody named requirements for tbb::parallel_for_each algorithm specification.

namespace oneapi {
    namespace tbb {

        template <typaname InputIterator, typename Body>
        void parallel_for_each( InputIterator first, InputIterator last, Body body ); // overload (1)
        template <typename InputIterator, typename Body>
        void parallel_for_each( InputIterator first, InputIterator last, Body body, task_group_context& group ); // overload (2)

        template <typename Container, typename Body>
        void parallel_for_each( Container& c, Body body ); // overload (3)
        template <typename Container, typename Body>
        void parallel_for_each( Container& c, Body body, task_group_context& group ); // overload (4)

        template <typename Container, typename Body>
        void parallel_for_each( const Container& c, Body body ); // overload (5)
        template <typename Container, typename Body>
        void parallel_for_each( const Container& c, Body body, task_group_context& group ); // overload (6)

    } // namespace tbb
} // namespace oneapi

Terms

  • iterator determines the type of the iterator passed into parallel_for_each algorithm (which is InputIterator for overloads (1) and (2) and decltype(std::begin(c)) for overloads (3) - (6))

  • value_type - the type typename std::iterator_traits<iterator>::value_type

  • reference - the type typename std::iterator_traits<iterator>::reference.

Requirements for different iterator types

If the iterator satisfies Input iterator named requirements from [input.iterators] ISO C++ Standard section and do not satisfies Forward iterator named requirements from [forward.iterators] ISO C++ Standard section, tbb::parallel_for_each requires the execution of 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 rvalue reference will be prefered.

Caution

If the Body only takes non-const lvalue reference to value_type, named requirements above are violated and the program can be ill-formed.

If the iterator satisfies Forward iterator named requirements from [forward.iterators] ISO C++ Standard section, tbb::parallel_for_each requires the execution of the body with an object of type reference to be well-formed.

Requirements for Body with feeder argument

Additional elements submitted into tbb::parallel_for_each through the feeder::add passes to the Body as rvalues and therefore the corresponding execution of the Body is required to be well-formed.