.. SPDX-FileCopyrightText: 2019-2021 Intel Corporation
..
.. SPDX-License-Identifier: CC-BY-4.0

=============
continue_node
=============
**[flow_graph.continue_node]**

A node that executes a specified body object when triggered.

.. code:: cpp

    // Defined in header <oneapi/tbb/flow_graph.h>

    namespace oneapi {
    namespace tbb {
    namespace flow {

        template< typename Output, typename Policy = /*implementation-defined*/ >
        class continue_node : public graph_node, public receiver<continue_msg>, public sender<Output> {
        public:
            template<typename Body>
            continue_node( graph &g, Body body, node_priority_t priority = no_priority );
            template<typename Body>
            continue_node( graph &g, Body body, Policy /*unspecified*/ = Policy(),
                          node_priority_t priority = no_priority );

            template<typename Body>
            continue_node( graph &g, int number_of_predecessors, Body body,
                           node_priority_t priority = no_priority );
            template<typename Body>
            continue_node( graph &g, int number_of_predecessors, Body body,
                           Policy /*unspecified*/ = Policy(), node_priority_t priority = no_priority );

            continue_node( const continue_node &src );
            ~continue_node();

            bool try_put( const input_type &v );
            bool try_get( output_type &v );
        };

    } // namespace flow
    } // namespace tbb
    } // namespace oneapi

Requirements:

* The type ``Output`` must meet the `CopyConstructible` requirements from [copyconstructible] ISO
  C++ Standard section.
* The type ``Policy`` can be specified as :doc:`lightweight policy<functional_node_policies>` or defaulted.
* The type ``Body`` must meet the :doc:`ContinueNodeBody requirements <../named_requirements/flow_graph/continue_node_body>`.

A ``continue_node`` is a ``graph_node``, ``receiver<continue_msg>``, and ``sender<Output>``.

This node is used for nodes that wait for their predecessors to complete before executing, but no
explicit data is passed across the incoming edges.

A ``continue_node`` maintains an internal threshold that defines the number of predecessors.
This value can be provided at construction. Call of the :doc:`make_edge function <make_edge_func>`
with ``continue_node`` as a receiver increases its threshold. Call of the
:doc:`remove_edge function <remove_edge_func>` with ``continue_node`` as a receiver
decreases it.

Each time the number of ``try_put()`` calls reaches the defined threshold, node's ``body`` is called
and the node starts counting the number of ``try_put()`` calls from the beginning.

``continue_node`` has a `discarding` and `broadcast-push` :doc:`properties <forwarding_and_buffering>`.

The body object passed to a ``continue_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 <copy_body_func>` can be
used to obtain an updated copy.


Member functions
-----------------

.. code:: cpp

    template<typename Body>
    continue_node( graph &g, Body body, node_priority_t priority = no_priority );


Constructs a ``continue_node`` that invokes ``body``. The internal threshold is set to 0.

This function specifies :doc:`node priority<node_priorities>`.

----------------------------------------------------------------

.. code:: cpp

    template<typename Body>
    continue_node( graph &g, Body body, Policy /*unspecified*/ = Policy(),
                   node_priority_t priority = no_priority );

Constructs a ``continue_node`` that invokes ``body``. The internal threshold is set to 0.

This function specifies :doc:`lightweight policy<functional_node_policies>` and :doc:`node priority<node_priorities>`.

----------------------------------------------------------------

.. code:: cpp

    template<typename Body>
    continue_node( graph &g, int number_of_predecessors, Body body,
                   node_priority_t priority = no_priority );

Constructs a ``continue_node`` that invokes ``body``. The internal threshold is set to
``number_of_predecessors``.

This function specifies :doc:`node priority<node_priorities>`.

----------------------------------------------------------------

.. code:: cpp

    template<typename Body>
    continue_node( graph &g, int number_of_predecessors, Body body,
                   Policy /*unspecified*/ = Policy(), node_priority_t priority = no_priority );

Constructs a ``continue_node`` that invokes ``body``. The internal threshold is set to
``number_of_predecessors``.

This function specifies :doc:`lightweight policy<functional_node_policies>` and :doc:`node priority<node_priorities>`.

----------------------------------------------------------------

.. code:: cpp

    template<typename Body>
    continue_node( graph &g, int number_of_predecessors, Body body );

Constructs a ``continue_node`` that invokes ``body``. The internal threshold is set to
``number_of_predecessors``.

----------------------------------------------------------------

.. code:: cpp

    continue_node( const continue_node &src )

Constructs a ``continue_node`` that has the same initial state that ``src`` had after its
construction. It does not copy the current count of ``try_puts`` received, or the current
known number of predecessors. The ``continue_node`` that is constructed has a
reference to the same ``graph`` object as ``src``, has a copy of the initial ``body``
used by ``src``, and only has a non-zero threshold if ``src`` is constructed with a
non-zero threshold.

The new body object is copy-constructed from a copy of the original body provided to ``src``
at its construction.

----------------------------------------------------------------

.. code:: cpp

    bool try_put( const Input &v )

Increments the count of ``try_put()`` calls received. If the incremented count is equal to the
number of known predecessors, performs the ``body`` function object execution. It does not wait
for the execution of the body to complete.

**Returns**: ``true``

----------------------------------------------------------------

.. code:: cpp

    bool try_get( Output &v )

**Returns**: ``false``

Deduction Guides
----------------

.. code:: cpp

    template <typename Body, typename Policy>
    continue_node(graph&, Body, Policy, node_priority_t = no_priority)
        -> continue_node<continue_output_t<std::invoke_result_t<Body, continue_msg>>, Policy>;

    template <typename Body, typename Policy>
    continue_node(graph&, int, Body, Policy, node_priority_t = no_priority)
        -> continue_node<continue_output_t<std::invoke_result_t<Body, continue_msg>>, Policy>;

    template <typename Body>
    continue_node(graph&, Body, node_priority_t = no_priority)
        -> continue_node<continue_output_t<std::invoke_result_t<Body, continue_msg>>, /*default-policy*/>;

    template <typename Body>
    continue_node(graph&, int, Body, node_priority_t = no_priority)
        -> continue_node<continue_output_t<std::invoke_result_t<Body, continue_msg>>, /*default-policy*/>;

Where:

* ``continue_output_t<Output>`` is an alias to `Output` template argument type. If `Output` specified
  as ``void``, ``continue_output_t<Output>`` is an alias to ``continue_msg`` type.

Example
-------

A set of ``continue_nodes`` forms a :doc:`Dependency Flow Graph <dependency_flow_graph_example>`.