KhronosGroup / KhronosGroup/SYCL-Docs

Clarify behavior when wrong property is passed

Open
#643 12 comments 0 reactions 0 assignees View on GitHub
clarification
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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.