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-CF08AE05-94AA-43F2-8AB4-1434E8205176
Visible to Intel only — GUID: GUID-CF08AE05-94AA-43F2-8AB4-1434E8205176
Sending to One or Multiple Successors
An important characteristic of the predefined nodes is whether they push their output to a single successor or broadcast to all successors. The following predefined nodes push messages to a single successor:
buffer_node
queue_node
priority_queue_node
sequencer_node
Other nodes push messages to all successors that will accept them.
The nodes that push to only a single successor are all buffer nodes. Their purpose is to hold messages temporarily, until they are consumed downstream. Consider the example below:
void use_buffer_and_two_nodes() { graph g; function_node< int, int, rejecting > f1( g, 1, []( int i ) -> int { spin_for(0.1); cout << "f1 consuming " << i << "\n"; return i; } ); function_node< int, int, rejecting > f2( g, 1, []( int i ) -> int { spin_for(0.2); cout << "f2 consuming " << i << "\n"; return i; } ); priority_queue_node< int > q(g); make_edge( q, f1 ); make_edge( q, f2 ); for ( int i = 10; i > 0; --i ) { q.try_put( i ); } g.wait_for_all(); }
First, function_nodes by default queue up the messages they receive at their input. To make a priority_queue_node work properly with a function_node, the example above constructs its function_nodes with its buffer policy set to rejecting. So, f1 and f2 do not internally buffer incoming messages, but instead rely on upstream buffering in the priority_queue_node.
In the above example, each message buffered by the priority_queue_node is sent to either f1 or f2, but not both.
Let’s consider the alternative behavior; that is; what if the priority_queue_node broadcasts to all successors. What if some, but not all, nodes accept a message? Should the message be buffered until all nodes accept it, or be only delivered to the accepting subset? If the node continues to buffer the message, should it eventually deliver the messages in the same order to all nodes or in the current priority order at the time the node accepts the next message? For example, assume a priority_queue_node only contains “9” when a successor node, f1, accepts “9” but another successor node, f2, rejects it. Later a value “100” arrives and f2 is available to accept messages. Should f2 receive “9” next or “100”, which has a higher priority? In any case, trying to ensure that all successors receive each message creates a garbage collection problem and complicates reasoning. Therefore, these buffering nodes push each message to only one successor. And, you can use this characteristic to create useful graph structures such as the one shown in the graph above, where each message will be processed in priority order, by either f1 or f2.
But what if you really do want both f1 and f2 to receive all of the values, and in priority order? You can easily create this behavior by creating one priority_queue_node for each function_node, and pushing each value to both queues through a broadcast_node, as shown below:
graph g; function_node< int, int, rejecting > f1( g, 1, []( int i ) -> int { spin_for(0.1); cout << "f1 consuming " << i << "\n"; return i; } ); function_node< int, int, rejecting > f2( g, 1, []( int i ) -> int { spin_for(0.2); cout << "f2 consuming " << i << "\n"; return i; } ); priority_queue_node< int > q1(g); priority_queue_node< int > q2(g); broadcast_node< int > b(g); make_edge( b, q1 ); make_edge( b, q2 ); make_edge( q1, f1 ); make_edge( q2, f2 ); for ( int i = 10; i > 0; --i ) { b.try_put( i ); } g.wait_for_all();
So, when connecting a node in your graph to multiple successors, be sure to understand whether the output will broadcast to all of the successors, or just a single successor.