KhronosGroup / KhronosGroup/SYCL-Docs
Add `queue::submit` and `handler::parallel_for` overloads accepting `property_list`
- Dominant language
- JavaScript
- Stars
- 158
- Forks
- 80
- Avg merge
- 7d 6h
- Merged PRs (30d)
- 5
Description
Properties is SYCL serve as a generic way to expanding the behavior of a class or function, either with standardized properties or with vendor-specific ones.
Submitting tasks to a queue is, in a way, the most important operation in heterogeneous programming, so it seems reasonable that there could be need to customize it with various runtime properties (compile-time properties are a separate issue; I am primarily concerned with run-time ones here). However, neither `queue::submit` nor `handler::parallel_for` (and it's variations) allow specifying a property list in SYCL 2020.
The need to provide properties is definitely there, as both major implementations have to work around that:
- AdaptiveCpp has `ACPP_EXT_CG_PROPERTY_` extension family, which introduce `queue::submit(const property_list& prop_list, T cgf)` function. It can be used not only for kernels, but for other submissions as well.
- DPC++ has `sycl_ext_oneapi_kernel_properties` which introduces `handler::single_task(PropertyList properties, const KernelType &kernelFunc);` and similar overloads for `parallel_for` and their shorthands in `sycl::queue`. The extension is focused on compile-time properties but notes that "an implementation may support additional properties which could have run-time values".
From a user perspective, the difference in function signatures mean that if extensions from both vendors are used, the kernel invocation code starts looking like:
```cpp
#if DPCPP
# define DPCPP_PROPERTY sycl::ext::oneapi::experimental::properties { /*...*/ },
# define ACPP_PROPERTY
#elif ACPP
# define DPCPP_PROPERTY
# define ACPP_PROPERTY sycl::property_list { /*...*/ },
#else
# define DPCPP_PROPERTY
# define ACPP_PROPERTY
#endif
q.submit([&](ACPP_PROPERTY sycl::handler& cgh) {
cgh.parallel_for(range, DPCPP_PROPERTY [=](/*...*/) { /*...*/ });
});
```
In particular, the comma at the end of the macro is very nasty. A wrapper functions like `my_parallel_for(sycl::queue, sycl::range, Kernel&& f)` could make the code prettier, but this still is not optimal from the user perspective, given that SYCL standard has a much better solution for this problem in other places: optional `sycl::property_list` parameter.
In SYCL 2020, `sycl::property_list` is mainly used in constructors, but there are cases where it is used in free functions, such as `sycl::malloc_device` &co, where `property_list` is explicitly said to be added for future extensibility, with no suitable properties defined by the standard. I see little reason to limit this extensibility to memory allocation alone.
The suggestion is to add overloads to `queue::submit`, `queue::single_task`, `queue::parallel_for`, `queue::memcpy`, `queue::copy`, `queue::memset`, `queue::fill`, `handler::single_task`, `handler::parallel_for`, `handler::parallel_for_work_group`, `handler::memcpy`, `handler::copy`, `handler::memset`, and `handler::fill` functions with a `property_list` parameter (right before the kernel parameter) to allow users to pass run-time properties. Even if the construction of property_lists relies on macros to construct vendor-specific property objects, the kernel invocation code will be much cleaner and more aligned with how the rest of SYCL API is organized.
Contributor guide
No contributing guide indexed for this repository
Research direction
Start by reviewing the listed queue and handler entry points, especially submit, parallel_for, and the other submission operations named in the issue. Compare their proposed property_list parameter placement with the existing SYCL property_list APIs and vendor examples; done means the specification has a consistent, resolved overload design for the requested operations.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- cpp
- Domain
- backend-api-design
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100