Skip to content

Commit c8504c4

Browse files
ValentinaKatsaepanchianton-potapovaleksei-fedotovVladimir Serov
authored
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]>
1 parent 4533e4f commit c8504c4

34 files changed

+604
-430
lines changed

‎.github/pull_request_template.md

+6-6
Original file line numberDiff line numberDiff line change
@@ -1,26 +1,26 @@
11
### Description
2-
_Add comprehensive description of proposed changes_
2+
_Add a comprehensive description of proposed changes_
33

44

55
Fixes # - _issue number(s) if exists_
66

7-
- [ ] - 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)_
7+
- [ ] - 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)_
88

99
### Type of change
1010

1111
_Choose one or multiple, leave empty if none of the other choices apply_
1212

13-
_Add respective label(s) to PR if you have permissions_
13+
_Add a respective label(s) to PR if you have permissions_
1414

15-
- [ ] bug fix - _change which fixes an issue_
16-
- [ ] new feature - _change which adds functionality_
15+
- [ ] bug fix - _change that fixes an issue_
16+
- [ ] new feature - _change that adds functionality_
1717
- [ ] tests - _change in tests_
1818
- [ ] infrastructure - _change in infrastructure and CI_
1919
- [ ] documentation - _documentation update_
2020

2121
### Tests
2222

23-
- [ ] added - _required for new features and for some bug fixes_
23+
- [ ] added - _required for new features and some bug fixes_
2424
- [ ] not needed
2525

2626
### Documentation

‎CONTRIBUTING.md

+6-3
Original file line numberDiff line numberDiff line change
@@ -38,18 +38,21 @@ You can use issues to report a problem, make a feature request, or add comments
3838

