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. |