An node that counts and limits the number of messages that pass through it.
template < typename T > class limiter_node;
#include "tbb/flow_graph.h"
A limiter_node is a graph_node, receiver<T> and sender<T> that broadcasts messages to all of its successors. It keeps a counter C of the number of broadcasts it makes and does not accept new messages once its user-specified threshold is reached. The internal count of broadcasts C can be decremented through use of its embedded continue_receiver decrement.
The behavior of a call to a limiter_node's try_put is shown below.
Value of counter C |
bool try_put( const input_type &v ) |
---|---|
C < threshold |
C is incremented and v is broadcast to all successors. If no successor accepts the message, C is decremented. Returns true if the message was successfully broadcast to at least one successor and false otherwise. |
C == threshold |
Returns false. |
When try_put is called on the member object decrement, 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 C. Rejection of messages by successors and failed gets from predecessors are handled using the protocol in the Message Passing Protocol, see link below.
T must be copy-constructible and assignable.
namespace tbb { namespace flow { template< typename T > class limiter_node : public graph_node, public receiver<T>, public sender<T> { public: limiter_node( graph &g, size_t threshold, int number_of_decrement_predecessors = 0 ); limiter_node( const limiter_node &src ); // a continue_receiver implementation-dependent-type decrement; // receiver<T> typedef T input_type; typedef sender<input_type> predecessor_type; bool try_put( const input_type &v ); bool register_predecessor( predecessor_type &p ); bool remove_predecessor( predecessor_type &p ); // sender<T> typedef T output_type; typedef receiver<output_type> successor_type; bool register_successor( successor_type &r ); bool remove_successor( successor_type &r ); bool try_get( output_type &v ); bool try_reserve( output_type &v ); bool try_release( ); bool try_consume( ); }; } }
Member | Description |
---|---|
limiter_node( graph &g, size_t threshold, int number_of_decrement_predecessors = 0 ) |
Constructs a limiter_node that allows up to threshold items to pass through before rejecting try_put's. Optionally a number_of_decrement_predecessors value can be supplied. This value is passed on to the continue_receiver decrement's constructor. |
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, and have the same initial number_of_decrement_predecessors. The list of predecessors, the list of successors, and the current count of broadcasts, C, are NOT copied from src. |
bool try_put( const input_type &v ) |
If the broadcast count is below the threshold, v is broadcast to all successors. For each successor s, if s.try_put( v ) == false && s.register_predecessor( *this ) == true, then s is removed from the set of succesors. Otherwise, s will remain in the set of successors. Returns: true if v is broadcast. false if v is not broadcast because the threshold has been reached. |
bool register_predecessor( predecessor_type &p ) |
Adds a predecessor that can be pulled from once the broadcast count falls below the threshold. Adds p to the set of predecessors. Returns:true. |
bool remove_predecessor( predecessor_type &p ) |
Removes p from the set of predecessors. Returns: true |
bool register_successor( successor_type &r ) |
Adds r to the set of successors. Returns: true |
bool remove_successor( successor_type &r ) |
Removes r from the set of successors. Returns: true |
bool try_get( output_type &v ) |
Does not contain buffering and therefore cannot be pulled from. Returns: false. |
bool try_reserve( output_type &v ) |
Does not support reservations. Returns: false. |
bool try_release( ) |
Does not support reservations. Returns: false. |
bool try_consume( ) |
Does not support reservations. Returns: false. |