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