Skip to content

Commit 2b39fda

Browse files
kboyarinovaepanchivossmjp
authored
Add documentation for blocked_nd_range CTAD (#1641)
Co-authored-by: Alexandra <[email protected]> Co-authored-by: Mike Voss <[email protected]>
1 parent e02bdf2 commit 2b39fda

File tree

3 files changed

+211
-0
lines changed

3 files changed

+211
-0
lines changed

‎doc/main/reference/blocked_nd_range_ctad.rst

+149
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,149 @@
1+
.. _blocked_nd_range_ctad:
2+
3+
Deduction Guides for ``blocked_nd_range``
4+
=========================================
5+
6+
.. note::
7+
To enable this feature, define the ``TBB_PREVIEW_BLOCKED_ND_RANGE_DEDUCTION_GUIDES`` macro to 1.
8+
9+
.. contents::
10+
:local:
11+
:depth: 1
12+
13+
Description
14+
***********
15+
16+
The ``blocked_nd_range`` class represents a recursively divisible N-dimensional half-open interval for the oneTBB
17+
parallel algorithms. This feature extends ``blocked_nd_range`` to support Class Template Argument
18+
Deduction (starting from C++17). With that, you do not need to specify template arguments explicitly
19+
while creating a ``blocked_nd_range`` object if they can be inferred from the constructor arguments:
20+
21+
.. literalinclude:: ./examples/blocked_nd_range_ctad_example.cpp
22+
:language: c++
23+
:start-after: /*begin_blocked_nd_range_ctad_example_1*/
24+
:end-before: /*end_blocked_nd_range_ctad_example_1*/
25+
26+
.. note::
27+
For more detailed description of the implementation of this feature or to leave comments or feedback on the API, please
28+
refer to the [corresponding RFC](https://github.com/uxlfoundation/oneTBB/tree/master/rfcs/experimental/blocked_nd_range_ctad).
29+
30+
API
31+
***
32+
33+
Header
34+
------
35+
36+
.. code:: cpp
37+
38+
#include <oneapi/tbb/blocked_nd_range.h>
39+
40+
Synopsis
41+
--------
42+
43+
.. code:: cpp
44+
45+
namespace oneapi {
46+
namespace tbb {
47+
48+
template <typename Value, unsigned int N>
49+
class blocked_nd_range {
50+
public:
51+
// Member types and constructors defined as part of oneTBB specification
52+
using value_type = Value;
53+
using dim_range_type = blocked_range<value_type>;
54+
using size_type = typename dim_range_type::size_type;
55+
56+
blocked_nd_range(const dim_range_type& dim0, /*exactly N arguments of type const dim_range_type&*/); // [1]
57+
blocked_nd_range(const value_type (&dim_size)[N], size_type grainsize = 1); // [2]
58+
blocked_nd_range(blocked_nd_range& r, split); // [3]
59+
blocked_nd_range(blocked_nd_range& r, proportional_split); // [4]
60+
}; // class blocked_nd_range
61+
62+
// Explicit deduction guides
63+
template <typename Value, typename... Values>
64+
blocked_nd_range(blocked_range<Value>, blocked_range<Values>...)
65+
-> blocked_nd_range<Value, 1 + sizeof...(Values)>;
66+
67+
template <typename Value, unsigned int... Ns>
68+
blocked_nd_range(const Value (&...)[Ns])
69+
-> blocked_nd_range<Value, sizeof...(Ns)>;
70+
71+
template <typename Value, unsigned int N>
72+
blocked_nd_range(const Value (&)[N], typename blocked_nd_range<Value, N>::size_type = 1)
73+
-> blocked_nd_range<Value, N>;
74+
75+
template <typename Value, unsigned int N>
76+
blocked_nd_range(blocked_nd_range<Value, N>, split)
77+
-> blocked_nd_range<Value, N>;
78+
79+
template <typename Value, unsigned int N>
80+
blocked_nd_range(blocked_nd_range<Value, N>, proportional_split)
81+
-> blocked_nd_range<Value, N>;
82+
} // namespace tbb
83+
} // namespace oneapi
84+
85+
Deduction Guides
86+
----------------
87+
88+
The copy and move constructors of ``blocked_nd_range`` provide implicitly generated deduction guides.
89+
In addition, the following explicit deduction guides are provided:
90+
91+
.. code:: cpp
92+
93+
template <typename Value, typename... Values>
94+
blocked_nd_range(blocked_range<Value>, blocked_range<Values>...)
95+
-> blocked_nd_range<Value, 1 + sizeof...(Values)>;
96+
97+
**Effects**: Enables deduction when a set of ``blocked_range`` objects is passed to the ``blocked_nd_range`` constructor ``[1]``.
98+
99+
**Constraints**: Participates in overload resolution only if all of the types in `Values` are same as `Value`.
100+
101+
.. code:: cpp
102+
103+
template <typename Value, unsigned int... Ns>
104+
blocked_nd_range(const Value (&...)[Ns])
105+
-> blocked_nd_range<Value, sizeof...(Ns)>;
106+
107+
**Effects**: Enables deduction when a set of ``blocked_range`` objects is provided as braced-init-lists
108+
to the ``blocked_nd_range`` constructor ``[1]``.
109+
110+
**Constraints**: Participates in overload resolution only if ``sizeof...(Ns) >= 2``, and each integer ``Ni`` in ``Ns``
111+
is either ``2`` or ``3``, corresponding to ``blocked_range`` constructors with 2 and 3 arguments, respectively.
112+
113+
.. note::
114+
The guide allows a deduction only from braced-init-lists containing objects of the same type.
115+
For ranges with non-integral ``value_type``, setting an explicit grainsize argument
116+
is not supported by the deduction guides and requires specifying explicit template arguments.
117+
118+
.. code:: cpp
119+
120+
template <typename Value, unsigned int N>
121+
blocked_nd_range(const Value (&)[N], typename blocked_nd_range<Value, N>::size_type = 1)
122+
-> blocked_nd_range<Value, N>;
123+
124+
**Effects**: Allows deduction from a single C array object indicating a set of dimension sizes to constructor
125+
``2`` of ``blocked_nd_range``.
126+
127+
.. code:: cpp
128+
129+
template <typename Value, unsigned int N>
130+
blocked_nd_range(blocked_nd_range<Value, N>, split)
131+
-> blocked_nd_range<Value, N>;
132+
133+
**Effects**: Allows deduction while using the splitting constructor ``3`` of ``blocked_nd_range``.
134+
135+
.. code:: cpp
136+
137+
template <typename Value, unsigned int N>
138+
blocked_nd_range(blocked_nd_range<Value, N>, proportional_split)
139+
-> blocked_nd_range<Value, N>;
140+
141+
**Effects**: Allows deduction while using the proportional splitting constructor ``4`` of ``blocked_nd_range``.
142+
143+
Example
144+
-------
145+
146+
.. literalinclude:: ./examples/blocked_nd_range_ctad_example.cpp
147+
:language: c++
148+
:start-after: /*begin_blocked_nd_range_ctad_example_2*/
149+
:end-before: /*end_blocked_nd_range_ctad_example_2*/

‎doc/main/reference/examples/blocked_nd_range_ctad_example.cpp

+61
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
/*
2+
Copyright (c) 2025 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+
#if __cplusplus >= 201703L
18+
19+
#define TBB_PREVIEW_BLOCKED_ND_RANGE_DEDUCTION_GUIDES 1
20+
#include <oneapi/tbb/blocked_nd_range.h>
21+
22+
int main() {
23+
{
24+
/*begin_blocked_nd_range_ctad_example_1*/
25+
oneapi::tbb::blocked_range<int> range1(0, 100);
26+
oneapi::tbb::blocked_range<int> range2(0, 200);
27+
oneapi::tbb::blocked_range<int> range3(0, 300);
28+
29+
// Since 3 unidimensional ranges of type int are provided, the type of nd_range
30+
// can be deduced as oneapi::tbb::blocked_nd_range<int, 3>
31+
oneapi::tbb::blocked_nd_range nd_range(range1, range2, range3);
32+
/*end_blocked_nd_range_ctad_example_1*/
33+
}
34+
/*begin_blocked_nd_range_ctad_example_2*/
35+
{
36+
oneapi::tbb::blocked_range<int> range1(0, 100);
37+
oneapi::tbb::blocked_range<int> range2(0, 200);
38+
39+
// Deduced as blocked_nd_range<int, 2>
40+
oneapi::tbb::blocked_nd_range nd_range(range1, range2);
41+
}
42+
{
43+
// Deduced as blocked_nd_range<int, 2>
44+
oneapi::tbb::blocked_nd_range nd_range({0, 100}, {0, 200, 5});
45+
}
46+
{
47+
int endings[3] = {100, 200, 300};
48+
49+
// Deduced as blocked_nd_range<int, 3>
50+
oneapi::tbb::blocked_nd_range nd_range1(endings);
51+
52+
// Deduced as blocked_nd_range<int, 3>
53+
oneapi::tbb::blocked_nd_range nd_range2({100, 200, 300}, /*grainsize = */10);
54+
}
55+
/*end_blocked_nd_range_ctad_example_2*/
56+
}
57+
58+
#else
59+
// Skip
60+
int main() {}
61+
#endif

‎doc/main/reference/reference.rst

+1
Original file line numberDiff line numberDiff line change
@@ -52,3 +52,4 @@ The key properties of a preview feature are:
5252
custom_mutex_chmap
5353
try_put_and_wait
5454
parallel_phase_for_task_arena
55+
blocked_nd_range_ctad

0 commit comments

Comments
 (0)