1.. _use_concurrency_limits:
2
3Use Concurrency Limits
4======================
5
6
7To control the number of instances of a single node, you can use the
8concurrency limit on the node. To cause it to reject messages after it
9reaches its concurrency limit, you construct it as a "rejecting" node.
10
11
12A function node is constructed with one or more template arguments. The
13third argument controls the buffer policy used by the node, and is by
14default queueing. With a queueing policy, a ``function_node`` that has
15reached its concurrency limit still accepts incoming messages, but
16buffers them internally. If the policy is set to rejecting the node will
17instead reject the incoming messages.
18
19
20::
21
22
23   template < typename Input,
24              typename Output = continue_msg,
25              graph_buffer_policy = queueing >
26   class function_node;
27
28
29For example, you can control the number of big objects in flight in a
30graph by placing a rejecting function_node downstream of an ``input_node``,
31as is done below:
32
33
34::
35
36
37     graph g;
38
39
40     int src_count = 0;
41     int number_of_objects = 0;
42     int max_objects = 3;
43
44
45     input_node< big_object * > s( g, [&]( oneapi::tbb::flow_control& fc ) -> big_object* {
46         if ( src_count < M ) {
47           big_object* v = new big_object();
48           ++src_count;
49           return v;
50         } else {
51           fc.stop();
52           return nullptr;
53         }
54     } );
55     s.activate();
56
57     function_node< big_object *, continue_msg, rejecting > f( g, 3,
58         []( big_object *v ) -> continue_msg {
59         spin_for(1);
60            delete v;
61         return continue_msg();
62     } );
63
64
65     make_edge( s, f );
66     g.wait_for_all();
67
68
69The ``function_node`` will operate on at most three big objects
70concurrently. The node's concurrency threshold that limits the node to
71three concurrent invocations. When the ``function_node`` is running three
72instances concurrently, it will start rejecting incoming messages from
73the ``input_node``, causing the ``input_node`` to buffer its last created
74object and temporarily stop invoking its body object. Whenever the
75``function_node`` drops below its concurrency limit, it will pull new
76messages from the ``input_node``. At most four big objects will exist
77simultaneously, three in the ``function_node`` and one buffered in the
78``input_node``.
79
80