From 10b84d22e294c506f6112e46c6639c88975b682a Mon Sep 17 00:00:00 2001 From: "Ptak, Slawomir" Date: Fri, 17 Jul 2026 12:10:06 +0000 Subject: [PATCH 1/6] [SYCL][DOC] Introduce limitations to the Reusable Events specification. Update the sycl_ext_oneapi_reusable_events specification with some limitations related to the following: - Limit the interoperability between the Reusable Events API and other event APIs. - Limit the enqueue_wait_event and enqueue_wait_events, so they can only be called with events on the same context as the queue. The limitations are related to how host tasks are used for cross-context dependencies in the SYCL RT. --- .../sycl_ext_oneapi_reusable_events.asciidoc | 47 ++++++++++--------- 1 file changed, 26 insertions(+), 21 deletions(-) diff --git a/sycl/doc/extensions/proposed/sycl_ext_oneapi_reusable_events.asciidoc b/sycl/doc/extensions/proposed/sycl_ext_oneapi_reusable_events.asciidoc index 5a41e62db6950..a5b589fb7b464 100644 --- a/sycl/doc/extensions/proposed/sycl_ext_oneapi_reusable_events.asciidoc +++ b/sycl/doc/extensions/proposed/sycl_ext_oneapi_reusable_events.asciidoc @@ -241,8 +241,21 @@ _Effects:_ Enqueues a special barrier to `q` with the following semantic. 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 as `q`. +_Throws:_ + + * An `exception` with the `errc::invalid` error code if `evt` or any of events + in `evts` was not created using the `make_event` function or default + constructed. + * An `exception` with the `errc::invalid` error code if `evt` and `q` don't + have the same context or any event in `evts` and `q` don't have the same + context. + +_Remarks:_ If an event `evt` is used as a command dependency for some command +_C_ (e.g. via `enqueue_wait_event`), the dependency is captured at the point +when _C_ is submitted. +It is legal to reassociate the event `evt` to a new command via +`enqueue_signal_event` even before command _C_ completes. Doing so does _not_ +change the dependency for command _C_. ''' @@ -292,6 +305,8 @@ _Throws:_ * An `exception` with the `errc::invalid` error code if `evt` and `q` don't have the same context. + * An `exception` with the `errc::invalid` error code if `evt` was not created + using the `make_event` function or default constructed. * 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 @@ -311,32 +326,22 @@ _{endnote}_] === 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 of _E_ to match the context of _Q_. +The core SYCL specification defines a default constructor for the `event` +class. The default constructor creates an event that is equivalent to calling +`make_event` with no parameters. -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 -submitted. -It is legal to reassociated the event _E_ to a new command via -`enqueue_signal_event` even before command _C_ completes. -Doing so does _not_ change the dependency for command _C_. +An event created via `make_event` or a default constructed event can only be +used with the APIs defined in this extension. + +Several of the `queue` class member functions from the core SYCL specification +return an event. These events cannot be passed to any of the functions defined +in this extension. If another host thread is blocked waiting for event _E_ to complete via `event:wait` or `event::wait_and_throw` when event _E_ is reassociated with a new command via `enqueue_signal_event`, the behavior of the `event:wait` or `event::wait_and_throw` call is undefined. -The core SYCL specification defines a default constructor for the `event` -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 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. - == Examples === Recording cross queue dependencies From a713a6bcabd70b80e8c17069e980d5b0c69b4e46 Mon Sep 17 00:00:00 2001 From: "Ptak, Slawomir" Date: Mon, 20 Jul 2026 09:43:42 +0000 Subject: [PATCH 2/6] Introduce reusable and non-reusable events. --- .../sycl_ext_oneapi_reusable_events.asciidoc | 62 +++++++++++++------ 1 file changed, 43 insertions(+), 19 deletions(-) diff --git a/sycl/doc/extensions/proposed/sycl_ext_oneapi_reusable_events.asciidoc b/sycl/doc/extensions/proposed/sycl_ext_oneapi_reusable_events.asciidoc index a5b589fb7b464..816de2ab03334 100644 --- a/sycl/doc/extensions/proposed/sycl_ext_oneapi_reusable_events.asciidoc +++ b/sycl/doc/extensions/proposed/sycl_ext_oneapi_reusable_events.asciidoc @@ -133,7 +133,8 @@ _Constraints:_ than those listed below in section "New property for creating an event". _Returns:_ An event that is associated with context `ctxt`. The event has -`info::event_command_status::complete` status. +`info::event_command_status::complete` status. The event is reusable (the +event::ext_oneapi_reusable() function returns true). _Throws:_ An `exception` with the `errc::feature_not_supported` error code if `PropertyListT` contains an `enable_profiling` property that enables profiling @@ -220,6 +221,26 @@ profiling enabled via `make_event`. ''' +==== New event member function + +This extension adds a new event type member function, which can be used to +check if a given event is reusable. + +[source,c++] +---- +namespace sycl { + +class event { + // ... + bool ext_oneapi_reusable() const; +}; + +} // namespace sycl +---- + +_Returns:_ True if the event was created using the `make_event` function or +with a default event constructor. + === New functions to enqueue event operations This extension adds the following free functions which submit operations related @@ -243,19 +264,14 @@ until all commands associated with `evt` or `evts` have completed. _Throws:_ - * An `exception` with the `errc::invalid` error code if `evt` or any of events - in `evts` was not created using the `make_event` function or default - constructed. - * An `exception` with the `errc::invalid` error code if `evt` and `q` don't - have the same context or any event in `evts` and `q` don't have the same + * An `exception` with the `errc::invalid` error code if `evt` is reusable + (`event::ext_oneapi_reusable() returns true) and `evt` and `q` don't have + the same context. + * An `exception` with the `errc::invalid` error code if all the events in + `evts` are reusable and any event in `evts` and `q` don't have the same context. - -_Remarks:_ If an event `evt` is used as a command dependency for some command -_C_ (e.g. via `enqueue_wait_event`), the dependency is captured at the point -when _C_ is submitted. -It is legal to reassociate the event `evt` to a new command via -`enqueue_signal_event` even before command _C_ completes. Doing so does _not_ -change the dependency for command _C_. + * An `exception` with the `errc::invalid` error code if `evts` contains + reusable and non-reusable events. ''' @@ -303,10 +319,9 @@ Implementations are encouraged to transition the event directly from the _Throws:_ + * An `exception` with the `errc::invalid` error code if `evt` is not reusable. * An `exception` with the `errc::invalid` error code if `evt` and `q` don't have the same context. - * An `exception` with the `errc::invalid` error code if `evt` was not created - using the `make_event` function or default constructed. * 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 @@ -330,12 +345,21 @@ The core SYCL specification defines a default constructor for the `event` class. The default constructor creates an event that is equivalent to calling `make_event` with no parameters. -An event created via `make_event` or a default constructed event can only be -used with the APIs defined in this extension. +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_. +The context of _E_ needs to match the context of _Q_. Several of the `queue` class member functions from the core SYCL specification -return an event. These events cannot be passed to any of the functions defined -in this extension. +return an event. These events can be passed to `enqueue_wait_event` and +`enqueue_wait_events` functions. They are not reusable and cannot be passed to +`enqueue_signal_event`. + +If an event `evt` is used as a command dependency for some command _C_ (e.g. +via `enqueue_wait_event`), the dependency is captured at the point when _C_ is +submitted. +It is legal to reassociate the event `evt` to a new command via +`enqueue_signal_event` even before command _C_ completes. Doing so does _not_ +change the dependency for command _C_. If another host thread is blocked waiting for event _E_ to complete via `event:wait` or `event::wait_and_throw` when event _E_ is reassociated with a From 569e63aad2da6ee69e90a6d7e61bf7210924f721 Mon Sep 17 00:00:00 2001 From: "Ptak, Slawomir" Date: Mon, 20 Jul 2026 09:49:32 +0000 Subject: [PATCH 3/6] Clarify the interaction with other APIs. --- .../proposed/sycl_ext_oneapi_reusable_events.asciidoc | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/sycl/doc/extensions/proposed/sycl_ext_oneapi_reusable_events.asciidoc b/sycl/doc/extensions/proposed/sycl_ext_oneapi_reusable_events.asciidoc index 816de2ab03334..ea5f667c75f00 100644 --- a/sycl/doc/extensions/proposed/sycl_ext_oneapi_reusable_events.asciidoc +++ b/sycl/doc/extensions/proposed/sycl_ext_oneapi_reusable_events.asciidoc @@ -345,14 +345,14 @@ The core SYCL specification defines a default constructor for the `event` class. The default constructor creates an event that is equivalent to calling `make_event` with no parameters. -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_. +Reusable event _E_ can be used as a command dependency (e.g. via +`handler::depends_on`) for a command submitted to some queue _Q_. The context of _E_ needs to match the context of _Q_. Several of the `queue` class member functions from the core SYCL specification -return an event. These events can be passed to `enqueue_wait_event` and -`enqueue_wait_events` functions. They are not reusable and cannot be passed to -`enqueue_signal_event`. +return an event. These events are non-reusable. +They can be passed to `enqueue_wait_event` and `enqueue_wait_events` functions. +They cannot be passed to `enqueue_signal_event`. If an event `evt` is used as a command dependency for some command _C_ (e.g. via `enqueue_wait_event`), the dependency is captured at the point when _C_ is From 6528f6377a0818f663bd375a633ae94ef2cd4dab Mon Sep 17 00:00:00 2001 From: "Ptak, Slawomir" Date: Mon, 20 Jul 2026 10:00:24 +0000 Subject: [PATCH 4/6] Update the inter process communication specification. --- .../sycl_ext_oneapi_inter_process_communication.asciidoc | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/sycl/doc/extensions/experimental/sycl_ext_oneapi_inter_process_communication.asciidoc b/sycl/doc/extensions/experimental/sycl_ext_oneapi_inter_process_communication.asciidoc index 979ee3692a29c..bd4e3d1c7b7de 100644 --- a/sycl/doc/extensions/experimental/sycl_ext_oneapi_inter_process_communication.asciidoc +++ b/sycl/doc/extensions/experimental/sycl_ext_oneapi_inter_process_communication.asciidoc @@ -1332,7 +1332,8 @@ _Returns:_ An `event` object that represents the same event identified by `handle_data`. The returned event is associated with context `ctx`. The returned event and the event identified by `handle_data` share the same state. When one is signaled, the state of the other event automatically becomes -signaled also. +signaled also. The returned `event` is reusable (see the +sycl_ext_oneapi_reusable_events extension). [_Note:_ The `open` function can be called multiple times on the same handle within the same process. Each call to the `open` function may return a unique From 9914cf0a6920492e335b370968df517ec7bc8718 Mon Sep 17 00:00:00 2001 From: "Ptak, Slawomir" Date: Mon, 20 Jul 2026 10:38:23 +0000 Subject: [PATCH 5/6] Limit the use of reusable events to the reusable events extension APIs. Remove the host task section. --- .../sycl_ext_oneapi_reusable_events.asciidoc | 39 ++++--------------- 1 file changed, 7 insertions(+), 32 deletions(-) diff --git a/sycl/doc/extensions/proposed/sycl_ext_oneapi_reusable_events.asciidoc b/sycl/doc/extensions/proposed/sycl_ext_oneapi_reusable_events.asciidoc index ea5f667c75f00..cb86628b546e1 100644 --- a/sycl/doc/extensions/proposed/sycl_ext_oneapi_reusable_events.asciidoc +++ b/sycl/doc/extensions/proposed/sycl_ext_oneapi_reusable_events.asciidoc @@ -264,14 +264,9 @@ until all commands associated with `evt` or `evts` have completed. _Throws:_ - * An `exception` with the `errc::invalid` error code if `evt` is reusable - (`event::ext_oneapi_reusable() returns true) and `evt` and `q` don't have - the same context. - * An `exception` with the `errc::invalid` error code if all the events in - `evts` are reusable and any event in `evts` and `q` don't have the same - context. - * An `exception` with the `errc::invalid` error code if `evts` contains - reusable and non-reusable events. + * An `exception` with the `errc::invalid` error code if `evt` is non-reusable + (`event::ext_oneapi_reusable() returns false) or any event in `evts` is + non-reusable. ''' @@ -319,7 +314,7 @@ Implementations are encouraged to transition the event directly from the _Throws:_ - * An `exception` with the `errc::invalid` error code if `evt` is not reusable. + * An `exception` with the `errc::invalid` error code if `evt` is non-reusable. * 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` @@ -345,14 +340,11 @@ The core SYCL specification defines a default constructor for the `event` class. The default constructor creates an event that is equivalent to calling `make_event` with no parameters. -Reusable event _E_ can be used as a command dependency (e.g. via -`handler::depends_on`) for a command submitted to some queue _Q_. -The context of _E_ needs to match the context of _Q_. +Reusable events can only be used with APIs defined in this extension. Several of the `queue` class member functions from the core SYCL specification -return an event. These events are non-reusable. -They can be passed to `enqueue_wait_event` and `enqueue_wait_events` functions. -They cannot be passed to `enqueue_signal_event`. +return an event. These events are non-reusable. They cannot be passed to any +APIs defined in this extension. If an event `evt` is used as a command dependency for some command _C_ (e.g. via `enqueue_wait_event`), the dependency is captured at the point when _C_ is @@ -488,20 +480,3 @@ event when a command is submitted, rather than taking an event as input. previous call attached to the SYCL `event`. If so, the `cl_event` is released before calling `clEnqueueMarkerWithWaitList` or `clEnqueueBarrierWithWaitList`. - -=== Host tasks - -Because host tasks are executed by the SYCL runtime, there can be cases where -a command _C_ is submitted at the SYCL level, but the command remains pending -inside the SYCL runtime until a host task completes. -(E.g. when command _C_ has a dependency on the host task.) -As a result, there may be cases when `enqueue_signal_event` must also leave the -"event signal" operation pending in the SYCL runtime, or when -`enqueue_wait_event` must leave the "event wait" operation pending in the SYCL -runtime. -In these cases, we expect that a backend event may not be associated with the -SYCL event until the pending operations are resolved in the runtime library. -This will likely cause the handling of events to be less efficient when host -tasks are submitted to the same queue as "native" commands like kernels or -copy operations, or when there are dependencies between host tasks and native -commands. From 0a538378e599116f166ff5aac1352e1ff05ee6cc Mon Sep 17 00:00:00 2001 From: "Ptak, Slawomir" Date: Mon, 20 Jul 2026 12:28:47 +0000 Subject: [PATCH 6/6] Address review comments. --- ...neapi_inter_process_communication.asciidoc | 28 ++++++++----------- .../sycl_ext_oneapi_reusable_events.asciidoc | 8 +++--- 2 files changed, 16 insertions(+), 20 deletions(-) diff --git a/sycl/doc/extensions/experimental/sycl_ext_oneapi_inter_process_communication.asciidoc b/sycl/doc/extensions/experimental/sycl_ext_oneapi_inter_process_communication.asciidoc index bd4e3d1c7b7de..a8194e83817c5 100644 --- a/sycl/doc/extensions/experimental/sycl_ext_oneapi_inter_process_communication.asciidoc +++ b/sycl/doc/extensions/experimental/sycl_ext_oneapi_inter_process_communication.asciidoc @@ -1172,28 +1172,24 @@ _Remarks:_ `property::queue::enable_profiling` property. * `enqueue_signal_event`, `enqueue_wait_event`, `enqueue_wait_events` (from - the sycl_ext_oneapi_reusable_events extension) and `handler::depends_on` - functions throw an exception with the `errc::feature_not_supported` error - code if inter-process sharing of the event is enabled via `enable_ipc` and a - device associated with the queue (passed to those functions or associated - with the `handler`) does not have the aspect `aspect::ext_oneapi_ipc_event`. + the sycl_ext_oneapi_reusable_events extension) functions throw an exception + with the `errc::feature_not_supported` error code if inter-process sharing + of the event is enabled via `enable_ipc` and a device associated with the + queue does not have the aspect `aspect::ext_oneapi_ipc_event`. * `enqueue_signal_event`, `enqueue_wait_event`, `enqueue_wait_events` (from - the sycl_ext_oneapi_reusable_events extension) and `handler::depends_on` - functions throw an exception with the `errc::feature_not_supported` error - code if inter-process sharing of the event is enabled via `enable_ipc` and a - queue (passed to those functions or associated with the `handler`) has an - enqueued host task that has not completed (scheduled using the - `handler::host_task` function). + the sycl_ext_oneapi_reusable_events extension) functions throw an exception + with the `errc::feature_not_supported` error code if inter-process sharing + of the event is enabled via `enable_ipc` and a queue has an enqueued host + task that has not completed. * If the event has been enqueued for signaling (using `enqueue_signal_event`) in some process, and the IPC handle associated with that event has been passed to the `open` function in another process, then the resulting event - can be used as a dependency (using `handler::depends_on`) or passed to - `enqueue_wait_event` or `enqueue_wait_events` functions only if the device - associated with the queue passed to `enqueue_signal_event` and the device - associated with the queue where the dependency is set, can P2P access each - other. + can be used as a dependency by calling the `enqueue_wait_event` or + `enqueue_wait_events` functions only if the device associated with the queue + passed to `enqueue_signal_event` and the device associated with the queue + where the dependency is set, can P2P access each other. ==== New event member function diff --git a/sycl/doc/extensions/proposed/sycl_ext_oneapi_reusable_events.asciidoc b/sycl/doc/extensions/proposed/sycl_ext_oneapi_reusable_events.asciidoc index cb86628b546e1..82466978e5c3c 100644 --- a/sycl/doc/extensions/proposed/sycl_ext_oneapi_reusable_events.asciidoc +++ b/sycl/doc/extensions/proposed/sycl_ext_oneapi_reusable_events.asciidoc @@ -134,7 +134,7 @@ _Constraints:_ _Returns:_ An event that is associated with context `ctxt`. The event has `info::event_command_status::complete` status. The event is reusable (the -event::ext_oneapi_reusable() function returns true). +`event::ext_oneapi_reusable()` function returns `true`). _Throws:_ An `exception` with the `errc::feature_not_supported` error code if `PropertyListT` contains an `enable_profiling` property that enables profiling @@ -265,7 +265,7 @@ until all commands associated with `evt` or `evts` have completed. _Throws:_ * An `exception` with the `errc::invalid` error code if `evt` is non-reusable - (`event::ext_oneapi_reusable() returns false) or any event in `evts` is + (`event::ext_oneapi_reusable()` returns `false`) or any event in `evts` is non-reusable. ''' @@ -354,8 +354,8 @@ It is legal to reassociate the event `evt` to a new command via change the dependency for command _C_. If another host thread is blocked waiting for event _E_ to complete via -`event:wait` or `event::wait_and_throw` when event _E_ is reassociated with a -new command via `enqueue_signal_event`, the behavior of the `event:wait` or +`event::wait` or `event::wait_and_throw` when event _E_ is reassociated with a +new command via `enqueue_signal_event`, the behavior of the `event::wait` or `event::wait_and_throw` call is undefined. == Examples