Document a way to flow graph can be attached to arbitrary task_arena #785

vlserov · 2022-02-22T07:36:37Z

Description

Adding documentation to describes a way to flow::graph can be attached to arbitrary task_arena

Fixes # - issue number(s) if exists

- git commit message contains an appropriate signed-off-by string (see CONTRIBUTING.md for details)

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

@aleksei-fedotov @alexandraepan

Other information

Signed-off-by: Serov, Vladimir <vladimir.serov@intel.com>

aepanchi · 2022-02-22T09:40:35Z

doc/main/tbb_userguide/attach_flow_graph_to_arena.rst

@@ -0,0 +1,62 @@
+.. _attach_flow_graph_to_arena:
+
+Attach Flow Graph to arbitrary Task Arena


Suggested change

Attach Flow Graph to arbitrary Task Arena

Attach Flow Graph to an Arbitrary Task Arena

Maybe it is worth adding in which cases a user may need to attach flow graph to task arena

Changes has been applied.

aepanchi · 2022-02-22T09:40:54Z

doc/main/tbb_userguide/attach_flow_graph_to_arena.rst

+======================
+
+
+During construction a ``graph`` object captures a reference to the arena of the thread that


Suggested change

During construction a ``graph`` object captures a reference to the arena of the thread that

During construction, a ``graph`` object captures a reference to the arena of the thread that

aepanchi · 2022-02-22T10:03:27Z

doc/main/tbb_userguide/attach_flow_graph_to_arena.rst

+
+
+During construction a ``graph`` object captures a reference to the arena of the thread that
+constructed the object. Whenever a task is spawned to execute work in the graph, the tasks


Suggested change

constructed the object. Whenever a task is spawned to execute work in the graph, the tasks

constructed the object. When a task is spawned to execute work in a graph, the tasks

aepanchi · 2022-02-22T10:03:56Z

doc/main/tbb_userguide/attach_flow_graph_to_arena.rst

+
+During construction a ``graph`` object captures a reference to the arena of the thread that
+constructed the object. Whenever a task is spawned to execute work in the graph, the tasks
+are spawned in this arena, not in the arena of the that caused the task to be spawned.


Suggested change

are spawned in this arena, not in the arena of the that caused the task to be spawned.

are spawned in that arena, not in the arena that caused the task to be spawned.

aepanchi · 2022-02-22T10:04:22Z

doc/main/tbb_userguide/attach_flow_graph_to_arena.rst

+During construction a ``graph`` object captures a reference to the arena of the thread that
+constructed the object. Whenever a task is spawned to execute work in the graph, the tasks
+are spawned in this arena, not in the arena of the that caused the task to be spawned.
+All tasks are spawned into a single arena, the arena of the thread that constructed the graph


Suggested change

All tasks are spawned into a single arena, the arena of the thread that constructed the graph

All tasks are spawned into a single arena that constructed a graph

aepanchi · 2022-02-22T10:11:55Z

doc/main/tbb_userguide/attach_flow_graph_to_arena.rst

+       } );
+
+
+Since the main thread constructs the ``graph`` object, the ``graph`` will use the default arena,


Suggested change

Since the main thread constructs the ``graph`` object, the ``graph`` will use the default arena,

Since the main thread constructs the ``graph`` object, the ``graph`` uses the default arena.

aepanchi · 2022-02-22T10:12:45Z

doc/main/tbb_userguide/attach_flow_graph_to_arena.rst

+
+
+Since the main thread constructs the ``graph`` object, the ``graph`` will use the default arena,
+which we initialize with eight slots. After calling ``reset`` function to reinitialize


Suggested change

which we initialize with eight slots. After calling ``reset`` function to reinitialize

Such an arena is initialized with eight slots. After calling the ``reset`` function to reinitialize

aepanchi · 2022-02-22T10:13:09Z

doc/main/tbb_userguide/attach_flow_graph_to_arena.rst

+
+Since the main thread constructs the ``graph`` object, the ``graph`` will use the default arena,
+which we initialize with eight slots. After calling ``reset`` function to reinitialize
+the graph and nodes executes in arena ``arena``.


Not clear what is this sentence for.

Removed as not necessary.

aepanchi · 2022-02-22T10:13:49Z

doc/main/tbb_userguide/attach_flow_graph_to_arena.rst

+the graph and nodes executes in arena ``arena``.
+
+
+So performance tuning optimizations which is described in sections below can be applied for


Suggested change

