From 6653e2ff490a0f0f50f5386886f0aa545c0e5b88 Mon Sep 17 00:00:00 2001 From: Konstantin Boyarinov Date: Fri, 3 Nov 2023 17:24:09 +0200 Subject: [PATCH] [oneTBB] Allow new data types as algorithm and flow graph bodies (#510) Co-authored-by: Alexey Kukanov --- .../algorithms/functions/parallel_for_each_func.rst | 1 + .../functions/parallel_pipeline_func/filter_cls.rst | 11 +++++++---- .../algorithms/functions/parallel_reduce_func.rst | 3 ++- .../algorithms/functions/parallel_scan_func.rst | 5 ++++- .../oneTBB/source/flow_graph/async_node_cls.rst | 7 ++++--- .../oneTBB/source/flow_graph/func_node_cls.rst | 2 ++ .../oneTBB/source/flow_graph/join_node_cls.rst | 2 ++ .../oneTBB/source/flow_graph/multifunc_node_cls.rst | 1 + .../oneTBB/source/flow_graph/sequencer_node_cls.rst | 4 +++- .../flow_graph/function_node_body.rst | 5 ++--- 10 files changed, 28 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 713271b038..0469c277b5 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,6 +37,7 @@ 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>`. + Since C++17, ``Body`` may also be a pointer to a member function in ``Index``. * The ``InputIterator`` type must meet the `Input Iterator` requirements from the [input.iterators] section of the ISO C++ Standard. * 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``. diff --git a/source/elements/oneTBB/source/algorithms/functions/parallel_pipeline_func/filter_cls.rst b/source/elements/oneTBB/source/algorithms/functions/parallel_pipeline_func/filter_cls.rst index db496cc48d..ddecb03d16 100644 --- a/source/elements/oneTBB/source/algorithms/functions/parallel_pipeline_func/filter_cls.rst +++ b/source/elements/oneTBB/source/algorithms/functions/parallel_pipeline_func/filter_cls.rst @@ -7,7 +7,7 @@ filter ====== **[algorithms.parallel_pipeline.filter]** -A ``filter`` class template represents a strongly-typed filter in a ``parallel_pipeline`` algorithm, +A ``filter`` class template represents a strongly-typed filter in a ``parallel_pipeline`` algorithm, with its template parameters specifying the filter input and output types. A ``filter`` can be constructed from a functor or by composing two ``filter`` objects with ``operator&()``. The same ``filter`` object can be reused in multiple ``&`` expressions. @@ -17,7 +17,7 @@ The ``filter`` class should only be used in conjunction with ``parallel_pipeline .. code:: cpp // Defined in header - + namespace oneapi { namespace tbb { @@ -48,9 +48,12 @@ The ``filter`` class should only be used in conjunction with ``parallel_pipeline Requirements: -* If `InputType` is ``void``, a ``Body`` type must meet the :doc:`StartFilterBody requirements <../../../named_requirements/algorithms/filter_body>`. -* If `OutputType` is ``void``, a ``Body`` type must meet the :doc:`OutputFilterBody requirements <../../../named_requirements/algorithms/filter_body>`. +* If `InputType` is ``void``, a ``Body`` type must meet the :doc:`FirstFilterBody requirements <../../../named_requirements/algorithms/filter_body>`. +* If `OutputType` is ``void``, a ``Body`` type must meet the :doc:`LastFilterBody requirements <../../../named_requirements/algorithms/filter_body>`. + Since C++17, ``Body`` may also be a pointer to a member function in ``InputType``. * If `InputType` and `OutputType` are not ``void``, a ``Body`` type must meet the :doc:`MiddleFilterBody requirements <../../../named_requirements/algorithms/filter_body>`. + Since C++17, ``Body`` may also be a pointer to a member function in ``InputType`` that returns ``OutputType`` + or a pointer to a data member in ``InputType`` of type ``OutputType``. * If `InputType` and `OutputType` are ``void``, a ``Body`` type must meet the :doc:`SingleFilterBody requirements <../../../named_requirements/algorithms/filter_body>`. filter_mode Enumeration 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 728972ef09..551678c550 100644 --- a/source/elements/oneTBB/source/algorithms/functions/parallel_reduce_func.rst +++ b/source/elements/oneTBB/source/algorithms/functions/parallel_reduce_func.rst @@ -53,7 +53,9 @@ Requirements: * 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>`. + Since C++17, ``Func`` may also be a pointer to a const member function in ``Range`` that takes ``const Value&`` argument and returns ``Value``. * The ``Reduction`` types must meet :doc:`ParallelReduceReduction requirements <../../named_requirements/algorithms/par_reduce_reduction>`. + Since C++17, ``Reduction`` may also be a pointer to a const member function in ``Value`` that takes ``const Value&`` argument and returns ``Value``. The function template ``parallel_reduce`` has two forms: The functional form is designed to be easy to use in conjunction with lambda expressions. @@ -163,4 +165,3 @@ expressions and the functional form of ``parallel_reduce``. See also: * :ref:`Partitioners ` - 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 b8cadad9fe..821f850d6d 100644 --- a/source/elements/oneTBB/source/algorithms/functions/parallel_scan_func.rst +++ b/source/elements/oneTBB/source/algorithms/functions/parallel_scan_func.rst @@ -35,7 +35,11 @@ Requirements: * 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>`. + Since C++17, ``Scan`` may also be a pointer to a const member function in ``Range`` that takes ``const Value&`` and ``bool`` arguments and + returns ``Value``. * The ``Combine`` type must meet the :doc:`ParallelScanCombine requirements <../../named_requirements/algorithms/par_scan_combine>`. + Since C++17, ``Combine`` may also be a pointer to a const member function in ``Value`` that takes ``const Value&`` argument + and returns ``Value``. The function template ``parallel_scan`` computes a parallel prefix, also known as a parallel scan. This computation is an advanced concept in parallel computing that is sometimes useful in scenarios @@ -185,4 +189,3 @@ See also: * :doc:`blocked_range class <../../algorithms/blocked_ranges/blocked_range_cls>` * :doc:`parallel_reduce algorithm <../../algorithms/functions/parallel_reduce_func>` - diff --git a/source/elements/oneTBB/source/flow_graph/async_node_cls.rst b/source/elements/oneTBB/source/flow_graph/async_node_cls.rst index 7451faf84b..8c28b7dd0e 100644 --- a/source/elements/oneTBB/source/flow_graph/async_node_cls.rst +++ b/source/elements/oneTBB/source/flow_graph/async_node_cls.rst @@ -47,6 +47,7 @@ Requirements: and the `CopyConstructible` requirements from [copyconstructible] ISO C++ Standard sections. * The type ``Policy`` can be specified as :doc:`lightweight, queueing and rejecting policies` or defaulted. * The type ``Body`` must meet the :doc:`AsyncNodeBody requirements <../named_requirements/flow_graph/async_node_body>`. + Since C++17, ``Body`` may also be a pointer to a const member function in ``Input`` that takes ``gateway_type&`` argument. ``async_node`` executes a user-provided body on incoming messages. The body typically submits the messages to an external activity for processing outside of the graph. It is responsibility of @@ -61,8 +62,8 @@ messages to an external activity for processing outside of the graph. It is resp The user can also provide a value of type ``std::size_t`` to limit concurrency to a value between 1 and :doc:`tbb::flow::unlimited `. -The body object passed to a ``async_node`` is copied. Updates to member variables do not affect the original object used to construct the node. -If the state held within a body object must be inspected from outside of the node, +The body object passed to a ``async_node`` is copied. Updates to member variables do not affect the original object used to construct the node. +If the state held within a body object must be inspected from outside of the node, the :doc:`copy_body ` function can be used to obtain an updated copy. Member types @@ -79,7 +80,7 @@ Member functions async_node( graph &g, size_t concurrency, Body body, node_priority_t priority = no_priority ); -Constructs an ``async_node`` that invokes a copy of ``body``. The ``concurrency`` value limits the number of simultaneous +Constructs an ``async_node`` that invokes a copy of ``body``. The ``concurrency`` value limits the number of simultaneous ``body`` invocations for the node. This function specifies :doc:`node priority`. diff --git a/source/elements/oneTBB/source/flow_graph/func_node_cls.rst b/source/elements/oneTBB/source/flow_graph/func_node_cls.rst index 426c6cc579..0f22b88fe5 100644 --- a/source/elements/oneTBB/source/flow_graph/func_node_cls.rst +++ b/source/elements/oneTBB/source/flow_graph/func_node_cls.rst @@ -47,6 +47,8 @@ Requirements: [copyconstructible] ISO C++ Standard section. * The type ``Policy`` may be specified as :doc:`lightweight, queueing and rejecting policies` or defaulted. * The type ``Body`` must meet the :doc:`FunctionNodeBody requirements <../named_requirements/flow_graph/function_node_body>`. + Since C++17, ``Body`` may also be a pointer to a const member function in ``Input`` that returns ``Output`` or + a pointer to a data member in ``Input`` of type ``Output``. ``function_node`` has a user-settable concurrency limit. It can be set to one of :doc:`predefined values `. The user can also provide a value of type ``std::size_t`` to limit concurrency to a value between 1 and :doc:`tbb::flow::unlimited `. diff --git a/source/elements/oneTBB/source/flow_graph/join_node_cls.rst b/source/elements/oneTBB/source/flow_graph/join_node_cls.rst index 12050a4e0e..8b4e0737b4 100644 --- a/source/elements/oneTBB/source/flow_graph/join_node_cls.rst +++ b/source/elements/oneTBB/source/flow_graph/join_node_cls.rst @@ -79,6 +79,8 @@ Requirements: * The ``JoinPolicy`` type must be specified as one of :doc:`buffering policies ` for ``join_node``. * The ``KHash`` type must meet the :doc:`HashCompare requirements <../named_requirements/containers/hash_compare>`. * The ``Bi`` types must meet the :doc:`JoinNodeFunctionObject requirements <../named_requirements/flow_graph/join_node_func_obj>`. + Since C++17, each of ``Bi`` types may also be a pointer to a const member function in ``Input`` that returns ``Key`` or + a pointer to a data member of type ``Key`` in ``Input``. A ``join_node`` is a ``graph_node`` and a ``sender``. It contains a tuple of input ports, each of which is a ``receiver`` for each `Type` in diff --git a/source/elements/oneTBB/source/flow_graph/multifunc_node_cls.rst b/source/elements/oneTBB/source/flow_graph/multifunc_node_cls.rst index bc7a119652..a72f092bd5 100644 --- a/source/elements/oneTBB/source/flow_graph/multifunc_node_cls.rst +++ b/source/elements/oneTBB/source/flow_graph/multifunc_node_cls.rst @@ -47,6 +47,7 @@ Requirements: and the `CopyConstructible` requirements from [copyconstructible] ISO C++ Standard sections. * The type ``Policy`` can be specified as :doc:`lightweight, queueing and rejecting policies` or defaulted. * The type ``Body`` must meet the :doc:`MultifunctionNodeBody requirements <../named_requirements/flow_graph/multifunction_node_body>`. + Since C++17, ``Body`` may also be a pointer to a const member function in ``Input`` that takes ``output_ports_type&`` argument. ``multifunction_node`` has a user-settable concurrency limit. It can be set to one of :doc:`predefined values `. The user can also provide a value of type ``std::size_t`` to limit concurrency to a value between 1 and :doc:`tbb::flow::unlimited `. diff --git a/source/elements/oneTBB/source/flow_graph/sequencer_node_cls.rst b/source/elements/oneTBB/source/flow_graph/sequencer_node_cls.rst index 16629ad219..b8c5d28bf8 100644 --- a/source/elements/oneTBB/source/flow_graph/sequencer_node_cls.rst +++ b/source/elements/oneTBB/source/flow_graph/sequencer_node_cls.rst @@ -36,7 +36,9 @@ Requirements: * The type ``T`` must meet the `CopyConstructible` requirements from [copyconstructible] and `CopyAssignable` requirements from [copyassignable] ISO C++ Standard sections. -* The type ``Sequencer`` must meet the :doc:`Sequencer requirements <../named_requirements/flow_graph/sequencer>` +* The type ``Sequencer`` must meet the :doc:`Sequencer requirements <../named_requirements/flow_graph/sequencer>`. + Since C++17, ``Sequencer`` may also be a pointer to a const member function in ``T`` that returns ``size_t`` or + a pointer to a data member in ``T`` of type ``size_t``. If ``Sequencer`` instance throws an exception, behavior is undefined. ``sequencer_node`` forwards messages in a sequence order to a single successor in its successor set. diff --git a/source/elements/oneTBB/source/named_requirements/flow_graph/function_node_body.rst b/source/elements/oneTBB/source/named_requirements/flow_graph/function_node_body.rst index 2a80c8cde7..47b4c1c57e 100644 --- a/source/elements/oneTBB/source/named_requirements/flow_graph/function_node_body.rst +++ b/source/elements/oneTBB/source/named_requirements/flow_graph/function_node_body.rst @@ -14,7 +14,7 @@ A type `Body` satisfies `FunctionNodeBody` if it meets the following requirement **FunctionNodeBody Requirements: Pseudo-Signature, Semantics** .. namespace:: FunctionNodeBody - + .. cpp:function:: Body::Body( const Body& ) Copy constructor. @@ -26,8 +26,7 @@ A type `Body` satisfies `FunctionNodeBody` if it meets the following requirement .. cpp:function:: Output Body::operator()( const Input& v ) **Requirements:** The ``Input`` and ``Output`` types must be the same as the ``Input`` and ``Output`` - template type arguments of the ``fucntion_node`` instance in which the ``Body`` object is passed + template type arguments of the ``function_node`` instance in which the ``Body`` object is passed during construction. Performs operation on ``v`` and returns a value of type ``Output``. -