# limiter_node Template Class

## Summary

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

## Syntax

    template < typename T > class limiter_node;

## Header

    #include "tbb/flow_graph.h"

## Description

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.

Behavior of a call to a limiter_node's try_put
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.

## Members

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

    }
    }

The following table provides additional information on the members of this template class.
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. Note: If the limiter_node is used in a graph (that is, the only way the decrement will receive a message is from another node via an edge), then the number_of_decrement_predecessors must be zero. The count of the number of predecessors is maintained when make_edge creates arcs to the decrement and when remove_edge removes arcs.
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.

Parent topic: Flow Graph

## See Also

Message Passing Protocol