limiter_node

[flow_graph.limiter_node]

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

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

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 );

        InternalReceiverType<DecrementType> decrement;

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

} // namespace flow
} // namespace tbb

Requirements:

• T type should meet the CopyConstructible requirements from [copyconstructible] and CopyAssignable requirements from [copyassignable] ISO C++ Standard section.

• The DecrementType type shall 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.

It does not accept new messages once its user-specified threshold is reached. The internal count of broadcasts is adjusted through use of its embedded decrement object, and its values are truncated to be inside [0, threshold] interval.

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

The continue_msg sent to the member object decrement decreases the internal counter of broadcasts by one.

When try_put call on the member object decrement results in the new value of internal counter of broadcasts to be less than the threshold, the limiter_node will try to get a message from one of its known predecessors and forward that message to all of its successors. If it cannot obtain a message from a predecessor, it will decrement a 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 will belong to the same graph g as src, have the same threshold. The list of predecessors, the list of successors, and the current count of broadcasts are not copied from src.

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.