[RFCs] Add Flow Graph try_put_and_wait RFC

[kboyarinov]

Description

Add a comprehensive description of proposed changes

Fixes # - issue number(s) if exists

Type of change

Choose one or multiple, leave empty if none of the other choices apply

Add a respective label(s) to PR if you have permissions

• bug fix - change that fixes an issue
• new feature - change that adds functionality
• tests - change in tests
• infrastructure - change in infrastructure and CI
• documentation - documentation update

Tests

• added - required for new features and some bug fixes
• not needed

Documentation

• updated in # - add PR number
• needs to be updated
• not needed

Breaks backward compatibility

• Yes
• No
• Unknown

Notify the following users

List users with @ to send notifications

Other information

[vossmjp]

Suggested change

	Extending the oneTBB Flow Graph interface with the new ``try_put_and_wait(msg)`` API which allows to wait
	for completion of the chain of tasks corresponding to the ``msg``.
	This feature extends the oneTBB Flow Graph interface with a ``try_put_and_wait(msg)`` API that supports waiting
	for completion of the chain of tasks related to ``msg``.

[vossmjp]

Suggested change

	The feature should improve the Flow Graph performance in scenarios where multiple threads submits the work into the
	Flow Graph simultaneously and each of them should
	The feature may improve Flow Graph performance in scenarios where multiple threads submit work into the same
	Flow Graph and each of them need to wait for only the work associated with their message to complete.

[vossmjp]

Suggested change

	Current API of oneTBB Flow Graph allows doing two basic actions after building the graph:
	Without this feature, the oneTBB Flow Graph supports two basic actions after building the graph:

[vossmjp]

Suggested change

	- Waiting for completion of **all** messages in ghe graph using the ``graph.wait_for_all()`` API.
	- Waiting for completion of **all** messages in the graph using the ``graph.wait_for_all()`` API.

[vossmjp]

Suggested change

	when the work is done. Having only ``graph.wait_for_all()`` forces the thread to wait until **all** of the tasks in the Flow Graph, no meter
	corresponds to the waited message or not.
	when the work is done. Having only ``graph.wait_for_all()`` forces the thread to wait until **all** of the tasks in the Flow Graph complete,
	even those that are unrelated to the message it submitted.

[vossmjp]

Suggested change

	## Proposal
	## Overview of experimental feature

[vossmjp]

Suggested change

	The idea of this proposal is to extend the existing Flow Graph API with the new member function of each receiver nodes -
	This feature extends the existing Flow Graph API with an additional member function for each of the receiver nodes -

[vossmjp]

Suggested change

	``node.try_put_and_wait(msg)``. This function should submit the msg into the Flow Graph (similarly to ``try_put()``) and wait for its completion. The function should be exited only if all of the tasks corresponds to the ``msg`` and skip waiting for any other tasks to
	complete.
	``node.try_put_and_wait(msg)``. This function submits the msg into the Flow Graph (similarly to ``try_put()``) and wait for its completion.
	The function blocks until all of the tasks related to processing ``msg`` complete and is allowed to skip waiting for any
	other tasks to complete.

[vossmjp]

Suggested change

	Each message is broadcasted from ``start`` to three concurrent computational functions ``f1``, ``f2`` and ``f3``. The result is when joined into single tuple in ``join`` node and
	post-processed in a serial ``pf`` function node. The task queue corresponding to each node in the graph is exposed under the node in the picture. The tasks that corresponds
	to the parallel loop 0-100 are shown as blue tasks in the queue. Red tasks corresponds to the message submitted as an argument in ``try_put_and_wait``.
	The ``try_put_and_wait`` is expected to exit when all of the red tasks and the necessary amount of blue tasks would be completed. Completion of all blue tasks as in ``wait_for_all``
	is not guaranteed.
	Each message is broadcasted from ``start`` to three concurrent computational functions ``f1``, ``f2`` and ``f3``.
	The result is joined into single tuple in ``join`` node and post-processed in a serial ``pf`` function node.
	The task queue corresponding to each node in the graph is exposed under the node in the picture.
	The tasks that corresponds to the parallel loop 0-100 are shown as blue tasks in the queue. Red tasks
	correspond to the message submitted as an argument in ``try_put_and_wait``. The ``try_put_and_wait`` is
	expected to exit when all of the red tasks and the necessary amount of blue tasks are completed. Completion
	of all blue tasks as in ``wait_for_all`` is not guaranteed.

[vossmjp]

Suggested change

	From the implementation perspective, the feature is implemented currently by creating an instance of special class ``message_metainfo`` with the input message in ``try_put_and_wait``
	## Feature Design
	From the implementation perspective, the feature is implemented currently by creating an instance of special class ``message_metainfo`` with the input message in ``try_put_and_wait``