Intel® oneAPI Threading Building Blocks Developer Guide and API Reference
A newer version of this document is available. Customers should click here to go to the newest version.
Visible to Intel only — GUID: GUID-D0525911-FE03-4291-9D8C-A41365BA69D8
Visible to Intel only — GUID: GUID-D0525911-FE03-4291-9D8C-A41365BA69D8
Using limiter_node
One way to limit resource consumption is to use a limiter_node to set a limit on the number of messages that can flow through a given point in your graph. The constructor for a limiter node takes two arguments:
limiter_node( graph &g, size_t threshold )
The first argument is a reference to the graph it belongs to. The second argument sets the maximum number of items that should be allowed to pass through before the node starts rejecting incoming messages.
A limiter_node maintains an internal count of the messages that it has allowed to pass. When a message leaves the controlled part of the graph, a message can be sent to the decrement port on the limiter_node to decrement the count, allowing additional messages to pass through. In the example below, an input_node will generate M big objects. But the user wants to allow at most three big objects to reach the function_node at a time, and to prevent the input_node from generating all M big objects at once.
graph g;
int src_count = 0;
int number_of_objects = 0;
int max_objects = 3;
input_node< big_object * > s( g, [&]( oneapi::tbb::flow_control& fc ) -> big_object* {
if ( src_count < M ) {
big_object* v = new big_object();
++src_count;
return v;
} else {
fc.stop();
return nullptr;
}
} );
s.activate();
limiter_node< big_object * > l( g, max_objects );
function_node< big_object *, continue_msg > f( g, unlimited,
[]( big_object *v ) -> continue_msg {
spin_for(1);
delete v;
return continue_msg();
} );
make_edge( l, f );
make_edge( f, l.decrement );
make_edge( s, l );
g.wait_for_all();
The example above prevents the input_node from generating all M big objects at once. The limiter_node has a threshold of 3, and will therefore start rejecting incoming messages after its internal count reaches 3. When the input_node sees its message rejected, it stops calling its body object and temporarily buffers the last generated value. The function_node has its output, a continue_msg, sent to the decrement port of the limiter_node. So, after it completes executing, the limiter_node internal count is decremented. When the internal count drops below the threshold, messages begin flowing from the input_node again. So in this example, at most four big objects exist at a time, the three that have passed through the limiter_node and the one that is buffered in the input_node.