Intel® oneAPI Threading Building Blocks Developer Guide and API Reference
priority_queue_node
[flow_graph.priority_queue_node]
A class template that forwards messages in a priority order.
// Defined in header <oneapi/tbb/flow_graph.h>
namespace oneapi {
namespace tbb {
namespace flow {
template< typename T, typename Compare = std::less<T>>
class priority_queue_node : public graph_node, public receiver<T>, public sender<T> {
public:
explicit priority_queue_node( graph &g );
priority_queue_node( const priority_queue_node &src );
~priority_queue_node();
// Preview feature: Helper Functions for Expressing Graphs
explicit priority_queue_node(decltype(follows(...)), const Compare& comp = Compare());
explicit priority_queue_node(decltype(precedes(...)), const Compare& compare = Compare());
bool try_put( const T &v );
bool try_get( T &v );
// Preview feature: Waiting for Single Message
bool try_put_and_wait( const T &v );
};
} // namespace flow
} // namespace tbb
} // namespace oneapiRequirements:
The type T must meet the CopyConstructible requirements from [copyconstructible] and CopyAssignable requirements from [copyassignable] ISO C++ Standard sections.
The type Compare must meet the Compare type requirements from [alg.sorting] ISO C++ Standard section. If Compare instance throws an exception, then behavior is undefined.
The next message to be forwarded has the largest priority as determined by the Compare template argument.
priority_queue_node is a graph_node, receiver<T>, and sender<T>.
priority_queue_node has a buffering and single-pushproperties.
Member functions
explicitpriority_queue_node(graph&g)
Constructs an empty priority_queue_node that belongs to the graph g.
priority_queue_node(constpriority_queue_node&src)
Constructs an empty priority_queue_node that belongs to the same graph g as src. Any intermediate state of src, including its links to predecessors and successors, is not copied.
booltry_put(constT&v)
Adds v to the priority_queue_node and tries forwarding to a successor the item with the largest priority among all of the items that were added to the node and have not been yet forwarded to successors.
Returns: true
booltry_get(T&v)
Returns: true if a message is available in the node and the node is not currently reserved. Otherwise, returns false. If the node returns true, the message with the largest priority is copied to v.
Preview Features
The following preview features extend the priority_queue_node API:
Helper Functions for Expressing Graphs - allows priority_queue_node to be constructed as a successor or a predecessor of the set of nodes.
Waiting for Single Message in Flow Graph - allows to put messages to priority_queue_node and wait for all related work to complete.
Example
Usage scenario is similar to sequencer_node except that the priority_queue_node provides local order, passing the message with highest priority of all stored at the moment, while sequencer_node enforces global order and does not allow a “smaller priority” message to pass through before all preceding messages.