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-F770694B-816E-4366-8ADD-F5F422556857
Visible to Intel only — GUID: GUID-F770694B-816E-4366-8ADD-F5F422556857
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.