So performance tuning optimizations which is described in sections below can be applied for

A performance tuning optimization can be applied for

aepanchi · 2022-02-22T10:14:20Z

doc/main/tbb_userguide/attach_flow_graph_to_arena.rst

+
+
+So performance tuning optimizations which is described in sections below can be applied for
+flow graphs as well.


Suggested change

flow graphs as well.

flow graphs as well. See the following topics to learn more.

aleksei-fedotov

Please see my comments below.

Also, let's move source code into separate files so that they are automatically tested when the automation task for testing of samples from the docs is ready.

doc/main/tbb_userguide/attach_flow_graph_to_arena.rst

Signed-off-by: Serov, Vladimir <vladimir.serov@intel.com> Co-authored-by: Aleksei Fedotov <aleksei.fedotov@intel.com> Co-authored-by: Alexandra Epanchinzeva <alexandra.epanchinzeva@intel.com>

aleksei-fedotov · 2022-03-04T14:02:45Z

doc/main/tbb_userguide/attach_flow_graph_to_arena.rst

+thread occupies a slot. Whenever a task is spawned on behalf of the graph, it is spawned
+in the arena of the graph it is attached to, disregarding the arena of the thread
+which is caused a task to be spawned.


I think that the second sentence in this paragraph better be moved closer to the second example as the example now shows this explicitly and so may raise questions of readers.

Perhaps, the best place for it is right after the example introduction words, i.e. line #41.

Updated with suggested changes.

aleksei-fedotov · 2022-03-04T14:36:46Z

doc/main/tbb_userguide/attach_flow_graph_to_arena.rst

+       graph g;
+       function_node< int > f( g, unlimited, []( int i ) {
+           /*the most performant core type is defined as preferred.*/
+       } );
+       std::vector<tbb::core_type_id> core_types = tbb::info::core_types();
+       tbb::task_arena arena(
+           tbb::task_arena::constraints{}.set_core_type(core_types.back())
+       );
+       arena.execute( [&]() {
+           g.reset();
+       } );
+       f.try_put(1);
+       g.wait_for_all();


I also asked a question about moving the code into separate source file for further simpler testing.
I found this approach that can work for us. Can we use it?

@aleksei-fedotov We definitely can make it work :)

Moved to separate source file

doc/main/tbb_userguide/attach_flow_graph_to_arena.rst

aepanchi · 2022-03-04T15:43:53Z

doc/main/tbb_userguide/attach_flow_graph_to_arena.rst

+During its construction a ``graph`` object attaches to the arena, in which the constructing
+thread occupies a slot. Whenever a task is spawned on behalf of the graph, it is spawned
+in the arena of the graph it is attached to, disregarding the arena of the thread
+which is caused a task to be spawned.


Suggested change

which is caused a task to be spawned.

that the task is spawned from.

Updated with suggested changes.

aepanchi · 2022-03-04T15:44:19Z

doc/main/tbb_userguide/attach_flow_graph_to_arena.rst

+thread occupies a slot. Whenever a task is spawned on behalf of the graph, it is spawned
+in the arena of the graph it is attached to, disregarding the arena of the thread
+which is caused a task to be spawned.


aepanchi · 2022-03-04T15:45:31Z

doc/main/tbb_userguide/attach_flow_graph_to_arena.rst

+in the arena of the graph it is attached to, disregarding the arena of the thread
+which is caused a task to be spawned.
+
+The example shows how to set the most performant core type as preferable for graph execution:


Suggested change

The example shows how to set the most performant core type as preferable for graph execution:

This example shows how to set the most performant core type as the preferred one for a graph execution:

Updated with suggested changes.

aepanchi · 2022-03-04T15:47:38Z

doc/main/tbb_userguide/attach_flow_graph_to_arena.rst

+
+A ``graph`` object can be reattached to a different ``task_arena`` by calling
+the ``graph::reset()`` function. This reinitializes the ``graph`` and reattaches
+it to the task arena instance, inside which the ``graph::reset()`` method is executed.


Suggested change

it to the task arena instance, inside which the ``graph::reset()`` method is executed.

the ``graph`` to the task arena instance, inside which the ``graph::reset()`` method is executed.

Updated with suggested changes.

aepanchi · 2022-03-04T15:48:01Z

doc/main/tbb_userguide/attach_flow_graph_to_arena.rst

