Skip to content

KHR for properties - #980

Merged
gmlueck merged 55 commits into
KhronosGroup:mainfrom
gmlueck:me/khr-properties
Nov 19, 2026
Merged

gmlueck merged 55 commits into
KhronosGroup:mainfrom
gmlueck:me/khr-properties

Conversation

@gmlueck

@gmlueck gmlueck commented Feb 25, 2026 •

Copy link
Copy Markdown
Contributor

Proposed KHR for a new property mechanism that conveys more information at compilation time. These new style properties allow better error checking at compilation time, and they support properties that can influence the code generated by the compiler (because some properties can have values that are known at compilation time).

It seems to make sense to allow a property with a runtime-supplied value
to be constexpr when the property value is a constant, at least for
those properties whose values could potentially be constants.  This is
not the same as a compile-time constant property, though, because the
type of the property still does not convey the value of the property.

Likewise, it seems to make sense to add `constexpr` to the `properties`
constructor, so that a `properties` can be declared as a constant when
all of its properties are constant expressions.
keryell added a commit to SYCL/properties that referenced this pull request Mar 11, 2026
Minimal C++20 header-only implementation of the compile-time properties
extension: properties class with CTAD, 6 traits, support for runtime,
compile-time and hybrid property kinds, plus queue properties and tests.

My question was:

I would like to create a minimal C++20 implementation for
KhronosGroup/SYCL-Docs#980. You can start by gathering
the C++ pieces found in the AsciiDoctor document and summarize it.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@keryell

keryell commented Mar 11, 2026

Copy link
Copy Markdown
Member

I have made an implementation of this with 5 variations with the help of Claude Code CLI Opus 4.6 1M tokens: https://github.com/SYCL/properties

So it looks like using prop2<> as a key works for constexpr properties. @illuhad

@keryell

keryell commented Mar 12, 2026

Copy link
Copy Markdown
Member

Some other ideas on clean interface https://github.com/qlibs/mp

@VerenaBeckham

Copy link
Copy Markdown
Contributor

I love the idea of compile-time properties, but does Intel have a killer use-case for them right now? As I understand it, all the existing SYCL properties would remain "runtime properties" as described by this KHR. Also, in the "free function commands KHR", which now depends on this KHR, I can't immediately see a property that would be implemented as a compile-time property, unless I missed it?
Is there a compile-time property that you are intending to introduce once this KHR is merged?

@gmlueck

gmlueck commented Mar 16, 2026

Copy link
Copy Markdown
Contributor Author

Is there a compile-time property that you are intending to introduce once this KHR is merged?

The reason we proposed this KHR now is because we want to use it in #922. We'd like to replace the khr::requirements class template with the new khr::properties. The khr::requirements is very similar to khr::properties, but it's not as general. If we can settle on the compile-time properties KHR, then we can avoid defining khr::requirements at all, which will simplify the overall API surface. It will also improve #922 because we can use the new khr::properties in the future to pass kernel launch properties to those APIs. Intel has a number of kernel launch properties in our extensions already, and I expect we will want a standard way for vendors to pass properties when launching a kernel.

@TApplencourt

Copy link
Copy Markdown
Contributor
> The properties defined and illustrated in this extension are all in the sycl::khr namespace rather than some nested namespace like sycl::khr::properties. If this KHR is adopted into the core spec, properties will be defined directly in sycl. This was intentional in order to reduce verbosity in applications that use the extensions. Is this a good idea, or will we end up polluting the top-level SYCL namespace with lots of properties?

Done

> The properties constructor has a Mandates that no two properties in the list have the same key. Does it make sense for this to be a Mandates instead of a Constraint? I think the error message will be better with a Mandates, but you could make that same argument for other cases where we decided to use Constraints anyways.

Not allowed: 
- plist.has_property_list<prop_1<false>, prop_1<true>>;

- C++: Mandates versus Constraint
	- Mandates: Compile Time
	- Constraint: "no overload matching"
		Allow: - if require 
					 - else 
	- Nevin Todo: When does the C++ choise to use Mandates or Constraint.

- No exception for plist.has_property_list<prop_1{true}, prop_1{true}>;
	- To much compile time overhead.
	- Imposible to do for runtime value

> Should we define operator== and operator!= for every property? The DPC++ extension has this, but I left it out of this KHR because they didn’t seem very useful to me.

- Can use `decltype` for get/has in CTS.
- WG vote to go without `==` and `!=`

> Should we define operator== and operator!= for the properties list? This would require metaprogramming to deduce EncodedProperties as the sorted list of Properties, otherwise two properties lists constructed from the same set of properties would have different types if the properties were specified in a different order. The DPC++ extension has this, but I left it out of this KHR because the comparison operators didn’t seem that useful, and I didn’t think it was worth the extra complexity required to sort the properties. Sorting the properties (via metaprogramming) would also slow down compilation (because the properties would be sorted at compilation time), and I didn’t want to impact compilation time by adding this sorting requirement. However, I defined the properties constructor in such a way that we could add this sorting as a later revision of this KHR.

auto p1 = sycl::property_list{ p1, p2 };
auto p2 = sycl::property_list{ p2, p1 };

static_assert { p1 == p2 };


- N^2 algorithm
- Property and property list will not follow SYCL "Common reference semantics", neither "Common  by-value semantics"
- Not possible to be implemented in user-space.
- WG vote to go without `==` and `!=`
- Potential to Add KHR section "Limitation"

> Can we guarantee that properties is trivially copyable unless it contains a runtime property that is not trivially copyable? The POC uses std::tuple to implement properties, and std::tuple is not trivially copyable. As a result the POC version of properties is not trivially copyable. This seems like it should be fixable, though, because the DPC++ version is trivially copyable.

- If `property_list` trivialy copyable, can be passed as Kernel Argument?
	- tuple is currently potentially `Device copyable`.
	- When all compile time, don't need a tuple, so trivial to make it "trivial copyable"

- For the same argument of simplification, we don't say anything.  WG vote to go without the `trivially copyable` requirement

> This KHR already defines the trait is_property_list_for, but should it also define the trait is_property_list? It turns out that none of the APIs in this KHR need is_property_list to implement any of their constraints, but maybe this trait would be useful to users who want to create a utility function that takes a generic properties list?

`is_property_for_v<in_order, queue> == true`
`is_property_for_v<sub_group_size, queue> == false`
`is_property_list_for_v<plist, queue>` == plist.all?

- WG vote for don't add it `is_property_list`. Also maybe easier in C++26 introspection

@CLAassistant

CLAassistant commented Apr 28, 2026 •

Copy link
Copy Markdown

CLA assistant check
All committers have signed the CLA.

KornevNikita pushed a commit to intel/llvm that referenced this pull request Sep 1, 2026
KornevNikita pushed a commit to intel/llvm that referenced this pull request Sep 9, 2026
uditagarwal97 pushed a commit to intel/llvm that referenced this pull request Sep 15, 2026
Implements the queue portion of sycl_khr_properties: the properties
`khr::property::enable_profiling` and `khr::property::in_order`, the
queue
constructor overloads accepting a khr property or property list, and
`queue::khr_is_profiling_enabled()` (`is_in_order()` already existed).
The
new-style properties are translated to the existing
`property::queue::*`.

KHR Link: KhronosGroup/SYCL-Docs#980
Fix the link in the previous commit and add links for the remaining
`context` and `queue` constructor overloads.
@koparasy

Copy link
Copy Markdown
Contributor

KhronosGroup/SYCL-CTS#1251 is ready for review.

In this example, [code]#enable_thing1# and [code]#enable_thing2# are instead
defined as presence-only properties with no boolean value.

[source,,linenums]

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would avoid giving an anti-pattern example. Perhaps a less able AI or an inattentive engineer could copy-paste this code. I think the description in the paragraph above is sufficient anyway.
But this is only a preference.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In an earlier draft, I tried to explain the problem without an example, and I found that readers were confused. Therefore, I have a slight preference to keep the example. I added a comment, which I hope clarifies that it is an anti-pattern in 4b8f242.

That said, I'm happy to remove this example if you (or others) think it's still confusing.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That's fine by me. But perhaps we can get more feedback in the WG call.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In yesterday's WG call we decided that it would be better to move all of the "examples for implementors" out of the formal KHR specification. We think examples should be directed to users of SYCL, not implementors. Therefore, I moved this to the existing "future plans" document and renamed that document to an "ancillary document" for the KHR. See f083c7e and ec6e575.

Comment thread future-plans/sycl_khr_properties.md Resolved
gmlueck and others added 2 commits November 4, 2026 15:26
Co-authored-by: Verena Beckham <vbeckham@qti.qualcomm.com>
gmlueck added a commit that referenced this pull request Nov 5, 2026
Change the definition of `queue::is_in_order` to be more general by
returning `true` whenever the queue is in-order.  This is exactly
identical to its current definition in the core SYCL 2020 language
because the only way to create an in-order queue is via the `in_order`
property.

However, this helps with the proposed KHR in #980 because that KHR
will add a new property that also makes the queue in-order.
We decided that the KHR specification should not contain examples that
are aimed at implementors of the SYCL language.  Therefore, move the
"examples for implementors" to an ancillary document.  Member of the
Khronos working group (and other implementors) can access this ancillary
document when designing patterns for the new-style properties.
@TApplencourt

Copy link
Copy Markdown
Contributor
  • The WG approved this KHR.
  • We will merge it when the CTS is ready.

gmlueck added a commit to slawekptak/SYCL-Docs that referenced this pull request Nov 13, 2026
Our recent direction has been to de-emphasize the buffer / accessor
model, and new KHR extensions are not adding this support.  For example,
the khr_properties extension (KhronosGroup#980) does not add support for buffers or
accessors.
Change the `is_property_list_for` trait to include *both* the case when
`T` is a bare property for `Class` *and* the case when `T` is a property
list of properties for `Class`.

This simplifies many of the constraints because our design pattern
always allows a single property to be passed in place of a property
list.  (The semantics are the same as passing a property list with one
property.)

I think the trait name `is_property_list_for` still makes sense because
we can think of a bare property as a degenerate case of a property list
with one property.
@gmlueck

gmlueck commented Nov 17, 2026

Copy link
Copy Markdown
Contributor Author

I added one more commit (6d90270) since this PR was approved. I realized while working on #922 that the constraints for functions that take a property list are unnecessarily complex. The reason is that our design pattern always allows the user to pass a single bare property in place of a property list. (The semantics are the same as passing a list with one property.) This caused all the constraints to be like

Constraints:

  • khr::is_property_for_v<PropertyOrList, CLASS> is true, or
  • khr::is_property_list_for_v<PropertyOrList, CLASS> is true.

I think it is better to simply redefine what is_property_list_for_v means to include both cases. I think this makes sense because you can view a single bare property as a degenerate case of a property list with one property.

The change allows us to simplify the constraints to look like this instead:

Constraints: khr::is_property_list_for_v<PropertyOrList, CLASS> is true.

I think this change will also improve the error message users get if they pass an incorrect property.

@VerenaBeckham and @0x12CC: if you agree with this late modification, can you indicate your approval by re-approving this PR?

@VerenaBeckham
VerenaBeckham self-requested a review November 18, 2026 12:22
@VerenaBeckham

Copy link
Copy Markdown
Contributor

I added one more commit (6d90270) since this PR was approved. I realized while working on #922 that the constraints for functions that take a property list are unnecessarily complex. The reason is that our design pattern always allows the user to pass a single bare property in place of a property list. (The semantics are the same as passing a list with one property.) This caused all the constraints to be like

Constraints:

  • khr::is_property_for_v<PropertyOrList, CLASS> is true, or
  • khr::is_property_list_for_v<PropertyOrList, CLASS> is true.

I think it is better to simply redefine what is_property_list_for_v means to include both cases. I think this makes sense because you can view a single bare property as a degenerate case of a property list with one property.

The change allows us to simplify the constraints to look like this instead:

Constraints: khr::is_property_list_for_v<PropertyOrList, CLASS> is true.

I think this change will also improve the error message users get if they pass an incorrect property.

@VerenaBeckham and @0x12CC: if you agree with this late modification, can you indicate your approval by re-approving this PR?

Nice, that is much neater!

@gmlueck

gmlueck commented Nov 18, 2026

Copy link
Copy Markdown
Contributor Author

I added one more commit (6d90270) since this PR was approved. I realized while working on #922 that the constraints for functions that take a property list are unnecessarily complex. The reason is that our design pattern always allows the user to pass a single bare property in place of a property list. (The semantics are the same as passing a list with one property.) This caused all the constraints to be like

Constraints:

  • khr::is_property_for_v<PropertyOrList, CLASS> is true, or
  • khr::is_property_list_for_v<PropertyOrList, CLASS> is true.

I think it is better to simply redefine what is_property_list_for_v means to include both cases. I think this makes sense because you can view a single bare property as a degenerate case of a property list with one property.
The change allows us to simplify the constraints to look like this instead:

Constraints: khr::is_property_list_for_v<PropertyOrList, CLASS> is true.

I think this change will also improve the error message users get if they pass an incorrect property.
@VerenaBeckham and @0x12CC: if you agree with this late modification, can you indicate your approval by re-approving this PR?

Nice, that is much neater!

After sleeping on it, I'm thinking that we should rename the trait to is_property_or_list_for (note the "or"). This makes the trait only 3 characters longer, and it seems a bit more descriptive. That might help make the error message a bit more clear if the user passes a wrong property. The naming also aligns with the name of the template parameter in the spec, which is PropertyOrList.

Any objections to that?

@koparasy

Copy link
Copy Markdown
Contributor

The proposed changes are in : intel/llvm#23864

After further reflection, I think this trait should be named
`is_property_or_list_for` because that seems a bit more descriptive.  I
think this will result in a more meaningful error message if someone
passes an invalid property that violates a constraint.
@gmlueck

gmlueck commented Nov 18, 2026

Copy link
Copy Markdown
Contributor Author

After sleeping on it, I'm thinking that we should rename the trait to is_property_or_list_for (note the "or"). This makes the trait only 3 characters longer, and it seems a bit more descriptive. That might help make the error message a bit more clear if the user passes a wrong property. The naming also aligns with the name of the template parameter in the spec, which is PropertyOrList.

Any objections to that?

Done in 1a0c004

@TApplencourt

Copy link
Copy Markdown
Contributor
  • The WG Agree with the KHR proposal
  • Will be merged to main
  • The ratification package then to the board
  • If accepted, will be publish a new minor-version of the specification.

@gmlueck
gmlueck merged commit 5a5d022 into KhronosGroup:main Nov 19, 2026
2 checks passed
KornevNikita pushed a commit to intel/llvm that referenced this pull request Nov 20, 2026
…23864)

There has been a last minute change on the specification, this
implements that change.
KhronosGroup/SYCL-Docs#980 commit:
6d90270a59c479dcae9a51f838e29ffc56368ab1
@gmlueck
gmlueck deleted the me/khr-properties branch November 20, 2026 13:19
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

7 participants