Skip to content

Commit aacf541

Browse files
[SYCL][Doc] Move properties to experimental namespace (#5410)
These changes move `properties` and property-related APIs into `sycl::ext::oneapi::experimental`. Signed-off-by: Steffen Larsen <steffen.larsen@intel.com>
1 parent af21e50 commit aacf541

File tree

1 file changed

+20
-23
lines changed

1 file changed

+20
-23
lines changed

sycl/doc/extensions/PropertyList/SYCL_EXT_ONEAPI_properties.asciidoc

Lines changed: 20 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ The `sycl::property_list` found in SYCL 2020 is used to store properties used in
88

99
Compile-time-constant properties are an important building block for classes and functions that have a need to propagate compile-time information for semantic and optimization purposes, while runtime properties continue to serve an important role in dynamic parameter specification.
1010

11-
This extension introduces `sycl::ext::oneapi::properties`, which is a replacement for `sycl::property_list` that supports the storage and manipulation of compile-time-constant properties in addition to runtime properties.
11+
This extension introduces `sycl::ext::oneapi::experimental::properties`, which is a replacement for `sycl::property_list` that supports the storage and manipulation of compile-time-constant properties in addition to runtime properties.
1212

1313
== Contributors
1414
Joe Garvey, Intel +
@@ -135,12 +135,12 @@ value to determine which of the extension's APIs the implementation supports.
135135

136136
Properties have a value and key type,
137137
and by convention, these classes are declared in the root of the
138-
`sycl::ext::oneapi` namespace. For a runtime property the key and value types are the same and the name of the property value
138+
`sycl::ext::oneapi::experimental` namespace. For a runtime property the key and value types are the same and the name of the property value
139139
class has no suffix. A runtime property value typically has a constructor
140140
which takes the value(s) of the properties and member function(s) which return those values.
141141

142142
```c++
143-
namespace sycl::ext::oneapi {
143+
namespace sycl::ext::oneapi::experimental {
144144

145145
// This is a runtime property value with one integer parameter.
146146
// The name of the property value class is the the name of the property without any suffix.
@@ -151,7 +151,7 @@ struct foo {
151151
// A runtime property key is an alias to the value type.
152152
using foo_key = foo;
153153

154-
} // namespace oneapi::ext::sycl
154+
} // namespace experimental::oneapi::ext::sycl
155155
```
156156

157157
For compile-time constant parameters the value type is a template specialization of `property_value`.
@@ -161,7 +161,7 @@ time-constant property can be either types or non-type values.
161161
The implementation provides a variable with the property value type. The variable has the name of the property without a suffix.
162162

163163
```c++
164-
namespace sycl::ext::oneapi {
164+
namespace sycl::ext::oneapi::experimental {
165165

166166
template<typename...> struct property_value;
167167

@@ -191,7 +191,7 @@ struct boo_key {
191191
template<typename... Ts>
192192
inline constexpr boo_key::value_t<Ts...> boo;
193193

194-
} // namespace oneapi::ext::sycl
194+
} // namespace experimental::oneapi::ext::sycl
195195

196196
=== Property traits
197197

@@ -203,7 +203,7 @@ that inherits from `std::true_type` for each SYCL runtime class that the
203203
property can be applied to. All have a base case which inherits from `std::false_type`.
204204

205205
```c++
206-
namespace sycl::ext::oneapi {
206+
namespace sycl::ext::oneapi::experimental {
207207
//Base case
208208
template<typename> struct is_property_key : std::false_type {};
209209
template<typename, typename> struct is_property_key_of : std::false_type {};
@@ -229,7 +229,7 @@ template<typename V> struct is_property_value<V, std::void_t<typename V::key_t>>
229229
template<typename V, typename O> struct is_property_value_of<V, O, std::void_t<typename V::key_t>> :
230230
is_property_key_of<typename V::key_t, O> {};
231231

232-
} // namespace oneapi::ext::sycl
232+
} // namespace experimental::oneapi::ext::sycl
233233
```
234234

235235
=== Property value class
@@ -242,7 +242,7 @@ and type of the parameter. When a property has more than one parameter, the
242242
the values and types of the parameters.
243243

244244
```c++
245-
namespace sycl::ext::oneapi {
245+
namespace sycl::ext::oneapi::experimental {
246246

247247
template<typename Property, typename First, typename...Others>
248248
struct property_value {
@@ -259,7 +259,7 @@ struct property_value {
259259
using value_t = First;
260260
};
261261

262-
} // namespace oneapi::ext::sycl
262+
} // namespace experimental::oneapi::ext::sycl
263263
```
264264

265265
The members of `property_value` are described in the table below.
@@ -295,7 +295,7 @@ The implementation provides equality and inequality operators for
295295
properties.
296296

297297
```c++
298-
namespace sycl::ext::oneapi {
298+
namespace sycl::ext::oneapi::experimental {
299299

300300
// Available only if Prop is a compile-time constant property
301301
template <typename Prop, typename...A, typename...B>
@@ -313,7 +313,7 @@ bool operator==(Prop P1, Prop P2);
313313
template <typename Prop>
314314
bool operator!=(Prop P1, Prop P2);
315315

316-
} // namespace oneapi::ext::sycl
316+
} // namespace experimental::oneapi::ext::sycl
317317
```
318318

319319
--
@@ -350,13 +350,13 @@ bool operator!=(Prop P1, Prop P2);
350350

351351
=== Property list `properties`
352352

353-
This extension adds a new template class, `sycl::ext::oneapi::properties`, which is a property list that can contain compile-time constant properties as well as runtime properties.
353+
This extension adds a new template class, `sycl::ext::oneapi::experimental::properties`, which is a property list that can contain compile-time constant properties as well as runtime properties.
354354

355355
`properties` is a class template, and the properties stored by it influence its type. Two `properties` objects have the same type if and only if they were constructed with the same set of compile-time constant property values and the same set of runtime properties.
356356

357357
[NOTE]
358358
====
359-
The runtime properties contained in the property list affect the type of `sycl::ext::oneapi::properties`, but their property values do not.
359+
The runtime properties contained in the property list affect the type of `sycl::ext::oneapi::experimental::properties`, but their property values do not.
360360
====
361361

362362
It is possible at compile-time to determine whether a `properties` object contains a particular (runtime or compile-time constant) property. See the `static constexpr` function `has_property` of the `properties` class.
@@ -376,7 +376,7 @@ That last sentence is not explicitly stated in the core SYCL spec, but it is ass
376376
The new `properties` class template is as follows:
377377

378378
```c++
379-
namespace sycl::ext::oneapi {
379+
namespace sycl::ext::oneapi::experimental {
380380

381381
template<typename PropertyValuesT>
382382
class properties {
@@ -401,7 +401,7 @@ class properties {
401401
static constexpr auto get_property();
402402
};
403403

404-
} // namespace oneapi::ext::sycl
404+
} // namespace experimental::oneapi::ext::sycl
405405
```
406406

407407
[NOTE]
@@ -456,7 +456,7 @@ Available only if `PropertyKeyT` is the property key class of a compile-time con
456456
The following trait is added to recognize a `properties`.
457457

458458
```c++
459-
namespace sycl::ext::oneapi {
459+
namespace sycl::ext::oneapi::experimental {
460460

461461
// New trait to recognize a properties
462462
template<typename propertyListT>
@@ -465,7 +465,7 @@ struct is_property_list;
465465
template<typename propertyListT>
466466
inline constexpr bool is_property_list_v = is_property_list<properties>::value;
467467

468-
} // namespace oneapi::ext::sycl
468+
} // namespace experimental::oneapi::ext::sycl
469469
```
470470

471471
The following table describes the new `is_property_list` trait:
@@ -642,7 +642,7 @@ Adding a new compile-time constant property requires implementers to introduce t
642642
This is an example showing the definition of a compile-time constant property `foo` that takes a single integer parameter. The property key class associated with the property is `foo_key`.
643643

644644
```c++
645-
namespace sycl::ext::oneapi {
645+
namespace sycl::ext::oneapi::experimental {
646646

647647
// foo is the property key class
648648
struct foo_key {
@@ -663,10 +663,7 @@ struct is_property_key<foo_key> : std::true_type {};
663663
template<typename SyclObjectT>
664664
struct is_property_key_of<foo_key, SyclObjectT> : std::true_type {};
665665

666-
} // namespace oneapi
667-
} // namespace ext
668-
669-
} // namespace sycl
666+
} // namespace experimental::oneapi::ext::sycl
670667
```
671668

672669

0 commit comments

Comments
 (0)