Add tasking documentation to user guide

doc/main/tbb_userguide/Parallelizing_with_Tasks.rst

@@ -0,0 +1,18 @@
+.. _Parallelizing_with_Tasks:
+
+Parallelizing with Tasks
+========================
+
+When parallel loops or the flow graph are not sufficient, the |full_name|
+library supports parallelization directly with tasks. Tasks
+can be created using the function ``oneapi::tbb::parallel_invoke`` or
+the class ``oneapi::tbb::task_group``. 
+
+
+.. toctree::
+   :maxdepth: 4
+
+   ../tbb_userguide/creating_tasks_with_parallel_invoke
+   ../tbb_userguide/creating_tasks_with_task_group
+   ../tbb_userguide/task_group_cancellation
+   ../tbb_userguide/task_group_thread_safety

doc/main/tbb_userguide/creating_tasks_with_parallel_invoke.rst

@@ -0,0 +1,55 @@
+.. _creating_tasks_with_parallel_invoke:
+
+Creating Tasks with parallel_invoke
+===================================
+
+Suppose you want to search a binary tree for the node that contains a specific value.
+Here is sequential code to do this:
+
+Nodes are represented by ``struct TreeNode``.
+
+.. literalinclude:: ./examples/task_examples.cpp
+    :language: c++
+    :start-after: /*begin_treenode*/
+    :end-before: /*end_treenode*/
+
+The function ``serial_tree_search`` is a recursive algorithm that checks the current node
+and, if the value is not found, calls itself on the left and right subtree. 
+
+.. literalinclude:: ./examples/task_examples.cpp
+    :language: c++
+    :start-after: /*begin_search_serial*/
+    :end-before: /*end_search_serial*/
+
+
+To improve performance, you can use ``oneapi::tbb::parallel_invoke`` to search the tree 
+in parallel:
+
+A recursive base case is used after a minimum size threshold is reached to avoid parallel overheads.
+Since more than one thread can call the base case concurrently as part of the same tree, ``result``
+is held in an atomic variable.
+
+.. literalinclude:: ./examples/task_examples.cpp
+    :language: c++
+    :start-after: /*begin_sequential_tree_search*/
+    :end-before: /*end_sequential_tree_search*/
+
+The function ``oneapi::tbb::parallel_invoke`` runs multiple independent tasks in parallel.
+Here is a function ``parallel_invoke_search``, where two lambdas are passed that define tasks
+that search the left and right subtrees of the current node in parallel:
+
+.. literalinclude:: ./examples/task_examples.cpp
+    :language: c++
+    :start-after: /*begin_parallel_invoke_search*/
+    :end-before: /*end_parallel_invoke_search*/
+
+If the value is found the pointer to the node that contains the value is stored
+in the ``std::atomic<TreeNode*> result``. This example uses recursion to create many tasks, instead of
+just two. The depth of the parallel recursion is limited by the ``depth_threshold`` parameter. After this depth is
+reached, the search falls back to a sequential approach. The value of ``result`` is periodically checked
+to see if the value has been found by other concurrent tasks, and if so, the search in the current task is
+terminated. Because multiple threads may access ``result`` concurrently, an atomic variable is used, even
+from the sequential base case.
+
+Because ``oneapi::tbb::parallel_invoke`` is a fork-join algorithm, each level of the recursion does not
+complete until both the left and right subtrees have completed.

doc/main/tbb_userguide/creating_tasks_with_task_group.rst

@@ -0,0 +1,51 @@
+.. _creating_tasks_with_task_group:
+
+Creating Tasks with task_group
+==============================
+
+The |full_name| library supports parallelization directly with tasks. The class 
+``oneapi::tbb::task_group`` is used to run and wait for tasks in a less
+structured way than ``oneapi::tbb::parallel_invoke``. It is useful when you want to
+create a set of tasks that can be run in parallel, but you do not know how many there
+will be in advance.
+
+Here is code that uses ``oneapi::tbb::task_group`` to implement a parallel search in
+a binary tree:
+
+Nodes are represented by ``struct TreeNode``.
+
+.. literalinclude:: ./examples/task_examples.cpp
+    :language: c++
+    :start-after: /*begin_treenode*/
+    :end-before: /*end_treenode*/
+
+A recursive base case is used after a minimum size threshold is reached to avoid parallel overheads.
+Since more than one thread can call the base case concurrently as part of the same tree, ``result``
+is held in an atomic variable.
+
+.. literalinclude:: ./examples/task_examples.cpp
+    :language: c++
+    :start-after: /*begin_sequential_tree_search*/
+    :end-before: /*end_sequential_tree_search*/
+
+In ``parallel_tree_search_impl``, ``task_group::run`` is used to create a new task for searching
+in the right subtree if both subtrees are valid. The recursion does not wait on the ``task_group``
+at each level and reuses the current task to search one of the subtrees. This can reduce the
+overhead of task creation and management, allowing for efficient use of resources.
+
+.. literalinclude:: ./examples/task_examples.cpp
+    :language: c++
+    :start-after: /*begin_parallel_search*/
+    :end-before: /*end_parallel_search*/
+
+This example uses recursion to create many tasks. The depth of the parallel recursion is
+limited by the ``depth_threshold`` parameter. After this depth is reached, no new tasks
+are created. The value of ``result`` is periodically checked to see if the value has been
+found by other concurrent tasks, and if so, the search in the current task is terminated.
+
+In this example, tasks that execute within the ``task_group tg`` add additional tasks
+by calling ``run`` on the same ``task_group`` object. These calls are thread-safe and the 
+call to ``tg.wait()`` will block until all of these tasks are complete. Although these
+additional tasks might be added from different worker threads, these additions are logically nested
+within the top-most calls to ``tg.run``. There is therefore no race in adding these tasks from
+the worker threads and waiting for them in the main thread.