diff --git a/doc/GSG/_static/custom.js b/doc/GSG/_static/custom.js new file mode 100644 index 0000000000..a7d312de32 --- /dev/null +++ b/doc/GSG/_static/custom.js @@ -0,0 +1,37 @@ +window.MathJax = { + TeX: { + Macros: { + src: '\\operatorname{src}', + srclayer: '\\operatorname{src\\_layer}', + srciter: '\\operatorname{src\\_iter}', + srciterc: '\\operatorname{src\\_iter\\_c}', + weights: '\\operatorname{weights}', + weightslayer: '\\operatorname{weights\\_layer}', + weightsiter: '\\operatorname{weights\\_iter}', + weightspeephole: '\\operatorname{weights\\_peephole}', + weightsprojection: '\\operatorname{weights\\_projection}', + bias: '\\operatorname{bias}', + dst: '\\operatorname{dst}', + dstlayer: '\\operatorname{dst\\_layer}', + dstiter: '\\operatorname{dst\\_iter}', + dstiterc: '\\operatorname{dst\\_iter\\_c}', + diffsrc: '\\operatorname{diff\\_src}', + diffsrclayer: '\\operatorname{diff\\_src\\_layer}', + diffsrciter: '\\operatorname{diff\\_src\\_iter}', + diffsrciterc: '\\operatorname{diff\\_src\\_iter\\_c}', + diffweights: '\\operatorname{diff\\_weights}', + diffweightslayer: '\\operatorname{diff\\_weights\\_layer}', + diffweightsiter: '\\operatorname{diff\\_weights\\_iter}', + diffweightspeephole: '\\operatorname{diff\\_weights\\_peephole}', + diffweightsprojection: '\\operatorname{diff\\_weights\\_projection}', + diffbias: '\\operatorname{diff\\_bias}', + diffdst: '\\operatorname{diff\\_dst}', + diffdstlayer: '\\operatorname{diff\\_dst\\_layer}', + diffdstiter: '\\operatorname{diff\\_dst\\_iter}', + diffdstiterc: '\\operatorname{diff\\_dst\\_iter\\_c}', + diffgamma: '\\operatorname{diff\\_\\gamma}', + diffbeta: '\\operatorname{diff\\_\\beta}', + workspace: '\\operatorname{workspace}' + } + } +} \ No newline at end of file diff --git a/doc/GSG/_static/favicons.png b/doc/GSG/_static/favicons.png new file mode 100644 index 0000000000..f450376b19 Binary files /dev/null and b/doc/GSG/_static/favicons.png differ diff --git a/doc/GSG/_static/oneAPI-rgb-rev-100.png b/doc/GSG/_static/oneAPI-rgb-rev-100.png new file mode 100644 index 0000000000..58d2d5c54e Binary files /dev/null and b/doc/GSG/_static/oneAPI-rgb-rev-100.png differ diff --git a/doc/GSG/_static/theme_overrides.css b/doc/GSG/_static/theme_overrides.css new file mode 100644 index 0000000000..63ee6cc74c --- /dev/null +++ b/doc/GSG/_static/theme_overrides.css @@ -0,0 +1,13 @@ +/* override table width restrictions */ +@media screen and (min-width: 767px) { + + .wy-table-responsive table td { + /* !important prevents the common CSS stylesheets from overriding + this as on RTD they are loaded after this stylesheet */ + white-space: normal !important; + } + + .wy-table-responsive { + overflow: visible !important; + } +} diff --git a/doc/GSG/conf.py b/doc/GSG/conf.py index 0355ed4ec6..e45812d1a0 100644 --- a/doc/GSG/conf.py +++ b/doc/GSG/conf.py @@ -26,7 +26,10 @@ # -- Project information ----------------------------------------------------- -project = u'Intel® oneAPI Threading Building Blocks (oneTBB)' +if BUILD_TYPE == 'oneapi' or BUILD_TYPE == 'dita': + project = u'Intel® oneAPI Threading Building Blocks (oneTBB)' +else: + project = u'oneAPI Threading Building Blocks (oneTBB)' copyright = u'2021, Intel Corporation' author = u'Intel' @@ -90,7 +93,8 @@ highlight_language = 'cpp' -rst_prolog = """ +if BUILD_TYPE == 'oneapi' or BUILD_TYPE == 'dita': + rst_prolog = """ .. |full_name| replace:: Intel\ |reg|\ oneAPI Threading Building Blocks (oneTBB) .. |short_name| replace:: oneTBB .. |product| replace:: oneTBB @@ -99,6 +103,16 @@ .. |base_tk| replace:: Intel\ |reg|\ oneAPI Base Toolkit .. |dpcpp| replace:: Intel\ |reg|\ oneAPI DPC++/C++ Compiler """ +else: + rst_prolog = """ +.. |full_name| replace:: oneAPI Threading Building Blocks (oneTBB) +.. |short_name| replace:: oneTBB +.. |product| replace:: oneTBB +.. |reg| unicode:: U+000AE +.. |copy| unicode:: U+000A9 +.. |base_tk| replace:: Intel\ |reg|\ oneAPI Base Toolkit +.. |dpcpp| replace:: Intel\ |reg|\ oneAPI DPC++/C++ Compiler + """ # -- Options for HTML output ------------------------------------------------- @@ -110,13 +124,36 @@ # further. For a list of options available for each theme, see the # documentation. # -html_theme = 'sphinx_book_theme' +if BUILD_TYPE == 'oneapi' or BUILD_TYPE == 'dita': + html_theme = 'sphinx_rtd_theme' +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': '

