limiter_node

[flow_graph.limiter_node]

A node that counts and limits the number of messages that pass through it.

// Defined in header <oneapi/tbb/flow_graph.h>

namespace oneapi {
namespace tbb {
namespace flow {

    template< typename T, typename DecrementType=continue_msg >
    class limiter_node : public graph_node, public receiver<T>, public sender<T> {
    public:
        limiter_node( graph &g, size_t threshold );
        limiter_node( const limiter_node &src );

        receiver<DecrementType>& decrementer();

        bool try_put( const T &v );
        bool try_get( T &v );
    };

} // namespace flow
} // namespace tbb
} // namespace oneapi

Requirements:

• T type must meet the DefaultConstructible requirements from [defaultconstructible] ISO C++ Standard section.

• The DecrementType type must be an integral type or continue_msg.

limiter_node is a graph_node, receiver<T>, and sender<T>

limiter_node has a discarding and broadcast-push properties.

This node does not accept new messages once the user-specified threshold is reached. The internal counter of broadcasts is adjusted through use of the decrementer, a receiver object embedded into the node that can be obtained by calling the decrementer method. The counter values are truncated to be inside the [0, threshold] interval.

The template parameter DecrementType specifies the type of the message that can be sent to the decrementer. This template parameter is defined to continue_msg by default. If an integral type is specified, positive values sent to the decrementer determine the value by which the internal counter of broadcasts will be decreased, while negative values determine the value by which the internal counter of broadcasts will be increased.

If continue_msg is used as an argument for the DecrementType template parameter, the decrementer’s port of the limiter_node also acquires the behavior of the continue_node. This behavior requires the number of messages sent to it to be equal to the number of connected predecessors before decrementing the internal counter of broadcasts by one.

When try_put call on the decrementer results in the new value of the counter of broadcasts to be less than the threshold, the limiter_node tries to get a message from one of its known predecessors and forward that message to all its successors. If it cannot obtain a message from a predecessor, it decrements the counter of broadcasts.

Member functions

limiter_node(graph &g, size_t threshold)

Constructs a limiter_node that allows up to threshold items to pass through before rejecting try_put’s.

limiter_node(const limiter_node &src)

Constructs a limiter_node that has the same initial state that src had at its construction. The new limiter_node belongs to the same graph g as src, has the same threshold. The list of predecessors, the list of successors, and the current count of broadcasts are not copied from src.

receiver<DecrementType> &decrementer()

Obtains a reference to the embedded receiver object that is used for the internal counter adjustments.

bool try_put(const T &v)

If the broadcast count is below the threshold, v is broadcast to all successors.

Returns: true if v is broadcast; false if v is not broadcast because the threshold has been reached.

bool try_get(T &v)

Returns: false.