From 3df08fe234f23e732a122809b40eb129ae22733f Mon Sep 17 00:00:00 2001 From: Olga Malysheva Date: Fri, 17 Dec 2021 16:40:54 +0300 Subject: [PATCH] Update documentation for 2021.5 release. (#690) Signed-off-by: Olga Malysheva --- doc/GSG/_static/custom.js | 37 +++++++++ doc/GSG/_static/favicons.png | Bin 0 -> 467 bytes doc/GSG/_static/oneAPI-rgb-rev-100.png | Bin 0 -> 7414 bytes doc/GSG/_static/theme_overrides.css | 13 ++++ doc/GSG/conf.py | 43 ++++++++++- doc/main/conf.py | 3 +- doc/main/index.rst | 22 ++---- .../parallel_sort_ranges_extension.rst | 72 ++++++++++++++++++ doc/main/reference/reference.rst | 1 + doc/main/reference/task_group_extensions.rst | 33 +++++--- 10 files changed, 195 insertions(+), 29 deletions(-) create mode 100644 doc/GSG/_static/custom.js create mode 100644 doc/GSG/_static/favicons.png create mode 100644 doc/GSG/_static/oneAPI-rgb-rev-100.png create mode 100644 doc/GSG/_static/theme_overrides.css create mode 100644 doc/main/reference/parallel_sort_ranges_extension.rst 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 0000000000000000000000000000000000000000..f450376b19e2d945e6d2da8b329de8aed320a9b7 GIT binary patch literal 467 zcmeAS@N?(olHy`uVBq!ia0vp^0wB!63?wyl`GbKJbFq_W2nPqp?T7vkfZQzsJ|V8| z1wPZ8J^^{vNsoafCh*ie2o%(1S)bwZ*nr{i!pV<{eBW$c`~#v=hGA`t*65p27hI++iAAt!F9FH-3in5x7jA&dYmBX!*k>8p9}maQ@6zPbDmk8 z>2hFgpElF;@Hqk%_dazSu3wYHs?8U_V)m|`)BA<~sXKg?ZBSKAG^&4*SVxwbwKPp`itHqoIXIqM_Y9QQ`m4(ELQu(Dq)Tp~-$mL!)`~<)@+i z(*e$F9StDb<9}8m{9F1Hga1a;+y@Qq8OMJNJ+M^C|B1x))dH#EZlW_$J!eCYZ+fB_ zwzPoC;J~HByr9q4CfP^t+z#R6GJX(6$&yMjuu*18L<;E(97j?{0~gYN{vFkaZzerG zs63GH!g4dq`u_blmhgByVj5>kHBx2~UOhZJ0G1}67IB3($eH<~wd29QAdOv&mM!1u zDt||Qr~*E>v>H4w1#?3-jTy-&Y?hQM{IMmRNuc4e&Ds5-_=RplqtVH?Q1E%X$+gug z`E5tR{T0apb35@Xz6n4^giImbAUfh=?GCf@+pJ6BgO!ZvxrhQLU$DE6w^`?XHC2qX z#&;S1Nf^Yqs3{=3X|h4a8zO(RGEo_k9dd-gr~^m?r15AmYybyXCqCPsaKUCPE_Dx9 zao-t>i`(Tgj1_9R?6drYCj~8>CR=)5zo}MT6}!btlHFNe{cf=f=IO!{AxK2WrC><8 zlk{z3Af77_u*v9u>Eu`8^jr@)+jv;#3TaL;uv^YKC}&q<8}OjjI}7&i*=(*a*bKLf zzzZbBi^%Sbt{JB{aGR8PmD3ZSiwbblHt+8PsE!v=Rz#{nWnV+QQoQd)zWUKDe>k;% zRb&&kS6i|F0|#tdh9+KCB1Ux++@@5;yUDH|Ao16Qkd4y_@$B%kOi8`rp*bd`ORyvH zP`mOkGWN4irb^t~<9jT6%->b~9?z2g)E!7yMDN{vA9|2EwG_Jn#_=LbDe+5tObpz_ zDp|j7{$kfI0F;JSe5LoO$U_)dn-q5kgAuCnr+9pPQAX%h#CN2DhxXd%r~oX=1AyPc z&yqbvq2^Twz9);_a*e52+Rkaxk>-Z7bw4db*1`-VZAh?T?4N}@(<-8viKm|l+C_4k zwP4@kUh}5kU6$UKTkfjq@Z@YosBX zfQDqN4n&z-7dug`6L(R8UQ#sjEja`^AUrD3s85_!G4R~O&gZQVt{?0cc7(oj@bz2^ z9t!VW&wRd;Ae0H2)VWJB3m{o=tHSn)orCo^%m!Iw&gD?;Gnq23*PXHE=5u8|XLH-R zpnbIecu5P=B$p5x>Ie%@2cor!FBB zfFc~(7E2o{rPkzP$oCRVNUtLRdtW5a@vXyd_Ke0D1Zhsahwzr?XRC<_mFBF{CGtbK zMh`wubV{iC{7{qONj&f!8pQ#}qtCvg25VN&smQGU9?{In@8E296cuL{tryrkTPf!v z${#4a5&J+&2?pl?tbWWaR}GHR`>!C=eHn{*OZGBRy<%UF@dh#JYbg!*V-A=IU9`*I zG=gZ=u+~BLG1%v!+>ae2tW#NPAS+ibk91N9#SE&))ZLM72Co$Lg0+nW2o9iwsOHS< zyJwo)_wk%r^FuL`!Y>l1{$@6X^35+z%^DamiyWP_F# zyTR*wJ-&NOgC>t{7KW8P%$*0G(o2IHdbn>kyav83+rd>VYa|pL5_wnIGM*2A*u&`j z603D{)2#nDgn#5L>Uxej-D9*IXk3*p{_7%*@9%2ORY)PBhNrWtKHa!6G(`Wi+kUE* zPy5ATq)B;(uZvvW;mxlP!7l{QH!nmRq9&N>_3keb%C{T|W=jbnSr(j@U|Qf^nbC6= z==i|$Q6RF)nYLYy{Y`0clTN{M`-p7FB7J+Yb4Ap23B-ogER(<+k!Er+*fKVnuIKV6 zo~Susm+;1P!CBDSUdr)Cut)Rc+Who<_ZT%DSHk~pFMj8xuEH}vsY7e6v>{YxLKfG< z>QZqU-0h>TNb8v0tHHTLc(9tw%rNw%T06w9#}~*ZTra4IK-j~B`n&alXa53JW2DbW zmi2soSs-s2Z@Yw`=>#UVwi_nR#fo`!b$ZN*f6`R|pO^KBGOr0ex?aP6x@^V0j7^V2 z@tr!yO&Q>WLiYNnVyWF;+2pWd8Ve?MBNrXJMFJq1N%yGecVO6**4_lItp>SkDHG6L z7wh#46*U8uwji65CfOdn^1;tt7>3$Br1k?_iSf%chpj<~D;5?$Tg0C-LSogk7vc1p zAC=qND-7~1jtBieSVrxxcn}eByFwax#|Y$D&Ia{xGk&C63+}{~MDLX1!>IWeC5+|L zIE|l+Z$z)i$;U4mWHv-tS2`(21wzG@tD~k8C)$B^jZP4=zRljrbzYIYOqhJji*v4o z@=BH*i)ZDLGyc3~>Kscs(T=mlHJSsgk zn@oEPgmnPQ<)gurCu|#XsuojxjKe)X#Gd~$69H9~-6h*-FZYOWFnDd<3>Er64+7j2 zsamKsxD5C?GgL-DwOJC+R;PkPlv%v0bl*`%T~QUhE{!*(FU3&da|p}6&Fp51D`~b$ zmF_mp)}@RN)% zsE68#kGM1DIa+~~c-iSM8anYx?^2CiWtA+h`M5m8j=~8H>;*jbT*eJ9mz_c^ppr zaPakrE6WrR;%3s;3YM_dE(7nv#%;%k-~$wajm>`hBxi#42pJLgOFzM>U$o48G$Tt5IRsBHG(WajhmFlgOL1p0p0N)w%l6gZ#C*R1S1Fn{ zTF5lX{U%u&Cg%pn$ZDO(=@vjQQR+NDZU!TpP7DT)Z0#=bzWg(D3|aLKSti&~bzeMZ zWPiNnQ1p>+2x(}mYQJ@7Tq!%mYOdBSp&V)~svT3Age=pd z>&%y2htB|g0a2|tmH*sMRn$YUoN7`1ea8#lcaui5y=3o*D-$QwUr9vo>2hZ3w;x=4 zf|&WFeVgTcJBG?m$SnQ*2}gmiBO+r7n8E0_Jv>BPGS7>bSonrabIwI{4g)}0BUzRi zX_Qy^s$2|dw;q~Du*!pnd{ez3=d0avYbMi*?3ETi#})hXCUr0v_*S+kw3_VlU3kaz zC%PkI#N1OQ95Y78p>+n$V+Pt3HC4qy?F$bV*= z3|&X4hra6VjDd~@PKa&Qj)#q9o7oI>eZ*omXT-1e3mycEWq z{`kU)^p4JDiCX>dNgX@5ifx+0m2p@dbzEG8RhE)mzNPw`N&Cx35u(gb$-I;*3~c^I2~XAM}%z!r7Gzo_ar5 zuMD)q9Fyw z6nK~O1x6Ho80*!GdSey^GEM&;M%a8-wMRn z!paYl!_sp%WE|VyvQ3>|eJITX$_%cyh~JIq$9lzWrbf$y?cJo7hT0Oc3TjL_7UjY9d-{(t)p|yw#_>)-PNG6 zZ0pd!m7X?Ph~90;M{%5=0Hl=z93E01rs<|0<8mEV4e7|-t@mHK$Nl8BI(d1AeJ(Aj z7Sf_m`+3&-KJM{lz2e)m-ylFj)-o?c!w)Aje{R{!h}B!A+u!Fav(wavpylV^nlAql zX0aT6r(If`fCDLTL}bVjV)f!TF+hst044CodM=IBcUxi*IBlt)Nt`3t9vSU3#WXi* zogk^8BN+V2oHK_~i0+4q1kGh_qu1>>3g>~GWpn;$j^%bgou^b+8y2D_wm42>mv-7C zJB@e@G5ia6?r2?@Ld`o)z2k9J_=4<+qI0_m!0?R*ETYI+zW} z=@L&mVqtm@L${;zY`D!EOQNO^KojHW_rSCj2E!XG-YqYB$lt7`RSC+OP8C$!PbdTN z7XldW)t=iFTqk~13kLlJ?O=KGQaM3)rGMW}`QbVRO`tDnipEnaGoqoYECs8x+{B`LXvly zt>O7@`UdKxA@TY>hivdUO;)wvM<&F-@}pAfCGK+YmWGe5bIWpIrR(-JXpvalfckgJL^(=F(B`}kd1g0p-XbMDWitPAeCKlA=) zvIW-lirF?n<-KdNF&$gfLUb!k_&jp>aDRVJ`bz38-_q-s8p(d^Yu(L~FwyRYrsoMb zPowtq2j#w@7~*E)HZ}7N(;g|EzUyp7x84aHjcWNByG2M0!m&A1bN_=IRnTH`hlNeN zAw#ASQoCd(hK6`aC+4~Icj-Q-A^zMNbOA$wVX`RKpmGKK6{#;*qydQvKlWYD#6TzuVwXmYdb&d>BfsD9j$#IJ5flOsp0n;M+xu zEalD-B^@l~H8Q){B2Lf6G7C}&7uy@EYf-}}Er4i*Y#;DFa-Nj3<5Q2&a;syvfGTCU z?Gz|eMrJ=6`KiVV{_HwY7%t7qz?Y`?S+IRNtUGeeM94c`#NRf)8Ng7BQ7jkc#I5i< zDmFg1Uo#0J1ZtYm_AJVtLOh?k>{U{-Hl7}t&EHGponIhy>9r$!AZjV zK3?B3pl<}IX)M+?ML&Oe{GI^%l1<_n8#Z`z%?XnrD)v|dV`_*qs{!>PoYYH2O3kKv zTYj39@pBmXeSBeXDOYAESx+Or6|9c9J?#Zwa!QXc>va`-#UHnFKY=qh!OTSmPJ;-f z;raf4F$$mW;B53DnfQn!dMSlHD63km_ZL=Vjm~0{lu@BPzV4BpZG#yh!acHmvgn#f z=NfKExi$~UfB-D$COl1CeM;YgHW!AR8E2g34IM{oU5)qghYqodyOne+SmV4!DN)%g zdpZ{^-$scaYbIJs&rfozPEg})|ET{+mREZ4lBFhNG)P^ig$?xQJs!pnSJA9I+(+pD zxw@Zfk|IR#cQZ&-mT|-bHx+CfRxcd45B&WW#>++}El(zq(0l{yOM)YH6m?uBX)1?9 z4XyUy)2|uAaV3oRUxQD?0ek2ikH=#!!l?#u;d+yO0f`EL0SVn*mD#_`qhOI6-u52C z$r9QIB_L;0R^(oAluU08re83t^8z5a(B3KW*yFt!h0ikEL@vl1nEG~ zuldQJ3y(?pj&@IzlVv}`tbp3&!Vf zuC`eiwjBJ$-&9c0ew?N<0aK7$F`y*w>QAcZ`s#4y6)%wQc#?TPy#2yCh5AfL9B z?yHmqNDETm(%)Lyr1s8cEwHd15cnb#)s@s`rncD;w)YM%&>ntji*balhy(kqVeO4| zCH5vR7K;!=sZVQrw97Jl_8eWbuf~_6e%~Vu!%Xk^U;DOOxMeKGh*lr62N@hsigFOc zKfu0;h`6t@mfD)$ce-;p36Ev$>;jRddI`2d6Jp)N-v3l1lkq9|dC2aa8hfShJ>Cv< zSP9Jw^Ho#CKsNFH9tsqV5+; zGywLPU3c#p_U{4$hgi4^G+~^$?<<7k&4}XGqabG0u=Xqbx4cW|pI+|K(7aR!0TF!c zKNaae#@-2&;qT9LkOj?SxZU0;W}PoybF#5Bu{Q*DH-+p`hsO$1r+N_9gas)p05=`k zjmmA8n>})#K@yT)|M`H^<3g# z)`iO_Xrfu6!;-G7ctBr>o^gNtMCe%Q`Pb$?gt;|Y`j;{zCdK)qSGlF+izsQR|I9hr ztE?+v{`2+77NUiw7soX7%dHfx9uWX^6va9Pjg3v`KyR|Mj-NnhiiU#W>|=A>g4>TS z?5_NKNpO1&3Udpqlt!I1cP?WkgPgQ~0d)$=lr5fAUE>LZZk?K7@@p2vFYBQl^7EgJ3yfe7by z-T`tH_Urir3{$jE#-2YIM-kFtRUUoW^$#v)_4u^6PP=jo~Md#`vvG#09gzTTmJ40^~-eh4pl}1g!bK_ zCw~3qX6)`%K-_#5rZ4&Flr3gww%3kU367P~V}RF6&yPNmf=+#1bb(vDx{bcM2e3|Q z(IZyX%G5CFHNET8A0U^n+Dl&tJ6}gxdvC`lKob)Y6A=;-6%vyHi;2ogO2~?f3yDa| liiiy6IiLKOz{AVI)hXzI3);F?^_~Q1T55X08kJY?{|_}8aQy%P literal 0 HcmV?d00001 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 `