KhronosGroup / KhronosGroup/SYCL-Docs
Clarify behavior when wrong property is passed
- Dominant language
- JavaScript
- Stars
- 158
- Forks
- 80
- Avg merge
- 7d 6h
- Merged PRs (30d)
- 5
Description
This question came from our development team.
The specification does not say what should happen if an incompatible property is passed to an API that takes a `property_list`. Here is a list of the APIs that take a `property_list`. I don't think any of them currently specify the behavior when an incompatible property is passed.
* `context` constructors
* `queue` constructors
* `buffer` constructors
* `unsampled_image` constructors
* `sampled_image` constructors
* `accessor` constructors
* `host_accessor` constructors
* `local_accessor` constructors
* `unsampled_image_accessor` constructors
* `host_unsampled_image_accessor` constructors
* `sampled_image_accessor` constructors
* `host_sampled_image_accessor` constructors
* `usm_allocator` constructors
* `malloc_device`, `aligned_alloc_device`
* `malloc_host`, `aligned_alloc_host`
* `malloc_shared`, `aligned_alloc_shared`
* `sycl::malloc`, `aligned_alloc`
* `reduction` functions
* `compile`, `link`, `build` (kernel bundle)
* `stream` constructors
I think there are two reasonable options:
1. Mandate that these APIs throw `errc::invalid` in this case.
2. Add a precondition that the properties are compatible with the given API, which means that the behavior is undefined if they are not.
Contributor guide
No contributing guide indexed for this repository
Research direction
Start with issue #643 and the specification sections for the listed property_list APIs, including constructors, allocation functions, reduction, kernel-bundle operations, and stream constructors. Determine whether incompatible properties should require errc::invalid or be covered by a precondition, then update the affected specification text consistently. Done means each listed API has defined behavior for incompatible properties.
Written by the indexing model from the issue text.
Assessment
- Domain
- api, documentation
- Issue type
- Documentation
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 25/100