Cookies

' + } # 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". html_static_path = ['_static'] +if BUILD_TYPE == 'oneapi' or BUILD_TYPE == 'dita': + html_context = { + 'css_files': [ + '_static/theme_overrides.css', # override wide tables in RTD theme + ], + } +else: + html_js_files = ['custom.js'] + 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/main/conf.py b/doc/main/conf.py index da8fe3248f..6c81f8ce03 100644 --- a/doc/main/conf.py +++ b/doc/main/conf.py @@ -149,7 +149,8 @@ else: html_js_files = ['custom.js'] html_logo = '_static/oneAPI-rgb-rev-100.png' - html_favicon = '_static/favicons.png' + +html_favicon = '_static/favicons.png' # Custom sidebar templates, must be a dictionary that maps document names # to template names. diff --git a/doc/main/index.rst b/doc/main/index.rst index afed90a2af..51982c9fb2 100644 --- a/doc/main/index.rst +++ b/doc/main/index.rst @@ -12,27 +12,17 @@ For a list of available documentation downloads by product version, see these pa * `Download Documentation for Intel Parallel Studio XE `_ * `Download Documentation for Intel System Studio `_ -The following are some important topics for the ``novice user``: - -**Get Started with oneAPI Threading Building Blocks (oneTBB)** - -`Get Started with oneTBB `_ gives you a brief explanation of what oneTBB is. - -**oneTBB Benefits** -:ref:`Benefits` describes how |short_name| differs from typical threading packages. - -**Package Contents** - -|short_name| includes dynamic library files and header files for Windows*, Linux*, and macOS* -operating systems as described in :ref:`Package_Contents`. +The following are some important topics for the ``novice user``: +* `Get Started with oneTBB `_ gives you a brief explanation of what oneTBB is. +* :ref:`Benefits` describes how |short_name| differs from typical threading packages. +* :ref:`Package_Contents` describes dynamic library files and header files for Windows*, Linux*, and macOS* operating systems used in |short_name|. -The following is important topic for the ``experienced user``: -**Migrating from Threading Building Blocks (TBB)** +The following is an important topic for the ``experienced user``: -Learn how to migrate from TBB to oneTBB with :ref:`Migration_Guide`. +:ref:`Migration_Guide` describes how to migrate from TBB to oneTBB. .. toctree:: diff --git a/doc/main/reference/parallel_sort_ranges_extension.rst b/doc/main/reference/parallel_sort_ranges_extension.rst new file mode 100644 index 0000000000..52f2283a17 --- /dev/null +++ b/doc/main/reference/parallel_sort_ranges_extension.rst @@ -0,0 +1,72 @@ +.. _parallel_sort_ranges_extension: + +parallel_sort ranges interface extension +======================================== + +.. contents:: + :local: + :depth: 1 + +Description +*********** + +|full_name| implementation extends the `oneapi::tbb::parallel_sort specification `_ +with overloads that takes the container by forwarding reference. + + +API +*** + +Header +------ + +.. code:: cpp + + #include + +Syntax +------ + +.. code:: cpp + + namespace oneapi { + namespace tbb { + + template + void parallel_sort( Container&& c ); + template + void parallel_sort( Container&& c, const Compare& comp ); + + } // namespace tbb + } // namespace oneapi + +Functions +--------- + +.. cpp:function:: template void parallel_sort( Container&& c ); + + Equivalent to ``parallel_sort( std::begin(c), std::end(c), comp )``, where `comp` uses `operator<` to determine relative orderings. + +.. cpp:function:: template void parallel_sort( Container&& c, const Compare& comp ); + + Equivalent to ``parallel_sort( std::begin(c), std::end(c), comp )``. + +Example +------- + +This interface may be used for sorting rvalue or constant views: + +.. code:: cpp + + #include + #include // requires C++20 + #include + + std::span get_span() { + static std::array arr = {3, 2, 1}; + return std::span(arr); + } + + int main() { + tbb::parallel_sort(get_span()); + } diff --git a/doc/main/reference/reference.rst b/doc/main/reference/reference.rst index d356b6025b..63b29ad76f 100644 --- a/doc/main/reference/reference.rst +++ b/doc/main/reference/reference.rst @@ -18,6 +18,7 @@ It also describes features that are not included in the oneTBB specification. info_namespace parallel_for_each_semantics + parallel_sort_ranges_extension Preview features **************** diff --git a/doc/main/reference/task_group_extensions.rst b/doc/main/reference/task_group_extensions.rst index 2ac0cf7137..ea4a7437ef 100644 --- a/doc/main/reference/task_group_extensions.rst +++ b/doc/main/reference/task_group_extensions.rst @@ -15,9 +15,9 @@ Description |full_name| implementation extends the `tbb::task_group specification `_ with the following members: - - Constructor that takes a custom ``tbb::task_group_context`` object as an argument. - - Methods to create and run deferred tasks with ``task_handle``. - - Requirements for a user-provided function object. + - constructor that takes a custom ``tbb::task_group_context`` object as an argument + - methods to create and run deferred tasks with ``task_handle`` + - requirements for a user-provided function object API @@ -46,8 +46,10 @@ Synopsis task_handle defer(F&& f); void run(task_handle&& h); + + task_group_status run_and_wait(task_handle&&); - //only F return type requirements have changed + //only the requirements for the return type of function F are changed template void run(F&& f); }; @@ -55,6 +57,8 @@ Synopsis } // namespace tbb } // namespace oneapi + + Member Functions ---------------- @@ -62,6 +66,7 @@ Member Functions Constructs an empty ``task_group``, which tasks are associated with the ``context``. + .. cpp:function:: template task_handle defer(F&& f) Creates a deferred task to compute ``f()`` and returns ``task_handle`` pointing to it. @@ -78,15 +83,24 @@ As an optimization hint, ``F`` might return a ``task_handle``, which task object **Returns:** ``task_handle`` object pointing to task to compute ``f()``. + .. cpp:function:: void run(task_handle&& h) - + Schedules the task object pointed by the ``h`` for execution. -.. note:: - The failure to satisfy the following conditions leads to undefined behavior: - * ``h`` is not empty. - * ``*this`` is the same ``task_group`` that ``h`` is created with. +.. caution:: If ``h`` is empty or ``*this`` is not the same ``task_group`` that ``h`` is created with, the behavior is undefined. + + +.. cpp:function:: task_group_status run_and_wait(task_handle&& h) + +Equivalent to ``{run(std::move(h)); return wait();}``. + +**Returns**: The status of ``task_group``. + +.. caution:: + If ``h`` is empty or ``*this`` is not the same ``task_group`` that ``h`` is created with, the behavior is undefined. + .. cpp:function:: template void run(F&& f) As an optimization hint, ``F`` might return a ``task_handle``, which task object can be executed next. @@ -99,4 +113,5 @@ As an optimization hint, ``F`` might return a ``task_handle``, which task object * `oneapi::tbb::task_group specification `_ * `oneapi::tbb::task_group_context specification `_ +* `oneapi::tbb::task_group_status specification `_ * :doc:`oneapi::tbb::task_handle class `