From 162fed2a4d0c6bcdb00526143d041ad58e5753cd Mon Sep 17 00:00:00 2001 From: Alexey Kukanov Date: Fri, 19 Sep 2025 15:24:37 +0200 Subject: [PATCH 01/11] Clarify the use of pseudo-signatures --- .../oneTBB/source/named_requirements.rst | 24 +++++++++++++------ 1 file changed, 17 insertions(+), 7 deletions(-) diff --git a/source/elements/oneTBB/source/named_requirements.rst b/source/elements/oneTBB/source/named_requirements.rst index e134f6fd19..b3e62c16fa 100644 --- a/source/elements/oneTBB/source/named_requirements.rst +++ b/source/elements/oneTBB/source/named_requirements.rst @@ -22,9 +22,14 @@ an array to be sorted. A type ``T`` would be *sortable* if: You can write a sorting template function in C++ that sorts an array of any type that is *sortable*. +.. _pseudo_signatures: + +Pseudo-Signatures +----------------- + Two approaches for defining named requirements are *valid expressions* and *pseudo-signatures*. The ISO C++ standard follows the valid *expressions* approach, which shows what the usage pattern looks like for a requirement. -It has the drawback of relegating important details to notational conventions. This document uses +It has the drawback of relegating important details to notational conventions. This document mostly uses pseudo-signatures because they are concise and can be cut-and-pasted for an initial implementation. For example, the table below shows pseudo-signatures for a *sortable* type ``T``: @@ -43,12 +48,18 @@ For example, the table below shows pseudo-signatures for a *sortable* type ``T`` --------------------------------------------------------------------------------------------- +A pseudo-signature describes how an implementation interacts with a type or a function. A real signature may differ from the pseudo-signature that it implements in ways where implicit -conversions would deal with the difference. For an example type ``U``, the real signature that -implements ``operator<`` in the table above can be expressed as ``int operator<( U x, U y )``, -because C++ permits implicit conversion from ``int`` to ``bool``, and implicit conversion from ``U`` -to (``const U&``). Similarly, the real signature ``bool operator<( U& x, U& y )`` is acceptable -because C++ permits implicit addition of a const qualifier to a reference type. +conversions would deal with the difference: function parameters need to implicitly convert +from the ones in the pseudo-signature, and return value needs to implicitly convert to the one +in the pseudo-signature. + +For an example type ``U``, the real signature that implements ``operator<`` in the table above +can be expressed as ``int operator<( U x, U y )``, because C++ permits implicit conversion from +``int`` to ``bool``, and implicit conversion from ``const U&`` to ``U`` if the type is copyable. +For a counter-example, the real signature ``bool operator<( U& x, U& y )`` is not acceptable +because C++ does not permit implicit removal of a const qualifier from a type, and so the code +would not compile if the implementation attempts to pass a const object to the function. Algorithms ---------- @@ -81,7 +92,6 @@ Mutexes Containers ---------- - .. toctree:: :titlesonly: From b2431ceb335c8f68f87edeab92064048997d85be Mon Sep 17 00:00:00 2001 From: Alexey Kukanov Date: Fri, 19 Sep 2025 15:27:09 +0200 Subject: [PATCH 02/11] Simplify the definition of ParallelForEachBody requirements --- .../algorithms/par_for_each_body.rst | 42 ++++++------------- 1 file changed, 12 insertions(+), 30 deletions(-) diff --git a/source/elements/oneTBB/source/named_requirements/algorithms/par_for_each_body.rst b/source/elements/oneTBB/source/named_requirements/algorithms/par_for_each_body.rst index 8abfcbb498..10fe95dc20 100644 --- a/source/elements/oneTBB/source/named_requirements/algorithms/par_for_each_body.rst +++ b/source/elements/oneTBB/source/named_requirements/algorithms/par_for_each_body.rst @@ -15,46 +15,28 @@ It should also meet one of the following requirements: **ParallelForEachBody Requirements: Pseudo-Signature, Semantics** -.. cpp:function:: Body::operator()( ItemType item ) const +.. cpp:function:: void Body::operator()( ReferenceType item ) const Process the received item. -.. cpp:function:: Body::operator()( ItemType item, oneapi::tbb::feeder& feeder ) const +.. cpp:function:: void Body::operator()( ItemType&& item, oneapi::tbb::feeder& feeder ) const - Process the received item. May invoke the ``feeder.add(T)`` function to spawn additional items. + Process the received item. May invoke the ``feeder.add`` function to spawn additional items. ----------------------------------------------------------------- -.. note:: - - ``ItemType`` may be optionally passed to ``Body::operator()`` by reference. - ``const`` and ``volatile`` type qualifiers are also applicable. - -Terms ------ - -* ``iterator`` determines the type of the iterator passed into the ``parallel_for_each`` algorithm, - which is ``decltype(std::begin(c))`` for the overloads that accept the ``Container`` template argument or ``InputIterator``. -* ``value_type`` - the type ``std::iterator_traits::value_type``. -* ``reference`` - the type ``std::iterator_traits::reference``. +where ``ItemType`` is ``std::iterator_traits::value_type`` for the type of the iterator +the ``parallel_for_each`` algorithm operates with, and ``ReferenceType`` is -``oneapi::tbb::parallel_for_each`` requires the ``Body::operator()`` call with an object of the ``reference`` type to be well-formed if -the ``iterator`` meets the `Forward iterator` requirements described in the [forward.iterators] section of the -ISO C++ Standard. +* ``std::iterator_traits::reference`` if the iterator type is a forward iterator + as described in the [forward.iterators] section of the ISO C++ Standard; +* otherwise, ``ItemType&&``. -`oneapi::tbb::parallel_for_each algorithm <../../algorithms/functions/parallel_for_each_func>`_ -requires the ``Body::operator()`` call with an object of type ``const value_type&`` or ``value_type&&`` to be well-formed if following requirements are met: - -* the iterator meets the `Input iterator` requirements described in the [input.iterators] section of the ISO C++ Standard -* the iterator does not meet the `Forward iterator` requirements described in the [forward.iterators] section of the ISO C++ Standard - -.. caution:: - - If the ``Body`` only takes non-const lvalue reference to the ``value_type``, the requirements described above - are violated, and the program can be ill-formed. +.. note:: -Additional elements submitted into ``oneapi::tbb::parallel_for_each`` through the ``feeder::add`` are passed to the ``Body`` as rvalues. In this case, the corresponding -execution of the ``Body`` is required to be well-formed. + The usual rules for :ref:`pseudo-signatures ` apply. + Therefore, ``Body::operator()`` may optionally take ``ItemType`` by value. + ``const`` and ``volatile`` type qualifiers are also applicable. See also: From 2c5ebc0a19e2200d02a414c4cbcef6a046a88a8f Mon Sep 17 00:00:00 2001 From: Alexey Kukanov Date: Fri, 19 Sep 2025 15:32:41 +0200 Subject: [PATCH 03/11] Improve the definition of ContainerBasedSequence --- .../functions/parallel_for_each_func.rst | 3 ++- .../algorithms/container_based_sequence.rst | 18 ++++++++++-------- 2 files changed, 12 insertions(+), 9 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 0469c277b5..534aae0733 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 @@ -42,7 +42,8 @@ Requirements: * 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 type returned by ``std::begin`` and ``std::end`` applied to a ``Container`` object + must meet the same requirements as the ``InputIterator`` type above. The ``parallel_for_each`` template has two forms. diff --git a/source/elements/oneTBB/source/named_requirements/algorithms/container_based_sequence.rst b/source/elements/oneTBB/source/named_requirements/algorithms/container_based_sequence.rst index e46490e274..b68c36fda0 100644 --- a/source/elements/oneTBB/source/named_requirements/algorithms/container_based_sequence.rst +++ b/source/elements/oneTBB/source/named_requirements/algorithms/container_based_sequence.rst @@ -7,17 +7,12 @@ ContainerBasedSequence ====================== **[req.container_based_sequence]** -A type `C` satisfies `ContainerBasedSequence` if it meets the following requirements: +A type `C` satisfies `ContainerBasedSequence` if the following expressions are valid +for an object ``c`` of type (possibly ``const``) ``C``: ---------------------------------------------------------------- -**ContainerBasedSequence Requirements: Pseudo-Signature, Semantics** - - .. note:: - - In this page ``c`` is an object of type (possibly ``const``) ``C``. - - Templates that use the named requirement can impose stricter requirements on the iterator concept. +**ContainerBasedSequence Requirements: Expression, Semantics** .. cpp:function:: std::begin(c) @@ -27,6 +22,13 @@ A type `C` satisfies `ContainerBasedSequence` if it meets the following requirem Returns an input iterator one past the end of the sequence represented by ``c``. +---------------------------------------------------------------- + +.. note:: + + Templates that use ``ContainerBasedSequence`` may impose stricter requirements on the iterator type + returned by ``std::begin``/``std::end``. + See also: * :doc:`parallel_for_each algorithm <../../algorithms/functions/parallel_for_each_func>` From f0cc3091de16d6c84fe6e73094f754c303200ef4 Mon Sep 17 00:00:00 2001 From: Alexey Kukanov Date: Mon, 6 Oct 2025 16:08:06 +0200 Subject: [PATCH 04/11] Address the review feedback Co-authored-by: Ruslan Arutyunyan --- .../oneTBB/source/named_requirements.rst | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) diff --git a/source/elements/oneTBB/source/named_requirements.rst b/source/elements/oneTBB/source/named_requirements.rst index b3e62c16fa..b0d8af7765 100644 --- a/source/elements/oneTBB/source/named_requirements.rst +++ b/source/elements/oneTBB/source/named_requirements.rst @@ -10,9 +10,9 @@ Named Requirements This section describes named requirements used in the oneTBB Specification. A *named requirement* is a set of requirements on a type. The requirements may be syntactic or semantic. -The *named_requirement* term is similar to “Requirements on types and expressions” term which is defined -by the ISO C++ Standard (chapter “Library Introduction”) or `“Named Requirements” section `_ -on the cppreference.com site. +The *named requirement* term is similar to “Requirements on types and expressions” term which is defined +by the ISO C++ Standard (chapter “Library Introduction”) or +`“Named Requirements” section `_ on the cppreference.com site. For example, the named requirement of *sortable* could be defined as a set of requirements that enable an array to be sorted. A type ``T`` would be *sortable* if: @@ -49,16 +49,17 @@ For example, the table below shows pseudo-signatures for a *sortable* type ``T`` --------------------------------------------------------------------------------------------- A pseudo-signature describes how an implementation interacts with a type or a function. -A real signature may differ from the pseudo-signature that it implements in ways where implicit -conversions would deal with the difference: function parameters need to implicitly convert -from the ones in the pseudo-signature, and return value needs to implicitly convert to the one +A real signature (after template instantiation, if applicable) may differ from the pseudo-signature +that it implements in ways where implicit +conversions would deal with the difference: its function parameter types need to implicitly convert +from the ones in the pseudo-signature, and the return value type needs to implicitly convert to the one in the pseudo-signature. For an example type ``U``, the real signature that implements ``operator<`` in the table above can be expressed as ``int operator<( U x, U y )``, because C++ permits implicit conversion from -``int`` to ``bool``, and implicit conversion from ``const U&`` to ``U`` if the type is copyable. +``int`` to ``bool``, and implicit conversion from ``const U&`` to ``U`` if the type is copy-constructible. For a counter-example, the real signature ``bool operator<( U& x, U& y )`` is not acceptable -because C++ does not permit implicit removal of a const qualifier from a type, and so the code +because C++ does not permit implicit removal of a ``const`` qualifier from a type, and so the code would not compile if the implementation attempts to pass a const object to the function. Algorithms From 68826e1519cacc12991e695417b78e17760c4e91 Mon Sep 17 00:00:00 2001 From: Alexey Kukanov Date: Fri, 17 Oct 2025 12:03:37 +0200 Subject: [PATCH 05/11] Update the named requirements for reductions to work with rvalues --- .../algorithms/par_reduce_func.rst | 12 ++++++------ .../algorithms/par_reduce_reduction.rst | 8 ++++---- 2 files changed, 10 insertions(+), 10 deletions(-) diff --git a/source/elements/oneTBB/source/named_requirements/algorithms/par_reduce_func.rst b/source/elements/oneTBB/source/named_requirements/algorithms/par_reduce_func.rst index 8845dfd771..e2bb6c885f 100644 --- a/source/elements/oneTBB/source/named_requirements/algorithms/par_reduce_func.rst +++ b/source/elements/oneTBB/source/named_requirements/algorithms/par_reduce_func.rst @@ -5,7 +5,7 @@ ================== ParallelReduceFunc ================== -**[req.parallel_reduce_body]** +**[req.parallel_reduce_func]** A type `Func` satisfies `ParallelReduceFunc` if it meets the following requirements: @@ -13,12 +13,12 @@ A type `Func` satisfies `ParallelReduceFunc` if it meets the following requireme **ParallelReduceFunc Requirements: Pseudo-Signature, Semantics** -.. cpp:function:: Value Func::operator()(const Range& range, const Value& x) const +.. cpp:function:: Value Func::operator()(const Range& range, Value&& x) const - Accumulates result for a subrange, starting with initial value ``x``. - ``Range`` type must meet the :doc:`Range requirements `. - ``Value`` type must be the same as a corresponding template parameter for the - :doc:`parallel_reduce algorithm <../../algorithms/functions/parallel_reduce_func>` algorithm. + Accumulates values over a subrange, starting with the initial value ``x``. + The ``Range`` type must meet the :doc:`Range requirements `. + The ``Value`` type must be the same as the corresponding template parameter for the + :doc:`parallel_reduce algorithm <../../algorithms/functions/parallel_reduce_func>`. See also: diff --git a/source/elements/oneTBB/source/named_requirements/algorithms/par_reduce_reduction.rst b/source/elements/oneTBB/source/named_requirements/algorithms/par_reduce_reduction.rst index c65c34c2c9..71080e6f55 100644 --- a/source/elements/oneTBB/source/named_requirements/algorithms/par_reduce_reduction.rst +++ b/source/elements/oneTBB/source/named_requirements/algorithms/par_reduce_reduction.rst @@ -13,11 +13,11 @@ A type `Reduction` satisfies `ParallelReduceReduction` if it meets the following **ParallelReduceReduction Requirements: Pseudo-Signature, Semantics** -.. cpp:function:: Value Reduction::operator()(const Value& x, const Value& y) const +.. cpp:function:: Value Reduction::operator()(Value&& x, Value&& y) const - Combines results ``x`` and ``y``. - ``Value`` type must be the same as a corresponding template parameter for the - :doc:`parallel_reduce algorithm <../../algorithms/functions/parallel_reduce_func>` algorithm. + Combines the results ``x`` and ``y``. + The ``Value`` type must be the same as the corresponding template parameter for the + :doc:`parallel_reduce algorithm <../../algorithms/functions/parallel_reduce_func>`. See also: From c47c112b4d15a675afa00e1ef74db8a39c7e8370 Mon Sep 17 00:00:00 2001 From: Alexey Kukanov Date: Fri, 17 Oct 2025 12:53:12 +0200 Subject: [PATCH 06/11] Emphasize importance of semantic requirements --- .../oneTBB/source/named_requirements.rst | 27 +++++++++++-------- 1 file changed, 16 insertions(+), 11 deletions(-) diff --git a/source/elements/oneTBB/source/named_requirements.rst b/source/elements/oneTBB/source/named_requirements.rst index b0d8af7765..005a2f999b 100644 --- a/source/elements/oneTBB/source/named_requirements.rst +++ b/source/elements/oneTBB/source/named_requirements.rst @@ -32,6 +32,12 @@ The ISO C++ standard follows the valid *expressions* approach, which shows what It has the drawback of relegating important details to notational conventions. This document mostly uses pseudo-signatures because they are concise and can be cut-and-pasted for an initial implementation. +A pseudo-signature describes how an implementation interacts with a type or a function. +A real function signature (after template instantiation, if applicable) may differ from the pseudo-signature +that it implements in ways where implicit conversions would deal with the difference, +transforming function parameter types from the ones in the pseudo-signature to the real signature, +and transforming the actual return value type to the one in the pseudo-signature. + For example, the table below shows pseudo-signatures for a *sortable* type ``T``: --------------------------------------------------------------------------------------------- @@ -40,27 +46,26 @@ For example, the table below shows pseudo-signatures for a *sortable* type ``T`` .. cpp:function:: bool operator<(const T& x, const T& y) - Compare x and y. + Compare ``x`` and ``y``. .. cpp:function:: void swap(T& x, T& y) - Swap x and y. + Swap ``x`` and ``y``. --------------------------------------------------------------------------------------------- -A pseudo-signature describes how an implementation interacts with a type or a function. -A real signature (after template instantiation, if applicable) may differ from the pseudo-signature -that it implements in ways where implicit -conversions would deal with the difference: its function parameter types need to implicitly convert -from the ones in the pseudo-signature, and the return value type needs to implicitly convert to the one -in the pseudo-signature. - For an example type ``U``, the real signature that implements ``operator<`` in the table above can be expressed as ``int operator<( U x, U y )``, because C++ permits implicit conversion from ``int`` to ``bool``, and implicit conversion from ``const U&`` to ``U`` if the type is copy-constructible. For a counter-example, the real signature ``bool operator<( U& x, U& y )`` is not acceptable -because C++ does not permit implicit removal of a ``const`` qualifier from a type, and so the code -would not compile if the implementation attempts to pass a const object to the function. +because C++ does not permit implicit removal of the ``const`` qualifier from a type, and so the code +would not compile if the implementation attempts to pass a constant object to the function. + +Besides pseudo-signatures, semantic requirements also need to be met by real types and functions. +For example, while ``std::pair swap(U x, U y)`` fits the pseudo-signature for *Sortable* +via implicit conversion of references to values and implicit drop of the returned value +(ignored by a library implementation), it is unable to swap the actual variables passed to the function +and therefore does not meet the semantic requirements of *Sortable*. Algorithms ---------- From a940d5c58eb4b4130fa4db7f57090b9b16cfb212 Mon Sep 17 00:00:00 2001 From: Alexey Kukanov Date: Fri, 17 Oct 2025 13:59:04 +0200 Subject: [PATCH 07/11] Add a second signature for the operator with the feeder --- .../named_requirements/algorithms/par_for_each_body.rst | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/source/elements/oneTBB/source/named_requirements/algorithms/par_for_each_body.rst b/source/elements/oneTBB/source/named_requirements/algorithms/par_for_each_body.rst index 10fe95dc20..da747107d6 100644 --- a/source/elements/oneTBB/source/named_requirements/algorithms/par_for_each_body.rst +++ b/source/elements/oneTBB/source/named_requirements/algorithms/par_for_each_body.rst @@ -19,9 +19,15 @@ It should also meet one of the following requirements: Process the received item. +---------------------------------------------------------------- + +.. cpp:function:: void Body::operator()( ReferenceType item, oneapi::tbb::feeder& feeder ) const + .. cpp:function:: void Body::operator()( ItemType&& item, oneapi::tbb::feeder& feeder ) const Process the received item. May invoke the ``feeder.add`` function to spawn additional items. + + The ``Body::operator()`` must accept both ``ReferenceType`` and ``ItemType&&`` values as the first argument. ----------------------------------------------------------------- From b724eb5b3a4ec97c8375d3c79042c838c7a6017a Mon Sep 17 00:00:00 2001 From: Alexey Kukanov Date: Fri, 17 Oct 2025 17:15:02 +0200 Subject: [PATCH 08/11] Improve formatting --- .../algorithms/par_for_each_body.rst | 24 +++++++++++-------- 1 file changed, 14 insertions(+), 10 deletions(-) diff --git a/source/elements/oneTBB/source/named_requirements/algorithms/par_for_each_body.rst b/source/elements/oneTBB/source/named_requirements/algorithms/par_for_each_body.rst index da747107d6..0d40390332 100644 --- a/source/elements/oneTBB/source/named_requirements/algorithms/par_for_each_body.rst +++ b/source/elements/oneTBB/source/named_requirements/algorithms/par_for_each_body.rst @@ -7,23 +7,26 @@ ParallelForEachBody =================== **[req.parallel_for_each_body]** -A type `Body` satisfies `ParallelForBody` if it meets the `Function Objects` -requirements described in the [function.objects] section of the ISO C++ standard. -It should also meet one of the following requirements: +A type `Body` satisfies `ParallelForEachBody` if it meets the `Function Objects` +requirements described in the [function.objects] section of the ISO C++ standard, +as well as it meets exactly one of the following two requirements for ``operator()``: ---------------------------------------------------------------- **ParallelForEachBody Requirements: Pseudo-Signature, Semantics** +Variant 1: + .. cpp:function:: void Body::operator()( ReferenceType item ) const Process the received item. ---------------------------------------------------------------- -.. cpp:function:: void Body::operator()( ReferenceType item, oneapi::tbb::feeder& feeder ) const +Variant 2: -.. cpp:function:: void Body::operator()( ItemType&& item, oneapi::tbb::feeder& feeder ) const +.. cpp:function:: void Body::operator()( ReferenceType item, oneapi::tbb::feeder& feeder ) const + void Body::operator()( ItemType&& item, oneapi::tbb::feeder& feeder ) const Process the received item. May invoke the ``feeder.add`` function to spawn additional items. @@ -31,12 +34,13 @@ It should also meet one of the following requirements: ----------------------------------------------------------------- -where ``ItemType`` is ``std::iterator_traits::value_type`` for the type of the iterator -the ``parallel_for_each`` algorithm operates with, and ``ReferenceType`` is +where -* ``std::iterator_traits::reference`` if the iterator type is a forward iterator - as described in the [forward.iterators] section of the ISO C++ Standard; -* otherwise, ``ItemType&&``. +* ``ItemType`` is ``std::iterator_traits::value_type`` for the type of the iterator + the ``parallel_for_each`` algorithm operates with, and +* ``ReferenceType`` is``std::iterator_traits::reference`` if the iterator type is a forward iterator + as described in the [forward.iterators] section of the ISO C++ Standard, +* otherwise, ``ReferenceType`` is ``ItemType&&``. .. note:: From 17fdde79a6ebc33fc887e4c72f53a12e37889de2 Mon Sep 17 00:00:00 2001 From: Alexey Kukanov Date: Fri, 17 Oct 2025 18:27:31 +0200 Subject: [PATCH 09/11] Improve formatting --- .../named_requirements/algorithms/par_for_each_body.rst | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/source/elements/oneTBB/source/named_requirements/algorithms/par_for_each_body.rst b/source/elements/oneTBB/source/named_requirements/algorithms/par_for_each_body.rst index 0d40390332..d3dd25d534 100644 --- a/source/elements/oneTBB/source/named_requirements/algorithms/par_for_each_body.rst +++ b/source/elements/oneTBB/source/named_requirements/algorithms/par_for_each_body.rst @@ -29,7 +29,6 @@ Variant 2: void Body::operator()( ItemType&& item, oneapi::tbb::feeder& feeder ) const Process the received item. May invoke the ``feeder.add`` function to spawn additional items. - The ``Body::operator()`` must accept both ``ReferenceType`` and ``ItemType&&`` values as the first argument. ----------------------------------------------------------------- @@ -38,14 +37,14 @@ where * ``ItemType`` is ``std::iterator_traits::value_type`` for the type of the iterator the ``parallel_for_each`` algorithm operates with, and -* ``ReferenceType`` is``std::iterator_traits::reference`` if the iterator type is a forward iterator - as described in the [forward.iterators] section of the ISO C++ Standard, +* ``ReferenceType`` is ``std::iterator_traits::reference`` if the iterator type is + a `forward iterator` as described in the [forward.iterators] section of the ISO C++ Standard, * otherwise, ``ReferenceType`` is ``ItemType&&``. .. note:: The usual rules for :ref:`pseudo-signatures ` apply. - Therefore, ``Body::operator()`` may optionally take ``ItemType`` by value. + Therefore, ``Body::operator()`` may optionally take items by value. ``const`` and ``volatile`` type qualifiers are also applicable. See also: From d5491423b2d060724f7680df3bbc3343b77c9633 Mon Sep 17 00:00:00 2001 From: Alexey Kukanov Date: Fri, 17 Oct 2025 19:23:19 +0200 Subject: [PATCH 10/11] Add a table for parameter mapping --- .../oneTBB/source/named_requirements.rst | 20 +++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/source/elements/oneTBB/source/named_requirements.rst b/source/elements/oneTBB/source/named_requirements.rst index 005a2f999b..5098627a50 100644 --- a/source/elements/oneTBB/source/named_requirements.rst +++ b/source/elements/oneTBB/source/named_requirements.rst @@ -67,6 +67,26 @@ via implicit conversion of references to values and implicit drop of the returne (ignored by a library implementation), it is unable to swap the actual variables passed to the function and therefore does not meet the semantic requirements of *Sortable*. +The following table provides guidance for the types of parameters used in pseudo-signatures. + +================ ================================ ============================= +Pseudo-signature General semantics Alternative real parameters +parameter +================ ================================ ============================= +``const T& x`` The function is not supposed ``T x`` + to modify the argument. ``auto& x`` + ``auto&& x``, forwarding reference + +``T& x`` The argument is a lvalue. ``const T& x`` + The function can or is ``T x`` + supposed to modify the argument. ``auto& x`` + ``auto&& x``, forwarding reference + +``T&& x`` The argument is a rvalue. The - ``const T& x`` + function can use the argument - ``T x`` + as a source in move operations. - ``auto&& x``, forwarding reference +================ ================================ ============================= + Algorithms ---------- .. toctree:: From b13abab03087cad397ab65191287950e196a7b4b Mon Sep 17 00:00:00 2001 From: Alexey Kukanov Date: Fri, 17 Oct 2025 19:45:14 +0200 Subject: [PATCH 11/11] Fix the new table --- .../oneTBB/source/named_requirements.rst | 33 +++++++++---------- 1 file changed, 16 insertions(+), 17 deletions(-) diff --git a/source/elements/oneTBB/source/named_requirements.rst b/source/elements/oneTBB/source/named_requirements.rst index 5098627a50..12e8875330 100644 --- a/source/elements/oneTBB/source/named_requirements.rst +++ b/source/elements/oneTBB/source/named_requirements.rst @@ -69,23 +69,22 @@ and therefore does not meet the semantic requirements of *Sortable*. The following table provides guidance for the types of parameters used in pseudo-signatures. -================ ================================ ============================= -Pseudo-signature General semantics Alternative real parameters -parameter -================ ================================ ============================= -``const T& x`` The function is not supposed ``T x`` - to modify the argument. ``auto& x`` - ``auto&& x``, forwarding reference - -``T& x`` The argument is a lvalue. ``const T& x`` - The function can or is ``T x`` - supposed to modify the argument. ``auto& x`` - ``auto&& x``, forwarding reference - -``T&& x`` The argument is a rvalue. The - ``const T& x`` - function can use the argument - ``T x`` - as a source in move operations. - ``auto&& x``, forwarding reference -================ ================================ ============================= +========================== ================================ ============================= +Pseudo-signature parameter General semantics Alternative real parameters +========================== ================================ ============================= +``const T& x`` The function is not supposed - ``T x`` + to modify the argument. - ``auto& x`` + - ``auto&& x``, forwarding reference + +``T& x`` The argument is a lvalue. - ``const T& x`` + The function can or is - ``T x`` + supposed to modify the argument. - ``auto& x`` + - ``auto&& x``, forwarding reference + +``T&& x`` The argument is a rvalue. The - ``const T& x`` + function can use the argument - ``T x`` + as a source in move operations. - ``auto&& x``, forwarding reference +========================== ================================ ============================= Algorithms ----------