From 2d2e15aa45104c7062490d301992e27a7eb33564 Mon Sep 17 00:00:00 2001 From: "Epanchinzeva, Alexandra" Date: Tue, 5 Sep 2023 14:10:22 +0200 Subject: [PATCH 1/9] Improve oneTBB type & named requirements --- .../source/algorithms/functions/feeder.rst | 5 +++- .../functions/parallel_for_each_func.rst | 5 +++- .../functions/parallel_reduce_func.rst | 2 ++ .../functions/parallel_scan_func.rst | 2 ++ .../algorithms/blocked_range_val.rst | 6 ++-- .../algorithms/filter_body.rst | 4 +-- .../algorithms/par_for_index.rst | 30 ++++++++++++++----- 7 files changed, 39 insertions(+), 15 deletions(-) diff --git a/source/elements/oneTBB/source/algorithms/functions/feeder.rst b/source/elements/oneTBB/source/algorithms/functions/feeder.rst index 93a093ff23..dc2a73f72d 100644 --- a/source/elements/oneTBB/source/algorithms/functions/feeder.rst +++ b/source/elements/oneTBB/source/algorithms/functions/feeder.rst @@ -33,10 +33,13 @@ Member functions Adds item to a collection of work items to be processed. + **Requirements**: The ``Item`` type must meet the `CopyConstructible` requirements from the [copyconstructible] section of the ISO C++ Standard. + .. cpp:function:: void add( Item&& item ) Same as the above but uses the move constructor of ``Item``, if available. - + + **Requirements**: The ``Item`` type must meet the `MoveConstructible` requirements from the [moveconstructible] section of the ISO C++ Standard. .. caution:: diff --git a/source/elements/oneTBB/source/algorithms/functions/parallel_for_each_func.rst b/source/elements/oneTBB/source/algorithms/functions/parallel_for_each_func.rst index f6712c3644..3c7186bdba 100644 --- a/source/elements/oneTBB/source/algorithms/functions/parallel_for_each_func.rst +++ b/source/elements/oneTBB/source/algorithms/functions/parallel_for_each_func.rst @@ -37,8 +37,11 @@ Function template that processes work items in parallel. Requirements: * The ``Body`` type must meet the :doc:`ParallelForEachBody requirements <../../named_requirements/algorithms/par_for_each_body>`. -* The ``InputIterator`` type must meet the `Input Iterator` requirements from the [input.iterators] ISO C++ Standard section. +* The ``InputIterator`` type must meet the `Input Iterator` requirements from the [input.iterators]section of the ISO C++ Standard. * The ``Container`` type must meet the :doc:`ContainerBasedSequence requirements <../../named_requirements/algorithms/container_based_sequence>`. +* If ``InputIterator`` type does not meet the `Forward Iterator` requirements from the [forward.iterators] section of the ISO C++ Standard, + the ``std::iterator_traits::value_type`` type must constructible from ``std::iterator_traits::reference``. +* ``decltype(std::declval().begin())`` must meet the `Input Iterator` requirements from the [input.iterators] section of the ISO C++ Standard. The ``parallel_for_each`` template has two forms. diff --git a/source/elements/oneTBB/source/algorithms/functions/parallel_reduce_func.rst b/source/elements/oneTBB/source/algorithms/functions/parallel_reduce_func.rst index 927cb656c0..728972ef09 100644 --- a/source/elements/oneTBB/source/algorithms/functions/parallel_reduce_func.rst +++ b/source/elements/oneTBB/source/algorithms/functions/parallel_reduce_func.rst @@ -50,6 +50,8 @@ Requirements: * The ``Range`` type must meet the :doc:`Range requirements <../../named_requirements/algorithms/range>`. * The ``Body`` type must meet the :doc:`ParallelReduceBody requirements <../../named_requirements/algorithms/par_reduce_body>`. +* The ``Value`` type must meet the `CopyConstructible` requirements from the [copyconstructible] section and + `CopyAssignable` requirements from the [copyassignable] section of the ISO C++ Standard. * The ``Func`` type must meet the :doc:`ParallelReduceFunc requirements <../../named_requirements/algorithms/par_reduce_func>`. * The ``Reduction`` types must meet :doc:`ParallelReduceReduction requirements <../../named_requirements/algorithms/par_reduce_reduction>`. diff --git a/source/elements/oneTBB/source/algorithms/functions/parallel_scan_func.rst b/source/elements/oneTBB/source/algorithms/functions/parallel_scan_func.rst index 1054a1f0cb..b8cadad9fe 100644 --- a/source/elements/oneTBB/source/algorithms/functions/parallel_scan_func.rst +++ b/source/elements/oneTBB/source/algorithms/functions/parallel_scan_func.rst @@ -32,6 +32,8 @@ Requirements: * The ``Range`` type must meet the :doc:`Range requirement <../../named_requirements/algorithms/range>`. * The ``Body`` type must meet the :doc:`ParallelScanBody requirements <../../named_requirements/algorithms/par_scan_body>`. +* The ``Value`` type must meet the `CopyConstructible` requirements from the [copyconstructible] section and + `CopyAssignable` requirements from the [copyassignable] section of the ISO C++ Standard. * The ``Scan`` type must meet the :doc:`ParallelScanFunc requirements <../../named_requirements/algorithms/par_scan_func>`. * The ``Combine`` type must meet the :doc:`ParallelScanCombine requirements <../../named_requirements/algorithms/par_scan_combine>`. diff --git a/source/elements/oneTBB/source/named_requirements/algorithms/blocked_range_val.rst b/source/elements/oneTBB/source/named_requirements/algorithms/blocked_range_val.rst index afb1d78a65..d24a3781c2 100644 --- a/source/elements/oneTBB/source/named_requirements/algorithms/blocked_range_val.rst +++ b/source/elements/oneTBB/source/named_requirements/algorithms/blocked_range_val.rst @@ -31,15 +31,15 @@ A type `Value` satisfies `BlockedRangeValue` if it meets the following requireme ``operator=`` is not required to return a value. The actual ``operator=`` can return a value, which will be ignored by ``blocked_range`` . -.. cpp:function:: bool operator<( const Value& i, const Value& j ) +.. cpp:function:: friend bool operator<( const Value& i, const Value& j ) Value *i* precedes value *j*. -.. cpp:function:: D operator-( const Value& i, const Value& j ) +.. cpp:function:: friend D operator-( const Value& i, const Value& j ) Number of values in range ``[i,j)``. -.. cpp:function:: Value operator+( const Value& i, D k ) +.. cpp:function:: friend Value operator+( const Value& i, D k ) *k*-th value after *i*. diff --git a/source/elements/oneTBB/source/named_requirements/algorithms/filter_body.rst b/source/elements/oneTBB/source/named_requirements/algorithms/filter_body.rst index e3326ae841..9813fa76e5 100644 --- a/source/elements/oneTBB/source/named_requirements/algorithms/filter_body.rst +++ b/source/elements/oneTBB/source/named_requirements/algorithms/filter_body.rst @@ -25,7 +25,7 @@ A type `Body` should meet one of the following requirements depending on the fil .. namespace:: FirstFilterBody -.. cpp:function:: OutputType Body::operator()( oneapi::tbb::flow_control fc ) const +.. cpp:function:: OutputType Body::operator()( oneapi::tbb::flow_control& fc ) const Returns the next item from an input stream. Calls ``fc.stop()`` at the end of an input stream. @@ -45,7 +45,7 @@ A type `Body` should meet one of the following requirements depending on the fil .. namespace:: SingleFilterBody -.. cpp:function:: void Body::operator()( oneapi::tbb::flow_control fc ) const +.. cpp:function:: void Body::operator()( oneapi::tbb::flow_control& fc ) const Processes an element from an input stream. Calls ``fc.stop()`` at the end of an input stream. diff --git a/source/elements/oneTBB/source/named_requirements/algorithms/par_for_index.rst b/source/elements/oneTBB/source/named_requirements/algorithms/par_for_index.rst index e166b526f6..1213aa2038 100644 --- a/source/elements/oneTBB/source/named_requirements/algorithms/par_for_index.rst +++ b/source/elements/oneTBB/source/named_requirements/algorithms/par_for_index.rst @@ -25,28 +25,42 @@ A type `Index` satisfies `ParallelForIndex` if it meets the following requiremen Destructor. -.. cpp:function:: void operator=( const Index& ) +.. cpp:function:: Index& operator=( const Index& ) Assignment. - .. note:: +.. cpp:function:: Index& operator++() - The return type ``void`` in the pseudo-signature denotes that - ``operator=`` is not required to return a value. The actual ``operator=`` - can return a value, which will be ignored. + Adjust ``*this`` to the next value. -.. cpp:function:: bool operator<( const Index& i, const Index& j ) +.. cpp:function:: friend bool operator<( const Index& i, const Index& j ) Value of *i* precedes value of *j*. -.. cpp:function:: D operator-( const Index& i, const Index& j ) +.. cpp:function:: friend bool operator<=( const Index& i, const Index& j ) + + Value of *i* precedes or equal to the value of *j*. + +.. cpp:function:: friend D operator-( const Index& i, const Index& j ) Number of values in range ``[i,j)``. -.. cpp:function:: Index operator+( const Index& i, D k ) +.. cpp:function:: friend Index operator+( const Index& i, const Index& j ) + + Sum of *i* and *j* values. + +.. cpp:function:: friend Index operator+( const Index& i, D k ) *k*-th value after *i*. +.. cpp:function:: friend Index operator*( const Index& i, const Index& j ) + + Multiplication of *i* and *j* values. + +.. cpp:function:: friend Index operator/( const Index& i, const Index& j ) + + Quotient of *i* and *j* values. + ``D`` is the type of the expression ``j-i``. It can be any integral type that is convertible to ``size_t``. Examples that model the Index requirements are integral types and pointers. From 5ee4d46d603232cc12c42ca57c1f7a8b88f6f0a2 Mon Sep 17 00:00:00 2001 From: Alexandra Date: Tue, 5 Sep 2023 14:12:21 +0200 Subject: [PATCH 2/9] Update parallel_for_each_func.rst --- .../source/algorithms/functions/parallel_for_each_func.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/elements/oneTBB/source/algorithms/functions/parallel_for_each_func.rst b/source/elements/oneTBB/source/algorithms/functions/parallel_for_each_func.rst index 3c7186bdba..c97232e091 100644 --- a/source/elements/oneTBB/source/algorithms/functions/parallel_for_each_func.rst +++ b/source/elements/oneTBB/source/algorithms/functions/parallel_for_each_func.rst @@ -40,7 +40,7 @@ Requirements: * The ``InputIterator`` type must meet the `Input Iterator` requirements from the [input.iterators]section of the ISO C++ Standard. * The ``Container`` type must meet the :doc:`ContainerBasedSequence requirements <../../named_requirements/algorithms/container_based_sequence>`. * If ``InputIterator`` type does not meet the `Forward Iterator` requirements from the [forward.iterators] section of the ISO C++ Standard, - the ``std::iterator_traits::value_type`` type must constructible from ``std::iterator_traits::reference``. + the ``std::iterator_traits::value_type`` type must be constructible from ``std::iterator_traits::reference``. * ``decltype(std::declval().begin())`` must meet the `Input Iterator` requirements from the [input.iterators] section of the ISO C++ Standard. The ``parallel_for_each`` template has two forms. From ed4b8257889ccdea8aa5a502c728bbd809a9a8ca Mon Sep 17 00:00:00 2001 From: kboyarinov Date: Wed, 1 Nov 2023 13:18:40 +0200 Subject: [PATCH 3/9] Fix named requirements for parallel_for_each, remove confusing friend in pseudo-signature --- .../functions/parallel_for_each_func.rst | 4 ++-- .../algorithms/blocked_range_val.rst | 8 ++++---- .../algorithms/par_for_index.rst | 14 +++++++------- 3 files changed, 13 insertions(+), 13 deletions(-) diff --git a/source/elements/oneTBB/source/algorithms/functions/parallel_for_each_func.rst b/source/elements/oneTBB/source/algorithms/functions/parallel_for_each_func.rst index c97232e091..782fc8de91 100644 --- a/source/elements/oneTBB/source/algorithms/functions/parallel_for_each_func.rst +++ b/source/elements/oneTBB/source/algorithms/functions/parallel_for_each_func.rst @@ -37,11 +37,11 @@ Function template that processes work items in parallel. Requirements: * The ``Body`` type must meet the :doc:`ParallelForEachBody requirements <../../named_requirements/algorithms/par_for_each_body>`. -* The ``InputIterator`` type must meet the `Input Iterator` requirements from the [input.iterators]section of the ISO C++ Standard. +* The ``InputIterator`` type must meet the `Input Iterator` requirements from the [input.iterators] section of the ISO C++ Standard. * The ``Container`` type must meet the :doc:`ContainerBasedSequence requirements <../../named_requirements/algorithms/container_based_sequence>`. * If ``InputIterator`` type does not meet the `Forward Iterator` requirements from the [forward.iterators] section of the ISO C++ Standard, the ``std::iterator_traits::value_type`` type must be constructible from ``std::iterator_traits::reference``. -* ``decltype(std::declval().begin())`` must meet the `Input Iterator` requirements from the [input.iterators] section of the ISO C++ Standard. +* ``decltype(std::declval().begin())`` must meet the same requirements as the `Input Iterator` type. The ``parallel_for_each`` template has two forms. diff --git a/source/elements/oneTBB/source/named_requirements/algorithms/blocked_range_val.rst b/source/elements/oneTBB/source/named_requirements/algorithms/blocked_range_val.rst index d24a3781c2..8be8b2d896 100644 --- a/source/elements/oneTBB/source/named_requirements/algorithms/blocked_range_val.rst +++ b/source/elements/oneTBB/source/named_requirements/algorithms/blocked_range_val.rst @@ -24,22 +24,22 @@ A type `Value` satisfies `BlockedRangeValue` if it meets the following requireme .. cpp:function:: void operator=( const Value& ) Assignment. - + .. note:: The return type ``void`` in the pseudo-signature denotes that ``operator=`` is not required to return a value. The actual ``operator=`` can return a value, which will be ignored by ``blocked_range`` . -.. cpp:function:: friend bool operator<( const Value& i, const Value& j ) +.. cpp:function:: bool operator<( const Value& i, const Value& j ) Value *i* precedes value *j*. -.. cpp:function:: friend D operator-( const Value& i, const Value& j ) +.. cpp:function:: D operator-( const Value& i, const Value& j ) Number of values in range ``[i,j)``. -.. cpp:function:: friend Value operator+( const Value& i, D k ) +.. cpp:function:: Value operator+( const Value& i, D k ) *k*-th value after *i*. diff --git a/source/elements/oneTBB/source/named_requirements/algorithms/par_for_index.rst b/source/elements/oneTBB/source/named_requirements/algorithms/par_for_index.rst index 1213aa2038..93e00464af 100644 --- a/source/elements/oneTBB/source/named_requirements/algorithms/par_for_index.rst +++ b/source/elements/oneTBB/source/named_requirements/algorithms/par_for_index.rst @@ -33,31 +33,31 @@ A type `Index` satisfies `ParallelForIndex` if it meets the following requiremen Adjust ``*this`` to the next value. -.. cpp:function:: friend bool operator<( const Index& i, const Index& j ) +.. cpp:function:: bool operator<( const Index& i, const Index& j ) Value of *i* precedes value of *j*. -.. cpp:function:: friend bool operator<=( const Index& i, const Index& j ) +.. cpp:function:: bool operator<=( const Index& i, const Index& j ) Value of *i* precedes or equal to the value of *j*. -.. cpp:function:: friend D operator-( const Index& i, const Index& j ) +.. cpp:function:: D operator-( const Index& i, const Index& j ) Number of values in range ``[i,j)``. -.. cpp:function:: friend Index operator+( const Index& i, const Index& j ) +.. cpp:function:: Index operator+( const Index& i, const Index& j ) Sum of *i* and *j* values. -.. cpp:function:: friend Index operator+( const Index& i, D k ) +.. cpp:function:: Index operator+( const Index& i, D k ) *k*-th value after *i*. -.. cpp:function:: friend Index operator*( const Index& i, const Index& j ) +.. cpp:function:: Index operator*( const Index& i, const Index& j ) Multiplication of *i* and *j* values. -.. cpp:function:: friend Index operator/( const Index& i, const Index& j ) +.. cpp:function:: Index operator/( const Index& i, const Index& j ) Quotient of *i* and *j* values. From 5a94fffdb2c02010bbdb830ae1411760bd325f0e Mon Sep 17 00:00:00 2001 From: kboyarinov Date: Wed, 1 Nov 2023 13:21:27 +0200 Subject: [PATCH 4/9] Remove unnecessary whitespace --- .../source/named_requirements/algorithms/blocked_range_val.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/source/elements/oneTBB/source/named_requirements/algorithms/blocked_range_val.rst b/source/elements/oneTBB/source/named_requirements/algorithms/blocked_range_val.rst index 8be8b2d896..2d82cfb65c 100644 --- a/source/elements/oneTBB/source/named_requirements/algorithms/blocked_range_val.rst +++ b/source/elements/oneTBB/source/named_requirements/algorithms/blocked_range_val.rst @@ -24,7 +24,6 @@ A type `Value` satisfies `BlockedRangeValue` if it meets the following requireme .. cpp:function:: void operator=( const Value& ) Assignment. - .. note:: The return type ``void`` in the pseudo-signature denotes that From a2af1761a26d83c85e6a6d46df74c0dd800dcd6b Mon Sep 17 00:00:00 2001 From: kboyarinov Date: Wed, 1 Nov 2023 13:25:26 +0200 Subject: [PATCH 5/9] Discard changes in blocked range value --- .../source/named_requirements/algorithms/blocked_range_val.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/source/elements/oneTBB/source/named_requirements/algorithms/blocked_range_val.rst b/source/elements/oneTBB/source/named_requirements/algorithms/blocked_range_val.rst index 2d82cfb65c..afb1d78a65 100644 --- a/source/elements/oneTBB/source/named_requirements/algorithms/blocked_range_val.rst +++ b/source/elements/oneTBB/source/named_requirements/algorithms/blocked_range_val.rst @@ -24,6 +24,7 @@ A type `Value` satisfies `BlockedRangeValue` if it meets the following requireme .. cpp:function:: void operator=( const Value& ) Assignment. + .. note:: The return type ``void`` in the pseudo-signature denotes that From a2fd167e85c6e2dc1ad669d03d53a81f221609f5 Mon Sep 17 00:00:00 2001 From: kboyarinov Date: Wed, 1 Nov 2023 19:22:45 +0200 Subject: [PATCH 6/9] Rephrase the container.begin() part --- .../source/algorithms/functions/parallel_for_each_func.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/elements/oneTBB/source/algorithms/functions/parallel_for_each_func.rst b/source/elements/oneTBB/source/algorithms/functions/parallel_for_each_func.rst index 782fc8de91..677e01ad9e 100644 --- a/source/elements/oneTBB/source/algorithms/functions/parallel_for_each_func.rst +++ b/source/elements/oneTBB/source/algorithms/functions/parallel_for_each_func.rst @@ -41,7 +41,7 @@ Requirements: * The ``Container`` type must meet the :doc:`ContainerBasedSequence requirements <../../named_requirements/algorithms/container_based_sequence>`. * If ``InputIterator`` type does not meet the `Forward Iterator` requirements from the [forward.iterators] section of the ISO C++ Standard, the ``std::iterator_traits::value_type`` type must be constructible from ``std::iterator_traits::reference``. -* ``decltype(std::declval().begin())`` must meet the same requirements as the `Input Iterator` type. +* The type returned by ``Container::begin()`` must meet the same requirements as the ``InputIterator`` type above. The ``parallel_for_each`` template has two forms. From cdcea475988e43c46d6c8b02682aa31c22a3ea9d Mon Sep 17 00:00:00 2001 From: kboyarinov Date: Wed, 1 Nov 2023 19:25:31 +0200 Subject: [PATCH 7/9] Reorder requirements --- .../source/algorithms/functions/parallel_for_each_func.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/elements/oneTBB/source/algorithms/functions/parallel_for_each_func.rst b/source/elements/oneTBB/source/algorithms/functions/parallel_for_each_func.rst index 677e01ad9e..713271b038 100644 --- a/source/elements/oneTBB/source/algorithms/functions/parallel_for_each_func.rst +++ b/source/elements/oneTBB/source/algorithms/functions/parallel_for_each_func.rst @@ -38,9 +38,9 @@ Requirements: * The ``Body`` type must meet the :doc:`ParallelForEachBody requirements <../../named_requirements/algorithms/par_for_each_body>`. * The ``InputIterator`` type must meet the `Input Iterator` requirements from the [input.iterators] section of the ISO C++ Standard. -* The ``Container`` type must meet the :doc:`ContainerBasedSequence requirements <../../named_requirements/algorithms/container_based_sequence>`. * If ``InputIterator`` type does not meet the `Forward Iterator` requirements from the [forward.iterators] section of the ISO C++ Standard, the ``std::iterator_traits::value_type`` type must be constructible from ``std::iterator_traits::reference``. +* The ``Container`` type must meet the :doc:`ContainerBasedSequence requirements <../../named_requirements/algorithms/container_based_sequence>`. * The type returned by ``Container::begin()`` must meet the same requirements as the ``InputIterator`` type above. The ``parallel_for_each`` template has two forms. From 6831e0c8be02002b8ade9fb93451e4312958c0d8 Mon Sep 17 00:00:00 2001 From: kboyarinov Date: Thu, 2 Nov 2023 18:35:52 +0200 Subject: [PATCH 8/9] Add recomendation to use integral types as index for parallel for --- .../source/named_requirements/algorithms/par_for_index.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/source/elements/oneTBB/source/named_requirements/algorithms/par_for_index.rst b/source/elements/oneTBB/source/named_requirements/algorithms/par_for_index.rst index 93e00464af..bc0ecbe9e5 100644 --- a/source/elements/oneTBB/source/named_requirements/algorithms/par_for_index.rst +++ b/source/elements/oneTBB/source/named_requirements/algorithms/par_for_index.rst @@ -64,6 +64,9 @@ A type `Index` satisfies `ParallelForIndex` if it meets the following requiremen ``D`` is the type of the expression ``j-i``. It can be any integral type that is convertible to ``size_t``. Examples that model the Index requirements are integral types and pointers. +**_NOTE:_** It is recommended to use integral types as ``ParallelForIndex``. See ``[basic.fundamental]`` +ISO C++ Standard section for information about integral types. + See also: * :doc:`parallel_for algorithm <../../algorithms/functions/parallel_for_func>` From ce38f30328f22409a9b83d4ccf723712584a20a6 Mon Sep 17 00:00:00 2001 From: Konstantin Boyarinov Date: Thu, 2 Nov 2023 19:54:48 +0200 Subject: [PATCH 9/9] Update source/elements/oneTBB/source/named_requirements/algorithms/par_for_index.rst Co-authored-by: Alexey Kukanov --- .../source/named_requirements/algorithms/par_for_index.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/elements/oneTBB/source/named_requirements/algorithms/par_for_index.rst b/source/elements/oneTBB/source/named_requirements/algorithms/par_for_index.rst index bc0ecbe9e5..6b9f1c3e13 100644 --- a/source/elements/oneTBB/source/named_requirements/algorithms/par_for_index.rst +++ b/source/elements/oneTBB/source/named_requirements/algorithms/par_for_index.rst @@ -64,8 +64,8 @@ A type `Index` satisfies `ParallelForIndex` if it meets the following requiremen ``D`` is the type of the expression ``j-i``. It can be any integral type that is convertible to ``size_t``. Examples that model the Index requirements are integral types and pointers. -**_NOTE:_** It is recommended to use integral types as ``ParallelForIndex``. See ``[basic.fundamental]`` -ISO C++ Standard section for information about integral types. +**_NOTE:_** It is recommended to use integral types as ``ParallelForIndex``. See the ``[basic.fundamental]`` +section of the ISO C++ Standard for information about integral types. See also: