function_node#

[flow_graph.function_node]

A node that executes a user-provided body on incoming messages.

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

namespace oneapi {
namespace tbb {
namespace flow {

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

        function_node( const function_node &src );

        bool try_put( const Input &v );
        bool try_get( Output &v );
    };

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

Requirements:

  • The Input type must meet the DefaultConstructible requirements from [defaultconstructible] and the CopyConstructible requirements from [copyconstructible] ISO C++ Standard sections.

  • The Output type must meet the CopyConstructible requirements from [copyconstructible] ISO C++ Standard section.

  • The type Policy may be specified as lightweight, queueing and rejecting policies or defaulted.

  • The type Body must meet the FunctionNodeBody requirements. 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 predefined values. The user can also provide a value of type std::size_t to limit concurrency to a value between 1 and tbb::flow::unlimited.

Messages that cannot be immediately processed due to concurrency limits are handled according to the Policy template argument.

function_node is a graph_node, receiver<Input>, and sender<Output>.

function_node has a discarding and broadcast-push properties.

The body object passed to a function_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 copy_body function can be used to obtain an updated copy.

Member functions#

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

Constructs a function_node that invokes a copy of body. Most of concurrency calls to body can be made concurrently.

Use this function to specify node priority.

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

Constructs a function_node that invokes a copy of body. Most of concurrency calls to body can be made concurrently.

Use this function to specify policy and node priority.

function_node( const function_node &src )

Constructs a function_node that has the same initial state that src had when it was constructed. The function_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 concurrency threshold as src. The predecessors and 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’s body after the construction of src do not affect the body of the new function_node.

bool try_put( const Input &v )

If the concurrency limit allows, executes the user-provided body on the incoming message v. Otherwise, depending on the policy of the node, either queues the incoming message v or rejects it.

Returns: true if the input was accepted; and false, otherwise.

bool try_get( Output &v )

Returns: false

Deduction Guides#

template <typename Body, typename Policy>
function_node(graph&, size_t, Body, Policy, node_priority_t = no_priority)
    ->function_node<std::decay_t<input_t<Body>>, output_t<Body>, Policy>;

template <typename Body>
function_node(graph&, size_t, Body, node_priority_t = no_priority)
    ->function_node<std::decay_t<input_t<Body>>, output_t<Body>, /*default-policy*/>;

Where:

  • input_t is an alias to Body input argument type.

  • output_t is an alias to Body return type.

Example#

Data Flow Graph example illustrates how function_node performs computation on input data and passes the result to successors.