Update documentation for oneTBB 2021.6 (#836)

* Update pull_request_template.md (#751) Signed-off-by: Alexandra Epanchinzeva [email protected] (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 <[email protected]> Co-authored-by: Alexandra <[email protected]> (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 <[email protected]> (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 <[email protected]> Co-authored-by: Aleksei Fedotov <[email protected]> Co-authored-by: Alexandra Epanchinzeva <[email protected]> (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 <[email protected]> (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 <[email protected]> Co-authored-by: Alexandra <[email protected]> (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 <[email protected]> Co-authored-by: Anton Potapov <[email protected]> Co-authored-by: Aleksei Fedotov <[email protected]> Co-authored-by: Vladimir Serov <[email protected]> Co-authored-by: Ilya Isaev <[email protected]> Co-authored-by: Anton Potapov <[email protected]>
uxlfoundation · Aug 9, 2022 · c8504c4 · c8504c4
1 parent 4533e4f
commit c8504c4
Show file tree

Hide file tree

Showing 34 changed files with 604 additions and 430 deletions.
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
@@ -1,26 +1,26 @@
 ### Description 
-_Add comprehensive description of proposed changes_
+_Add a comprehensive description of proposed changes_
 
 
 Fixes # - _issue number(s) if exists_
 
-- [ ] - git commit message contains appropriate signed-off-by string _(see [CONTRIBUTING.md](https://github.com/oneapi-src/oneTBB/blob/master/CONTRIBUTING.md#pull-requests) for details)_
+- [ ] - git commit message contains an appropriate signed-off-by string _(see [CONTRIBUTING.md](https://github.com/oneapi-src/oneTBB/blob/master/CONTRIBUTING.md#pull-requests) for details)_
 
 ### Type of change
 
 _Choose one or multiple, leave empty if none of the other choices apply_
 
-_Add respective label(s) to PR if you have permissions_
+_Add a respective label(s) to PR if you have permissions_
 
-- [ ] bug fix - _change which fixes an issue_
-- [ ] new feature - _change which adds functionality_
+- [ ] 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 for some bug fixes_
+- [ ] added - _required for new features and some bug fixes_
 - [ ] not needed
 
 ### Documentation

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -38,18 +38,21 @@ You can use issues to report a problem, make a feature request, or add comments
 
 You can find all [open oneTBB pull requests](https://github.com/oneapi-src/oneTBB/pulls) on GitHub. 
 
-No anonymous contributions are accepted. The name in the commit message Signed-of-by line and your email must match the change authorship information.  Make sure your .gitconfig is set up correctly so you can use `git commit -s` for signing your patches: 
+No anonymous contributions are accepted. The name in the commit message Signed-off-by line and your email must match the change authorship information.  Make sure your .gitconfig is set up correctly so you can use `git commit -s` for signing your patches: 
 
 `git config --global user.name "Taylor Developer"`
 
 `git config --global user.email [email protected]`
 
-
-Before contributing changes directly to the oneTBB repository: 
+### Before contributing changes directly to the oneTBB repository
 
 * Make sure you can build the product and run all the tests with your patch. 
 * For a larger feature, provide a relevant test. 
 * Document your code. The oneTBB project uses reStructuredText for documentation.  
+* Update the copyright year in the first line of the changing file(s). 
+  For example, if you commit your changes in 2022:
+  * the copyright year should be `2005-2022` for existing files
+  * the copyright year should be `2022` for new files
 * Submit a pull request into the master branch. You can submit changes with a pull request (preferred) or by sending an email patch.  
 
 Continuous Integration (CI) testing is enabled for the repository. Your pull request must pass all checks before it can be merged. We will review your contribution and may provide feedback to guide you if any additional fixes or modifications are necessary. When reviewed and accepted, your pull request will be merged into our GitHub repository. 
diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md
@@ -18,17 +18,15 @@
 This document contains changes of oneTBB compared to the last release.
 
 ## Table of Contents <!-- omit in toc -->
-- [Preview Features](#preview-features)
 - [New Features](#new_features)
 - [Known Limitations](#known-limitations)
 - [Fixed Issues](#fixed-issues)
-
-
-## :computer: Preview Features
-- Extended task_group interface with a new run_and_wait overload to accept task_handle.
+- [Open-source Contributions Integrated](#open-source-contributions-integrated)
 
 ## :white_check_mark: New Features
-- Enabled Microsoft Visual Studio* 2022 and Python 3.9 support.
+- Improved support and use of the latest C++ standards for parallel_sort that allows using this algorithm with user-defined and standard library-defined objects with modern semantics.
+- The following features are now fully functional: task_arena extensions, collaborative_call_once, adaptive mutexes, heterogeneous overloads for concurrent_hash_map, and task_scheduler_handle.
+- Added support for Windows* Server 2022 and Python 3.10.
 
 ## :rotating_light: Known Limitations
 - An application using Parallel STL algorithms in libstdc++ versions 9 and 10 may fail to compile due to incompatible interface changes between earlier versions of Threading Building Blocks (TBB) and oneAPI Threading Building Blocks (oneTBB). Disable support for Parallel STL algorithms by defining PSTL_USE_PARALLEL_POLICIES (in libstdc++ 9) or _GLIBCXX_USE_TBB_PAR_BACKEND (in libstdc++ 10) macro to zero before inclusion of the first standard header file in each translation unit.
@@ -41,7 +39,15 @@ This document contains changes of oneTBB compared to the last release.
 - C++ exception handling mechanism on Windows* OS on ARM64* might corrupt memory if an exception is thrown from any oneTBB parallel algorithm (see Windows* OS on ARM64* compiler issue: https://developercommunity.visualstudio.com/t/ARM64-incorrect-stack-unwinding-for-alig/1544293).
 
 ## :hammer: Fixed Issues
-- Reworked synchronization mechanism to reduce contention when multiple task_arena's are used concurrently.
-- Fixed possible correctness issue in queuing_rw_mutex on non-Intel platforms.
-- Fixed GCC* 11 warnings.
-- Fixed sporadic memory corruption.
+- Memory allocator crash on a system with an incomplete /proc/meminfo (GitHub* [#584](https://github.com/oneapi-src/oneTBB/issues/584)).
+- Incorrect blocking of task stealing (GitHub* #[478](https://github.com/oneapi-src/oneTBB/issues/478)).
+- Hang due to incorrect decrement of a limiter_node (GitHub* [#634](https://github.com/oneapi-src/oneTBB/issues/634)).
+- Memory corruption in some rare cases when passing big messages in a flow graph (GitHub* [#639](https://github.com/oneapi-src/oneTBB/issues/639)).
+- Possible deadlock in a throwable flow graph node with a lightweight policy. The lightweight policy is now ignored for functors that can throw exceptions (GitHub* [#420](https://github.com/oneapi-src/oneTBB/issues/420)).
+- Crash when obtaining a range from empty ordered and unordered containers (GitHub* [#641](https://github.com/oneapi-src/oneTBB/issues/641)).
+- Deadlock in a concurrent_vector resize() that could happen when the new size is less than the previous size (GitHub* [#733](https://github.com/oneapi-src/oneTBB/issues/733)).
+
+## :octocat: Open-source Contributions Integrated
+- Improved aligned memory allocation. Contributed by Andrey Semashev (https://github.com/oneapi-src/oneTBB/pull/671).
+- Optimized usage of atomic_fence on IA-32 and Intel(R) 64 architectures. Contributed by Andrey Semashev (https://github.com/oneapi-src/oneTBB/pull/328).
+- Fixed incorrect definition of the assignment operator in containers. Contributed by Andrey Semashev (https://github.com/oneapi-src/oneTBB/issues/372).
diff --git a/doc/GSG/Images/how-oneTBB-works.png b/doc/GSG/Images/how-oneTBB-works.png
diff --git a/doc/GSG/examples.rst b/doc/GSG/examples.rst
@@ -0,0 +1,45 @@
+.. _examples:
+
+oneTBB Samples
+==============
+
+Refer to the following examples to see how |short_name| works. 
+
+* **Containers** 
+
+  * `concurrent_hash_map <https://github.com/oneapi-src/oneTBB/tree/master/examples/concurrent_hash_map>`_ 
+  * `concurrent_priority_queue <https://github.com/oneapi-src/oneTBB/tree/master/examples/concurrent_priority_queue>`_ 
+
+* `Flow Graph <https://github.com/oneapi-src/oneTBB/tree/master/examples/graph>`_ 
+   * `A solution to the binpacking problem using a queue_node, a buffer_node, and function_node. <https://github.com/oneapi-src/oneTBB/tree/master/examples/graph/binpack>`_ 
+   * `Cholesky Factorization algorithm <https://github.com/oneapi-src/oneTBB/tree/master/examples/graph/cholesky>`_
+   * `An implementation of dining philosophers in graph using the reserving join_node <https://github.com/oneapi-src/oneTBB/tree/master/examples/graph/dining_philosophers>`_
+   * `A parallel implementation of bzip2 block-sorting file compressor <https://github.com/oneapi-src/oneTBB/tree/master/examples/graph/fgbzip2>`_
+   * `An example of a collection of digital logic gates that can be easily composed into larger circuits <https://github.com/oneapi-src/oneTBB/tree/master/examples/graph/logic_sim>`_
+   * `An example of a Kohonen Self-Organizing Map using cancellation <https://github.com/oneapi-src/oneTBB/tree/master/examples/graph/som>`_
+   * `Split computational kernel for execution between CPU and GPU <https://github.com/oneapi-src/oneAPI-samples/tree/master/Libraries/oneTBB/tbb-async-sycl>`_
+
+* **Algorithms**
+
+  * `parallel_for <https://github.com/oneapi-src/oneTBB/tree/master/examples/parallel_for>`_
+     * `Game of life overlay <https://github.com/oneapi-src/oneTBB/tree/master/examples/parallel_for/game_of_life>`_
+     * `Polygon overlay <https://github.com/oneapi-src/oneTBB/tree/master/examples/parallel_for/polygon_overlay>`_
+     * `Parallel seismic wave simulation <https://github.com/oneapi-src/oneTBB/tree/master/examples/parallel_for/seismic>`_
+     * `Parallel 2-D raytracer/renderer <https://github.com/oneapi-src/oneTBB/tree/master/examples/parallel_for/tachyon>`_
+     * `Find largest matching substrings <https://github.com/oneapi-src/oneTBB/tree/master/examples/getting_started>`_
+     * `Resumable task: Split computational kernel for execution between CPU and GPU <https://github.com/oneapi-src/oneAPI-samples/tree/master/Libraries/oneTBB/tbb-resumable-tasks-sycl>`_
+  * `parallel_for_each <https://github.com/oneapi-src/oneTBB/tree/master/examples/parallel_for_each>`_
+  * `parallel_pipeline <https://github.com/oneapi-src/oneTBB/tree/master/examples/parallel_pipeline>`_
+  * `parallel_reduce <https://github.com/oneapi-src/oneTBB/tree/master/examples/parallel_reduce>`_
+
+* **Task Scheduler**
+
+  * `task_arena <https://github.com/oneapi-src/oneTBB/tree/master/examples/task_arena>`_
+  * `task_group <https://github.com/oneapi-src/oneTBB/tree/master/examples/task_group>`_
+  * `Execute similar computational kernels, with one task executing the SYCL* code and the other task executing the oneTBB code <https://github.com/oneapi-src/oneAPI-samples/tree/master/Libraries/oneTBB/tbb-task-sycl>`_
+
+* **Other**
+
+  * `Compute Fibonacci numbers in different ways <https://github.com/oneapi-src/oneTBB/tree/master/examples/test_all>`_
+
+
diff --git a/doc/GSG/installation.rst b/doc/GSG/installation.rst
@@ -0,0 +1,7 @@
+.. _installation:
+
+Installation
+============
+
+See the `installation instructions <https://github.com/oneapi-src/oneTBB/blob/master/INSTALL.md>`_ 
+that will help you to install |short_name| successfully.  
diff --git a/doc/GSG/intro_gsg.rst b/doc/GSG/intro_gsg.rst
@@ -1,13 +1,23 @@
 .. _Intro_gsg:
 
 
-|short_name| is a runtime-based parallel programming model for C++ code that uses threads. 
-It enables you to simplify parallel programming by breaking 
-computation into parallel running tasks. 
-The library consists of a template-based runtime library to help you harness the latent performance
-of multi-core processors. Use |short_name| to write scalable applications that:
+|full_name| is a runtime-based parallel programming model for C++ code that uses threads. 
+It consists of a template-based runtime library to help you harness the latent performance of multi-core processors.
 
+oneTBB enables you to simplify parallel programming by breaking computation into parallel running tasks. Within a single process, 
+parallelism is carried out through threads, an operating system mechanism that allows the same or different sets of instructions 
+to be executed simultaneously.
 
-- Specify logical parallel structure instead of threads
-- Emphasize data parallel programming
-- Take advantage of concurrent collections and parallel algorithms
+Here you can see one of the possible executions of tasks by threads.
+
+.. figure:: /GSG/Images/how-oneTBB-works.png
+   :scale: 70%
+   :align: center
+
+Use oneTBB to write scalable applications that:
+
+* Specify logical parallel structure instead of threads
+* Emphasize data-parallel programming
+* Take advantage of concurrent collections and parallel algorithms
+
+oneTBB supports nested parallelism and load balancing. It means that you can use the library without being worried about oversubscribing a system.
diff --git a/doc/Makefile b/doc/Makefile
@@ -0,0 +1,36 @@
+#===============================================================================
+# Copyright (C) 2022 Intel Corporation
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#===============================================================================
+
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = doc
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
diff --git a/doc/README.md b/doc/README.md
@@ -0,0 +1,34 @@
+# How to build oneTBB documentation
+
+Our documentation is written in restructured text markup (.rst) and built using [Sphinx](http://www.sphinx-doc.org/en/master/). 
+
+This document explains how to build oneTBB documentation locally. 
+
+## Prerequisites
+- Python 3.7.0 or higher
+- Sphinx 
+
+## Build documentation
+
+Do the following to generate HTML output of the documentation: 
+
+1. Clone oneTBB repository:
+
+```
+git clone https://github.com/oneapi-src/oneTBB.git
+```
+
+2. Go to the `doc` folder:
+
+```
+cd oneTBB/doc
+```
+
+3. Run in the command line:
+
+```
+make html
+```
+
+
+That's it! Your built documentation is located in the ``build/html`` folder. 
diff --git a/doc/conf.py b/doc/conf.py
@@ -29,7 +29,7 @@
     project = u'Intel® oneAPI Threading Building Blocks (oneTBB)'
 else:
     project = u'oneTBB'
-copyright = u'2021, Intel Corporation'
+copyright = u'2022, Intel Corporation'
 author = u'Intel'
 
 # The short X.Y version
@@ -60,7 +60,7 @@
 ]
 
 # Add any paths that contain templates here, relative to this directory.
-templates_path = ['_templates']
+templates_path = ['main/_templates']
 
 # The suffix(es) of source filenames.
 # You can specify multiple suffix as a list of string:
@@ -120,21 +120,26 @@
 # further.  For a list of options available for each theme, see the
 # documentation.
 #
-if BUILD_TYPE == 'oneapi' or BUILD_TYPE == 'dita':
-    html_theme = 'sphinx_rtd_theme'
+
+html_theme = 'sphinx_book_theme'
+
+if BUILD_TYPE == 'dita':
+    html_theme_options = {
+        'repository_url': 'https://github.com/oneapi-src/oneTBB',
+        'path_to_docs': 'doc',
+        'repository_branch': 'master'
+    }
 else:
-    html_theme = 'sphinx_book_theme'
     html_theme_options = {
-    'repository_url': 'https://github.com/oneapi-src/oneTBB',
-    'path_to_docs': 'doc/main',
-    'use_issues_button': True,
-    'use_edit_page_button': True,
-    'repository_branch': 'master',
-    'extra_footer': '<p align="right"><a href="https://www.intel.com/content/www/us/en/privacy/intel-cookie-notice.html">Cookies</a></p>'
+        'repository_url': 'https://github.com/oneapi-src/oneTBB',
+        'path_to_docs': 'doc/main',
+        'use_issues_button': True,
+        'use_edit_page_button': True,
+        'repository_branch': 'master',
+        'extra_footer': '<p align="right"><a href="https://www.intel.com/content/www/us/en/privacy/intel-cookie-notice.html">Cookies</a></p>'
     }
 
 
-
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
@@ -148,8 +153,9 @@
     }
 else:
     html_js_files = ['custom.js']
-    html_logo = '_static/oneAPI-rgb-rev-100.png'
+
 
+html_logo = '_static/oneAPI-rgb-rev-100.png'
 html_favicon = '_static/favicons.png'
 
 # Custom sidebar templates, must be a dictionary that maps document names

diff --git a/doc/index/index_intro.rst b/doc/index/index_intro.rst
@@ -2,3 +2,4 @@
 
 This document contains information about |short_name|. 
 It is a flexible performance library that let you break computation into parallel running tasks. 
+
diff --git a/doc/index/toctree.rst b/doc/index/toctree.rst
@@ -1,13 +1,33 @@
 .. _toctree:
 
 .. toctree::
+   :caption: About
+   :maxdepth: 1
+
+   /main/intro/help_support
+   /main/intro/notation
+   /main/intro/intro_os
+   /main/intro/Benefits
+
+
+.. toctree::
+   :caption: Get Started
    :maxdepth: 2
 
-   main/intro/help_support
-   main/intro/notation
-   main/intro/intro_os
-   main/intro/Benefits
-   GSG/get_started
-   main/tbb_userguide/title
-   main/reference/reference
-   main/intro/notices_and_disclaimers
+   /GSG/get_started
+   /GSG/installation
+   /GSG/examples
+
+
+.. toctree::
+   :maxdepth: 3
+   :caption: Developer Guide
+
+   /main/tbb_userguide/title
+
+
+.. toctree::
+   :maxdepth: 3
+   :caption: Developer Reference
+
+   /main/reference/reference
diff --git a/doc/main/_templates/layout.html b/doc/main/_templates/layout.html
@@ -6,10 +6,12 @@
         var wapLocalCode = 'us-en'; // Dynamically set per localized site, see mapping table for values
         var wapSection = "oneapi-tbb"; // WAP team will give you a unique section for your site
         // Load TMS
-        (function () {
-          var url = 'https://www.intel.com/content/dam/www/global/wap/tms-loader.js'; // WAP file URL
-          var po = document.createElement('script'); po.type = 'text/javascript'; po.async = true; po.src = url;
-          var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(po, s);
+        if(document.location.href.contains("oneapi-src.github.io")){
+            (function () {
+              var url = 'https://www.intel.com/content/dam/www/global/wap/tms-loader.js'; // WAP file URL
+              var po = document.createElement('script'); po.type = 'text/javascript'; po.async = true; po.src = url;
+              var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(po, s);
         })();
+        }
       </script>
 {% endblock %}