+the ``graph::reset()`` function. This reinitializes the ``graph`` and reattaches
+it to the task arena instance, inside which the ``graph::reset()`` method is executed.
+
+The example shows how reattach existing graph to an arena with the most performant core type


Suggested change

The example shows how reattach existing graph to an arena with the most performant core type

This example shows how to reattach existing graph to an arena with the most performant core type

Updated with suggested changes.

aepanchi · 2022-03-04T15:48:27Z

doc/main/tbb_userguide/attach_flow_graph_to_arena.rst

+it to the task arena instance, inside which the ``graph::reset()`` method is executed.
+
+The example shows how reattach existing graph to an arena with the most performant core type
+as preferable for work execution:


Suggested change

as preferable for work execution:

as the preferred one for a work execution:

Updated with suggested changes.

aepanchi · 2022-03-04T15:49:40Z

doc/main/tbb_userguide/attach_flow_graph_to_arena.rst

+       graph g;
+       function_node< int > f( g, unlimited, []( int i ) {
+           /*the most performant core type is defined as preferred.*/
+       } );
+       std::vector<tbb::core_type_id> core_types = tbb::info::core_types();
+       tbb::task_arena arena(
+           tbb::task_arena::constraints{}.set_core_type(core_types.back())
+       );
+       arena.execute( [&]() {
+           g.reset();
+       } );
+       f.try_put(1);
+       g.wait_for_all();


@aleksei-fedotov We definitely can make it work :)

aepanchi · 2022-03-04T15:49:50Z

doc/main/tbb_userguide/attach_flow_graph_to_arena.rst

+       f.try_put(1);
+       g.wait_for_all();
+
+See the following topics to learn more.


Suggested change

See the following topics to learn more.

See the following topics to learn more:

Updated with suggested changes.

Co-authored-by: Aleksei Fedotov <aleksei.fedotov@intel.com>

Co-authored-by: Alexandra <alexandra.epanchinzeva@intel.com>

Moving examples to separate source file. Signed-off-by: Serov, Vladimir <vladimir.serov@intel.com> Co-authored-by: Aleksei Fedotov <aleksei.fedotov@intel.com> Co-authored-by: Alexandra Epanchinzeva <alexandra.epanchinzeva@intel.com>

aepanchi

the rest looks good!

doc/main/tbb_userguide/attach_flow_graph_to_arena.rst

Co-authored-by: Alexandra <alexandra.epanchinzeva@intel.com>

aleksei-fedotov

Now looks much better to me! There is a couple of questions left, though.

doc/main/tbb_userguide/attach_flow_graph_to_arena.rst

doc/main/tbb_userguide/snippets/flow_graph_examples.cpp

Co-authored-by: Aleksei Fedotov <aleksei.fedotov@intel.com>

aleksei-fedotov

Thanks Vladimir!

Hope readers won't be nit-picking regarding the other details necessary to make the example fully compilable.

…xlfoundation#785) * Document a way to flow graph can be attached to arbitrary task_arena task_arena interface provides mechanisms to guide tasks execution within the arena by setting the preferred computation units or restricting part of computation units. In some cases, you may want to use mechanisms within a flow graph. Signed-off-by: Serov, Vladimir <vladimir.serov@intel.com> Co-authored-by: Aleksei Fedotov <aleksei.fedotov@intel.com> Co-authored-by: Alexandra Epanchinzeva <alexandra.epanchinzeva@intel.com> (cherry picked from commit a938322)