3939
You can find all [open oneTBB pull requests](https://github.com/oneapi-src/oneTBB/pulls) on GitHub.
4040

41-
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:
41+
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:
4242

4343
`git config --global user.name "Taylor Developer"`
4444

4545
`git config --global user.email [email protected]`
4646

47-
48-
Before contributing changes directly to the oneTBB repository:
47+
### Before contributing changes directly to the oneTBB repository
4948

5049
* Make sure you can build the product and run all the tests with your patch.
5150
* For a larger feature, provide a relevant test.
5251
* Document your code. The oneTBB project uses reStructuredText for documentation.
52+
* Update the copyright year in the first line of the changing file(s).
53+
For example, if you commit your changes in 2022:
54+
* the copyright year should be `2005-2022` for existing files
55+
* the copyright year should be `2022` for new files
5356
* Submit a pull request into the master branch. You can submit changes with a pull request (preferred) or by sending an email patch.
5457

5558
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.

‎RELEASE_NOTES.md

+16-10
Original file line numberDiff line numberDiff line change
@@ -18,17 +18,15 @@
1818
This document contains changes of oneTBB compared to the last release.
1919

2020
## Table of Contents <!-- omit in toc -->
21-
- [Preview Features](#preview-features)
2221
- [New Features](#new_features)
2322
- [Known Limitations](#known-limitations)
2423
- [Fixed Issues](#fixed-issues)
25-
26-
27-
## :computer: Preview Features
28-
- Extended task_group interface with a new run_and_wait overload to accept task_handle.
24+
- [Open-source Contributions Integrated](#open-source-contributions-integrated)
2925

3026
## :white_check_mark: New Features
31-
- Enabled Microsoft Visual Studio* 2022 and Python 3.9 support.
27+
- 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.
28+
- 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.
29+
- Added support for Windows* Server 2022 and Python 3.10.
3230

3331
## :rotating_light: Known Limitations
3432
- 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.
4139
- 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).
4240

4341
## :hammer: Fixed Issues
44-
- Reworked synchronization mechanism to reduce contention when multiple task_arena's are used concurrently.
45-
- Fixed possible correctness issue in queuing_rw_mutex on non-Intel platforms.
46-
- Fixed GCC* 11 warnings.
47-
- Fixed sporadic memory corruption.
42+
- Memory allocator crash on a system with an incomplete /proc/meminfo (GitHub* [#584](https://github.com/oneapi-src/oneTBB/issues/584)).
43+
- Incorrect blocking of task stealing (GitHub* #[478](https://github.com/oneapi-src/oneTBB/issues/478)).
44+
- Hang due to incorrect decrement of a limiter_node (GitHub* [#634](https://github.com/oneapi-src/oneTBB/issues/634)).
45+
- Memory corruption in some rare cases when passing big messages in a flow graph (GitHub* [#639](https://github.com/oneapi-src/oneTBB/issues/639)).
46+
- 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)).
47+
- Crash when obtaining a range from empty ordered and unordered containers (GitHub* [#641](https://github.com/oneapi-src/oneTBB/issues/641)).
48+
- 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)).
49+
50+
## :octocat: Open-source Contributions Integrated
51+
- Improved aligned memory allocation. Contributed by Andrey Semashev (https://github.com/oneapi-src/oneTBB/pull/671).
52+
- 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).
53+
- Fixed incorrect definition of the assignment operator in containers. Contributed by Andrey Semashev (https://github.com/oneapi-src/oneTBB/issues/372).

‎doc/GSG/Images/how-oneTBB-works.png

52.2 KB
Loading

‎doc/GSG/examples.rst

+45
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
.. _examples:
2+
3+
oneTBB Samples
4+
==============
5+
6+
Refer to the following examples to see how |short_name| works.
7+
8+
* **Containers**
9+
10+
* `concurrent_hash_map <https://github.com/oneapi-src/oneTBB/tree/master/examples/concurrent_hash_map>`_
11+
* `concurrent_priority_queue <https://github.com/oneapi-src/oneTBB/tree/master/examples/concurrent_priority_queue>`_
12+
13+
* `Flow Graph <https://github.com/oneapi-src/oneTBB/tree/master/examples/graph>`_
14+
* `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>`_
15+
* `Cholesky Factorization algorithm <https://github.com/oneapi-src/oneTBB/tree/master/examples/graph/cholesky>`_
16+
* `An implementation of dining philosophers in graph using the reserving join_node <https://github.com/oneapi-src/oneTBB/tree/master/examples/graph/dining_philosophers>`_
17+
* `A parallel implementation of bzip2 block-sorting file compressor <https://github.com/oneapi-src/oneTBB/tree/master/examples/graph/fgbzip2>`_
18+
* `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>`_
19+
* `An example of a Kohonen Self-Organizing Map using cancellation <https://github.com/oneapi-src/oneTBB/tree/master/examples/graph/som>`_
20+
* `Split computational kernel for execution between CPU and GPU <https://github.com/oneapi-src/oneAPI-samples/tree/master/Libraries/oneTBB/tbb-async-sycl>`_
21+
22+
* **Algorithms**
23+
24+
* `parallel_for <https://github.com/oneapi-src/oneTBB/tree/master/examples/parallel_for>`_
25+
* `Game of life overlay <https://github.com/oneapi-src/oneTBB/tree/master/examples/parallel_for/game_of_life>`_
26+
* `Polygon overlay <https://github.com/oneapi-src/oneTBB/tree/master/examples/parallel_for/polygon_overlay>`_
27+
* `Parallel seismic wave simulation <https://github.com/oneapi-src/oneTBB/tree/master/examples/parallel_for/seismic>`_
28+
* `Parallel 2-D raytracer/renderer <https://github.com/oneapi-src/oneTBB/tree/master/examples/parallel_for/tachyon>`_
29+
* `Find largest matching substrings <https://github.com/oneapi-src/oneTBB/tree/master/examples/getting_started>`_
30+
* `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>`_
31+
* `parallel_for_each <https://github.com/oneapi-src/oneTBB/tree/master/examples/parallel_for_each>`_
32+
* `parallel_pipeline <https://github.com/oneapi-src/oneTBB/tree/master/examples/parallel_pipeline>`_
33+
* `parallel_reduce <https://github.com/oneapi-src/oneTBB/tree/master/examples/parallel_reduce>`_
34+
35+
* **Task Scheduler**
36+
37+
* `task_arena <https://github.com/oneapi-src/oneTBB/tree/master/examples/task_arena>`_
38+
* `task_group <https://github.com/oneapi-src/oneTBB/tree/master/examples/task_group>`_
39+
* `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>`_
40+
41+
* **Other**
42+
43+
* `Compute Fibonacci numbers in different ways <https://github.com/oneapi-src/oneTBB/tree/master/examples/test_all>`_
44+
45+

‎doc/GSG/installation.rst

+7
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
.. _installation:
2+
3+
Installation
4+
============
5+
6+
See the `installation instructions <https://github.com/oneapi-src/oneTBB/blob/master/INSTALL.md>`_
7+
that will help you to install |short_name| successfully.

‎doc/GSG/intro_gsg.rst

+18-8
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,23 @@
11
.. _Intro_gsg:
22

33

4-
|short_name| is a runtime-based parallel programming model for C++ code that uses threads.
5-
It enables you to simplify parallel programming by breaking
6-
computation into parallel running tasks.
7-
The library consists of a template-based runtime library to help you harness the latent performance
8-
of multi-core processors. Use |short_name| to write scalable applications that:
4+
|full_name| is a runtime-based parallel programming model for C++ code that uses threads.
5+
It consists of a template-based runtime library to help you harness the latent performance of multi-core processors.
96

7+
oneTBB enables you to simplify parallel programming by breaking computation into parallel running tasks. Within a single process,
8+
parallelism is carried out through threads, an operating system mechanism that allows the same or different sets of instructions
9+
to be executed simultaneously.
1010

11-
- Specify logical parallel structure instead of threads
12-
- Emphasize data parallel programming
13-
- Take advantage of concurrent collections and parallel algorithms
11+
Here you can see one of the possible executions of tasks by threads.
12+
13+
.. figure:: /GSG/Images/how-oneTBB-works.png
14+
:scale: 70%
15+
:align: center
16+
17+
Use oneTBB to write scalable applications that:
18+
19+
* Specify logical parallel structure instead of threads
20+
* Emphasize data-parallel programming
21+
* Take advantage of concurrent collections and parallel algorithms
22+
23+
oneTBB supports nested parallelism and load balancing. It means that you can use the library without being worried about oversubscribing a system.

‎doc/Makefile

+36
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
#===============================================================================
2+
# Copyright (C) 2022 Intel Corporation
3+
#
4+
# Licensed under the Apache License, Version 2.0 (the "License");
5+
# you may not use this file except in compliance with the License.
6+
# You may obtain a copy of the License at
7+
#
8+
# http://www.apache.org/licenses/LICENSE-2.0
9+
#
10+
# Unless required by applicable law or agreed to in writing, software
11+
# distributed under the License is distributed on an "AS IS" BASIS,
12+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
# See the License for the specific language governing permissions and
14+
# limitations under the License.
15+
#===============================================================================
16+
17+
# Minimal makefile for Sphinx documentation
18+
#
19+
20+
# You can set these variables from the command line, and also
21+
# from the environment for the first two.
22+
SPHINXOPTS ?=
23+
SPHINXBUILD ?= sphinx-build
24+
SOURCEDIR = doc
25+
BUILDDIR = build
26+
27+
# Put it first so that "make" without argument is like "make help".
28+
help:
29+
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
30+
31+
.PHONY: help Makefile
32+
33+
# Catch-all target: route all unknown targets to Sphinx using the new
34+
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
35+
%: Makefile
36+
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

‎doc/README.md

+34
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
# How to build oneTBB documentation
2+
3+
Our documentation is written in restructured text markup (.rst) and built using [Sphinx](http://www.sphinx-doc.org/en/master/).
4+
5+
This document explains how to build oneTBB documentation locally.
6+
7+
## Prerequisites
8+
- Python 3.7.0 or higher
9+
- Sphinx
10+
11+
## Build documentation
12+
13+
Do the following to generate HTML output of the documentation:
14+
15+
1. Clone oneTBB repository:
16+
17+
```
18+
git clone https://github.com/oneapi-src/oneTBB.git
19+
```
20+
21+
2. Go to the `doc` folder:
22+
23+
```
24+
cd oneTBB/doc
25+
```
26+
27+
3. Run in the command line:
28+
29+
```
30+
make html
31+
```
32+
33+
34+
That's it! Your built documentation is located in the ``build/html`` folder.

‎doc/conf.py

+19-13
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,7 @@
2929
project = u'Intel® oneAPI Threading Building Blocks (oneTBB)'
3030
else:
3131
project = u'oneTBB'
32-
copyright = u'2021, Intel Corporation'
32+
copyright = u'2022, Intel Corporation'
3333
author = u'Intel'
3434

3535
# The short X.Y version
@@ -60,7 +60,7 @@
6060
]
6161

6262
# Add any paths that contain templates here, relative to this directory.
63-
templates_path = ['_templates']
63+
templates_path = ['main/_templates']
6464

6565
# The suffix(es) of source filenames.
6666
# You can specify multiple suffix as a list of string:
@@ -120,21 +120,26 @@
120120
# further. For a list of options available for each theme, see the
121121
# documentation.
122122
#
123-
if BUILD_TYPE == 'oneapi' or BUILD_TYPE == 'dita':
124-
html_theme = 'sphinx_rtd_theme'
123+
124+
html_theme = 'sphinx_book_theme'
125+
126+
if BUILD_TYPE == 'dita':
127+
html_theme_options = {
128+
'repository_url': 'https://github.com/oneapi-src/oneTBB',
129+
'path_to_docs': 'doc',
130+
'repository_branch': 'master'
131+
}
125132
else:
126-
html_theme = 'sphinx_book_theme'
127133
html_theme_options = {
128-
'repository_url': 'https://github.com/oneapi-src/oneTBB',
129-
'path_to_docs': 'doc/main',
130-
'use_issues_button': True,
131-
'use_edit_page_button': True,
132-
'repository_branch': 'master',
133-
'extra_footer': '<p align="right"><a href="https://www.intel.com/content/www/us/en/privacy/intel-cookie-notice.html">Cookies</a></p>'
134+
'repository_url': 'https://github.com/oneapi-src/oneTBB',
135+
'path_to_docs': 'doc/main',
136+
'use_issues_button': True,
137+
'use_edit_page_button': True,
138+
'repository_branch': 'master',
139+
'extra_footer': '<p align="right"><a href="https://www.intel.com/content/www/us/en/privacy/intel-cookie-notice.html">Cookies</a></p>'
134140
}
135141

136142

137-
138143
# Add any paths that contain custom static files (such as style sheets) here,
139144
# relative to this directory. They are copied after the builtin static files,
140145
# so a file named "default.css" will overwrite the builtin "default.css".
@@ -148,8 +153,9 @@
148153
}
149154
else:
150155
html_js_files = ['custom.js']
151-
html_logo = '_static/oneAPI-rgb-rev-100.png'
156+
152157

158+
html_logo = '_static/oneAPI-rgb-rev-100.png'
153159
html_favicon = '_static/favicons.png'
154160

155161
# Custom sidebar templates, must be a dictionary that maps document names

‎doc/index/index_intro.rst

+1
Original file line numberDiff line numberDiff line change
@@ -2,3 +2,4 @@
22

33
This document contains information about |short_name|.
44
It is a flexible performance library that let you break computation into parallel running tasks.
5+

‎doc/index/toctree.rst

+28-8
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,33 @@
11
.. _toctree:
22

33
.. toctree::
4+
:caption: About
5+
:maxdepth: 1
6+
7+
/main/intro/help_support
8+
/main/intro/notation
9+
/main/intro/intro_os
10+
/main/intro/Benefits
11+
12+
13+
.. toctree::
14+
:caption: Get Started
415
:maxdepth: 2
516

6-
main/intro/help_support
7-
main/intro/notation
8-
main/intro/intro_os
9-
main/intro/Benefits
10-
GSG/get_started
11-
main/tbb_userguide/title
12-
main/reference/reference
13-
main/intro/notices_and_disclaimers
17+
/GSG/get_started
18+
/GSG/installation
19+
/GSG/examples
20+
21+
22+
.. toctree::
23+
:maxdepth: 3
24+
:caption: Developer Guide
25+
26+
/main/tbb_userguide/title
27+
28+
29+
.. toctree::
30+
:maxdepth: 3
31+
:caption: Developer Reference
32+
33+
/main/reference/reference

‎doc/main/_templates/layout.html

+6-4
Original file line numberDiff line numberDiff line change
@@ -6,10 +6,12 @@
66
var wapLocalCode = 'us-en'; // Dynamically set per localized site, see mapping table for values
77
var wapSection = "oneapi-tbb"; // WAP team will give you a unique section for your site
88
// Load TMS
9-
(function () {
10-
var url = 'https://www.intel.com/content/dam/www/global/wap/tms-loader.js'; // WAP file URL
11-
var po = document.createElement('script'); po.type = 'text/javascript'; po.async = true; po.src = url;
12-
var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(po, s);
9+
if(document.location.href.contains("oneapi-src.github.io")){
10+
(function () {
11+
var url = 'https://www.intel.com/content/dam/www/global/wap/tms-loader.js'; // WAP file URL
12+
var po = document.createElement('script'); po.type = 'text/javascript'; po.async = true; po.src = url;
13+
var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(po, s);
1314
})();
15+
}
1416
</script>
1517
{% endblock %}

0 commit comments

Comments
 (0)