Function Nodes Policies

[flow_graph.function_node_policies]

function_node, multifunction_node, async_node and continue_node can be specified by the Policy parameter, which is represented as a set of tag classes. This parameter affects behavior of node execution.

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

namespace oneapi {
namespace tbb {
namespace flow {

    class queueing { /*unspecified*/ };
    class rejecting { /*unspecified*/ };
    class lightweight { /*unspecified*/ };
    class queueing_lightweight { /*unspecified*/ };
    class rejecting_lightweight { /*unspecified*/ };

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

Each policy class satisfies the CopyConstructible requirements from [copyconstructible] ISO C++ Standard sections.

Queueing

This policy defines behavior for input messages acceptance. The queueing policy means that input messages that cannot be processed right away are kept to be processed when possible.

Rejecting

This policy defines behavior for input messages acceptance. The rejecting policy means that input messages that cannot be processed right away are not accepted by the node and it is responsibility of a predecessor to handle this.

Lightweight

This policy allows to specify that the node body takes little time to process, as a non-binding hint for an implementation to reduce overheads associated with the node execution. Any optimization applied by an implementation must have no observable side effects on the node and graph execution.

When combined with another policy, the lightweight policy results in extending the behavior of that other policy with the optimization hint. This rule automatically applies to functional nodes that have a default value for the Policy template parameter. For example, if the default value of Policy is queueing, specifying lightweight as the Policy value is equivalent to specifying queueing_lightweight.

The function call operator() of a node body must be noexcept for lightweight policies to have effect.

Example

The example below shows the application of the lightweight policy to a graph with a pipeline topology. It is reasonable to apply the lightweight policy to the second and third nodes because the bodies of these nodes are small. This allows the second and third nodes to execute without task scheduling overhead. The lightweight policy is not specified for the first node in order to permit concurrent invocations of the graph.

#include "oneapi/tbb/flow_graph.h"

int main() {
    using namespace oneapi::tbb::flow;

    graph g;

    function_node< int, int > add( g, unlimited, [](const int &v) {
        return v+1;
    } );
    function_node< int, int, lightweight > multiply( g, unlimited, [](const int &v) noexcept {
        return v*2;
    } );
    function_node< int, int, lightweight > cube( g, unlimited, [](const int &v) noexcept {
        return v*v*v;
    } );

    make_edge(add, multiply);
    make_edge(multiply, cube);

    for(int i = 1; i <= 10; ++i)
        add.try_put(i);
    g.wait_for_all();

    return 0;
}