doc/main/specification/source/flow_graph/input_node_cls.rst
.. SPDX-FileCopyrightText: 2019-2021 Intel Corporation .. .. SPDX-License-Identifier: CC-BY-4.0
[flow_graph.input_node]
A node that generates messages by invoking the user-provided functor and broadcasts the result to all of its successors.
.. code:: cpp
// Defined in header <oneapi/tbb/flow_graph.h>
namespace oneapi {
namespace tbb {
namespace flow {
template < typename Output >
class input_node : public graph_node, public sender<Output> {
public:
template< typename Body >
input_node( graph &g, Body body );
input_node( const input_node &src );
~input_node();
void activate();
bool try_get( Output &v );
};
} // namespace flow
} // namespace tbb
} // namespace oneapi
Requirements:
Output type must meet the DefaultConstructible requirements from [defaultconstructible], CopyConstructible requirements from [copyconstructible] and
CopyAssignable requirements from [copyassignable] ISO C++ Standard sections.Body must meet the :doc:InputNodeBody requirements <../named_requirements/flow_graph/input_node_body>.This node can have no predecessors. It executes a user-provided body function object to
generate messages that are broadcast to all successors. It is a serial node and never calls
its body concurrently. This node can buffer a single item. If no successor accepts an
item that it has generated, the message is buffered and provided to successors
before a new item is generated.
input_node is a graph_node and sender<Output>.
input_node has a buffering and broadcast-push :doc:properties <forwarding_and_buffering>.
An input_node continues to invoke body and broadcast messages until the body
toggles fc.stop() or it has no valid successors. A message may be generated and then rejected
by all successors. In this case, the message is buffered and will be the next message sent once a
successor is added to the node or try_get is called. Calls to try_get return a
message from the buffer, or invoke body to attempt to generate a new message.
A call to body is made only when the buffer is empty.
The body object passed to an input_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.
.. cpp:function:: template< typename Body > input_node( graph &g, Body body )
Constructs an ``input_node`` that invokes ``body``. By default,
the node is created in an inactive state, which means that messages are not generated until a call to ``activate`` is made.
.. cpp:function:: input_node( const input_node &src )
Constructs an ``input_node`` that has the same initial state that
``src`` had when it was constructed. The ``input_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
has the same initial active state as ``src``. The successors of
``src`` are not copied.
The new body object is copy-constructed from a copy of the original
body provided to ``src`` at its construction. Changes
made to member variables in ``src`` body after the construction
of ``src`` do not affect the body of the new ``input_node.``
.. cpp:function:: void activate()
Sets the ``input_node`` to the active state, which enables messages generation.
.. cpp:function:: bool try_get( Output &v )
Copies the message from the buffer to ``v`` if available, or, if the node is
in active state, invokes ``body`` to attempt to generate a new message that
will be copied into ``v``.
**Returns:** ``true`` if a message is copied to ``v``; ``false``, otherwise.
.. code:: cpp
template <typename Body>
input_node(graph&, Body) -> input_node<std::decay_t<input_t<Body>>>;
Where:
input_t is an alias to Body input argument type.