* Update pull_request_template.md (#751) Signed-off-by: Alexandra Epanchinzeva alexandra.epanchinzeva@intel.com (cherry picked from commit 4eda0f9) * Update CONTRIBUTING.md (#765) (cherry picked from commit e274a9e) * Documentation update for unpreview `task_handle` and related stuff (#755) * Unpreview task_handle and related stuff Signed-off-by: Anton Potapov <anton.potapov@intel.com> Co-authored-by: Alexandra <alexandra.epanchinzeva@intel.com> (cherry picked from commit fd76f45) * Update conf.py (#774) (cherry picked from commit 6666292) * Actualize documentation about proportional splitting constructor in Range (#728) Actualize documentation about proportional splitting Signed-off-by: Fedotov, Aleksei <aleksei.fedotov@intel.com> (cherry picked from commit e5cbe50) * Update doc structure and add new files (#791) (cherry picked from commit ce0d258) * Instruction for building the docs locally (#778) (cherry picked from commit e386960) * Document a way to flow graph can be attached to arbitrary task_arena (#785) * Document a way to flow graph can be attached to arbitrary task_arena task_arena interface provides mechanisms to guide tasks execution within the arena by setting the preferred computation units or restricting part of computation units. In some cases, you may want to use mechanisms within a flow graph. Signed-off-by: Serov, Vladimir <vladimir.serov@intel.com> Co-authored-by: Aleksei Fedotov <aleksei.fedotov@intel.com> Co-authored-by: Alexandra Epanchinzeva <alexandra.epanchinzeva@intel.com> (cherry picked from commit a938322) * Add topic about "Lazy Initiliazation" pattern to Design patterns (#790) New topic about Lazy initialization pattern and how it can be implemented using oneapi::tbb::collaborative_call_once has been added. Signed-off-by: Ilya Isaev <ilya.isaev@intel.com> (cherry picked from commit 1da8f0d) * Update Get Started Guide (#803) (cherry picked from commit 0502372) * Update intro_gsg.rst (#808) (cherry picked from commit 2c4f282) * Update conf.py (#810) (cherry picked from commit 0a0a592) * TBB DOC : Dev Guide: Task Scheduler Bypass and How Does Task Scheduler Works (#521) * TBB DOC : Dev Guide: Task Scheduler Bypass and How Task Scheduler Works Signed-off-by: Anton Potapov <anton.potapov@intel.com> Co-authored-by: Alexandra <alexandra.epanchinzeva@intel.com> (cherry picked from commit ed9d4b5) * Update intro_gsg.rst (#811) (cherry picked from commit efea993) * Update conf.py (#812) (cherry picked from commit 3859d11) * Update examples.rst (#816) (cherry picked from commit 4aa0b0b) * Update layout.html (#815) (cherry picked from commit 3e352b4) * Update RELEASE_NOTES.md for oneTBB 2021.6 (#835) (cherry picked from commit faaf43c) Co-authored-by: Alexandra <alexandra.epanchinzeva@intel.com> Co-authored-by: Anton Potapov <potapov.slash.co@gmail.com> Co-authored-by: Aleksei Fedotov <aleksei.fedotov@intel.com> Co-authored-by: Vladimir Serov <vladimir.serov@intel.com> Co-authored-by: Ilya Isaev <ilya.isaev@intel.com> Co-authored-by: Anton Potapov <anton.potapov@intel.com>

Document a way to flow graph can be attached to arbitrary task_arena

7ab56ed

Signed-off-by: Serov, Vladimir <vladimir.serov@intel.com>

vlserov requested review from aleksei-fedotov and aepanchi February 22, 2022 07:36

aepanchi reviewed Feb 22, 2022

View reviewed changes

aleksei-fedotov reviewed Feb 22, 2022

View reviewed changes

Updating with comments during code review.

69b4ed2

Signed-off-by: Serov, Vladimir <vladimir.serov@intel.com> Co-authored-by: Aleksei Fedotov <aleksei.fedotov@intel.com> Co-authored-by: Alexandra Epanchinzeva <alexandra.epanchinzeva@intel.com>

vlserov requested a review from aleksei-fedotov March 3, 2022 09:11

vlserov added the documentation label Mar 3, 2022

aleksei-fedotov reviewed Mar 4, 2022

View reviewed changes

aepanchi reviewed Mar 4, 2022

View reviewed changes

Vladimir Serov and others added 3 commits March 5, 2022 12:58

Update doc/main/tbb_userguide/attach_flow_graph_to_arena.rst

ea72ed2

Co-authored-by: Aleksei Fedotov <aleksei.fedotov@intel.com>

Update doc/main/tbb_userguide/attach_flow_graph_to_arena.rst

e44112e

Co-authored-by: Alexandra <alexandra.epanchinzeva@intel.com>

Updating with comments during code review.

286d1d8

Moving examples to separate source file. Signed-off-by: Serov, Vladimir <vladimir.serov@intel.com> Co-authored-by: Aleksei Fedotov <aleksei.fedotov@intel.com> Co-authored-by: Alexandra Epanchinzeva <alexandra.epanchinzeva@intel.com>

vlserov requested review from aleksei-fedotov and aepanchi March 9, 2022 07:51

aepanchi reviewed Mar 9, 2022

View reviewed changes

doc/main/tbb_userguide/attach_flow_graph_to_arena.rst Outdated Show resolved Hide resolved

Update doc/main/tbb_userguide/attach_flow_graph_to_arena.rst

2ed8684

Co-authored-by: Alexandra <alexandra.epanchinzeva@intel.com>

aleksei-fedotov reviewed Mar 9, 2022

View reviewed changes

doc/main/tbb_userguide/attach_flow_graph_to_arena.rst Outdated Show resolved Hide resolved

doc/main/tbb_userguide/snippets/flow_graph_examples.cpp Outdated Show resolved Hide resolved

Vladimir Serov and others added 2 commits March 9, 2022 12:45

Update doc/main/tbb_userguide/snippets/flow_graph_examples.cpp

28063bd

Co-authored-by: Aleksei Fedotov <aleksei.fedotov@intel.com>

Update doc/main/tbb_userguide/attach_flow_graph_to_arena.rst

6e848e2

Co-authored-by: Aleksei Fedotov <aleksei.fedotov@intel.com>

vlserov requested a review from aleksei-fedotov March 9, 2022 09:47

aleksei-fedotov approved these changes Mar 9, 2022

View reviewed changes

vlserov requested a review from aepanchi March 9, 2022 11:52

aepanchi approved these changes Mar 9, 2022

View reviewed changes

vlserov merged commit a938322 into master Mar 9, 2022

vlserov deleted the dev/vserov/flow_graph_arena branch March 9, 2022 12:04

isaevil mentioned this pull request Oct 6, 2022

limiter_node fails to decrement/open with continue_msg yet works with int #419

Closed

		@@ -0,0 +1,62 @@
		.. _attach_flow_graph_to_arena:

		Attach Flow Graph to arbitrary Task Arena

	Attach Flow Graph to arbitrary Task Arena
	Attach Flow Graph to an Arbitrary Task Arena

		======================


		During construction a ``graph`` object captures a reference to the arena of the thread that

	During construction a ``graph`` object captures a reference to the arena of the thread that
	During construction, a ``graph`` object captures a reference to the arena of the thread that



		During construction a ``graph`` object captures a reference to the arena of the thread that
		constructed the object. Whenever a task is spawned to execute work in the graph, the tasks

	constructed the object. Whenever a task is spawned to execute work in the graph, the tasks
	constructed the object. When a task is spawned to execute work in a graph, the tasks

	are spawned in this arena, not in the arena of the that caused the task to be spawned.
	are spawned in that arena, not in the arena that caused the task to be spawned.

	All tasks are spawned into a single arena, the arena of the thread that constructed the graph
	All tasks are spawned into a single arena that constructed a graph

		} );


		Since the main thread constructs the ``graph`` object, the ``graph`` will use the default arena,



		Since the main thread constructs the ``graph`` object, the ``graph`` will use the default arena,
		which we initialize with eight slots. After calling ``reset`` function to reinitialize

	which we initialize with eight slots. After calling ``reset`` function to reinitialize
	Such an arena is initialized with eight slots. After calling the ``reset`` function to reinitialize

		the graph and nodes executes in arena ``arena``.


		So performance tuning optimizations which is described in sections below can be applied for

	So performance tuning optimizations which is described in sections below can be applied for
	A performance tuning optimization can be applied for



		So performance tuning optimizations which is described in sections below can be applied for
		flow graphs as well.

	flow graphs as well.
	flow graphs as well. See the following topics to learn more.

	which is caused a task to be spawned.
	that the task is spawned from.

	The example shows how to set the most performant core type as preferable for graph execution:
	This example shows how to set the most performant core type as the preferred one for a graph execution:

	it to the task arena instance, inside which the ``graph::reset()`` method is executed.
	the ``graph`` to the task arena instance, inside which the ``graph::reset()`` method is executed.

	The example shows how reattach existing graph to an arena with the most performant core type
	This example shows how to reattach existing graph to an arena with the most performant core type

	as preferable for work execution:
	as the preferred one for a work execution:

Document a way to flow graph can be attached to arbitrary task_arena #785

Document a way to flow graph can be attached to arbitrary task_arena #785

Conversation

vlserov commented Feb 22, 2022

Description

Type of change

Tests

Documentation

Breaks backward compatibility

Notify the following users

Other information

aepanchi Feb 22, 2022 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

aleksei-fedotov left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

aepanchi left a comment

Choose a reason for hiding this comment

aleksei-fedotov left a comment

Choose a reason for hiding this comment

aleksei-fedotov left a comment

Choose a reason for hiding this comment

aepanchi Feb 22, 2022 •

edited

Loading

	See the following topics to learn more.
	See the following topics to learn more: