Skip to content

[SYCL][DOC] Updates to sycl_ext_oneapi_reusable_events specification. #22201

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
KornevNikita merged 5 commits into from
Jun 23, 2026
Merged

[SYCL][DOC] Updates to sycl_ext_oneapi_reusable_events specification. #22201

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
89d01cc
[SYCL][DOC] Remove the P2P-related requirement from enqueue_signal_event
slawekptak Jun 3, 2026
3c89817
Remove the device argument from make_event, remove the new event member
slawekptak Jun 16, 2026
a5fec19
Add a new device aspect for reusable events.
slawekptak Jun 18, 2026
c51711b
Revert "Add a new device aspect for reusable events."
slawekptak Jun 18, 2026
b7e4732
Address review comments.
slawekptak Jun 23, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
121 changes: 24 additions & 97 deletions sycl/doc/extensions/proposed/sycl_ext_oneapi_reusable_events.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -111,7 +111,7 @@ to determine which of the extension's features the implementation supports.
=== New functions to create an event

This extension adds the following factory functions which can create an event
with a specific context and device.
with a specific context or with associated properties.

'''

Expand All @@ -120,7 +120,7 @@ with a specific context and device.
namespace sycl::ext::oneapi::experimental {

template<typename PropertyListT = empty_properties_t>
event make_event(const context &ctxt, const device &dev, PropertyListT props = {});
event make_event(const context &ctxt, PropertyListT props = {});

} // namespace sycl::ext::oneapi::experimental
----
Expand All @@ -132,45 +132,13 @@ _Constraints:_
* `is_property_list_v<PropertyListT>` is `true` and contains no properties other
than those listed below in section "New property for creating an event".

_Returns:_ An event that is associated with context `ctxt` and device `dev`.
_Returns:_ An event that is associated with context `ctxt`. The event has
`info::event_command_status::complete` status.

_Throws:_

* An `exception` with the `errc::feature_not_supported` error code if
`PropertyListT` contains an `enable_profiling` property that enables
profiling timestamps and if the platform containing `ctxt` does not support
creation of such events as reported by the `event_profiling` information
descriptor.

* An `exception` with the `errc::invalid` error code if `ctxt` does not contain
`dev`.

'''

[source,c++]
----
namespace sycl::ext::oneapi::experimental {

template<typename PropertyListT = empty_properties_t>
event make_event(const device &dev, PropertyListT props = {});

} // namespace sycl::ext::oneapi::experimental
----

_Constraints:_

* `PropertyListT` is one of the properties listed below in section "New property
for creating an event"; or
* `is_property_list_v<PropertyListT>` is `true` and contains no properties other
than those listed below in section "New property for creating an event".

_Effects:_ Equivalent to:

[source,c++,indent=2]
----
sycl::context ctxt = dev.get_platform().khr_get_default_context();
return sycl::ext::oneapi::experimental::make_event(ctxt, dev, props);
----
_Throws:_ An `exception` with the `errc::feature_not_supported` error code if
`PropertyListT` contains an `enable_profiling` property that enables profiling
timestamps and if the platform containing `ctxt` does not support creation of
such events as reported by the `event_profiling` information descriptor.

'''

Expand All @@ -197,50 +165,11 @@ _Effects:_ Equivalent to:
----
sycl::device dev;
sycl::context ctxt = dev.get_platform().khr_get_default_context();
return sycl::ext::oneapi::experimental::make_event(ctxt, dev, props);
return sycl::ext::oneapi::experimental::make_event(ctxt, props);
----

'''

=== New event member functions

This extension adds the following new member functions to the event class:

'''

[source,c++]
----
namespace sycl {

class event {
// ...
device ext_oneapi_get_device() const;
context ext_oneapi_get_context() const;
};

} // namespace sycl
----

'''

[source,c++]
----
device ext_oneapi_get_device() const;
----

_Returns:_ The device object associated with this event.

'''

[source,c++]
----
context ext_oneapi_get_context() const;
----

_Returns:_ The context object associated with this event.

'''

=== New property for creating an event

This extension adds the following property, which can be used with `make_event`:
Expand Down Expand Up @@ -313,7 +242,7 @@ Any commands submitted to the queue after this barrier cannot begin execution
until all commands associated with `evt` or `evts` have completed.

_Remarks:_ The event `evt` and the events in `evts` do _not_ need to have the
same context or the same device as `q`.
same context as `q`.

'''

Expand All @@ -327,9 +256,7 @@ void enqueue_signal_event(queue q, event& evt);
----

_Effects:_ The event `evt` is immediately disassociated with any previous
command, and its status is set to `info::event_command_status::submitted`. The
event is also disassociated with any previous device and is associated with the
device returned by `q.get_device()`.
command, and its status is set to `info::event_command_status::submitted`.

If the queue `q` is in-order (i.e. was constructed with
`property::queue::in_order`), this function enqueues a lightweight "tag"
Expand Down Expand Up @@ -361,6 +288,15 @@ Implementations are encouraged to transition the event directly from the
"submitted" status to the "complete" status and are encouraged to set the
"command_start" timestamp to the same value as the "command_end" timestamp.

_Throws:_

* An `exception` with the `errc::invalid` error code if `evt` and `q` don't
have the same context.
* An `exception` with the `errc::feature_not_supported` error code if `evt`
was created with the `enable_profiling` property that enables profiling
timestamps and if the platform associated with `q` does not support creation
of such events as reported by the `event_profiling` information descriptor.

[_Note:_ In order to understand why the "command_start" and "command_end"
timestamps are encouraged to be the same, think of the tag operation as an empty
kernel with an implicit set of dependencies on all previous commands in the
Expand All @@ -373,20 +309,11 @@ is implemented by submitting an actual kernel, which has non-zero execution
time.
_{endnote}_]

_Throws:_ An `exception` with the `errc::invalid` error code if the device
associated with `evt` differs from the device associated with `q` and the
devices cannot P2P access each other. The P2P access between devices can be
queried using the `device::ext_oneapi_can_access_peer` function and enabled
using the `device::ext_oneapi_enable_peer_access` function defined in the
link:../experimental/sycl_ext_oneapi_peer_access.asciidoc[
sycl_ext_oneapi_peer_access] extension.

Comment thread
slawekptak marked this conversation as resolved.
=== Interaction with other event APIs

An event _E_ created via `make_event` can be used as a command dependency (e.g.
via `handler::depends_on`) for a command submitted to some queue _Q_.
It is _not_ necessary for the context or device of _E_ to match the context or
device of _Q_.
It is _not_ necessary for the context of _E_ to match the context of _Q_.

If an event _E_ is used as a command dependency for some command _C_ (e.g. via
`handler::depends_on`), the dependency is captured at the point when _C_ is
Expand All @@ -405,8 +332,8 @@ class. The default constructor creates an event that is equivalent to calling
`make_event` with no parameters.

Several of the `queue` class member functions from the core SYCL specification
return an event. These events are associated with the queue's context and the
queue's device as though created by `make_event` with that context and device.
return an event. These events are associated with the queue's context as though
created by `make_event` with that context.
These events may be passed to any of the functions in this extension that take
an event parameter.

Expand All @@ -426,7 +353,7 @@ int main() {
sycl::context ctxt = dev.get_platform().khr_get_default_context();
sycl::queue q1{ctxt, dev, sycl::property::queue::in_order{}};
sycl::queue q2{ctxt, dev, sycl::property::queue::in_order{}};
sycl::event e = syclex::make_event(ctxt, dev);
sycl::event e = syclex::make_event(ctxt);

// Launch a kernel on `q1` and then signal an event when the kernel completes.
syclex::parallel_for(q1, {N}, [=](sycl::item<> it) { /* ... */ });
Expand Down
Loading