priority_queue_node

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 oneapi

Requirements:

  • 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-push properties.

Member functions#

explicit priority_queue_node(graph &g)#

Constructs an empty priority_queue_node that belongs to the graph g.

priority_queue_node(const priority_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.

bool try_put(const T &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

bool try_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:

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.