diff --git a/sycl/doc/extensions/experimental/sycl_ext_oneapi_graph.asciidoc b/sycl/doc/extensions/experimental/sycl_ext_oneapi_graph.asciidoc index 9751dddcbe49c..dcbb1b72a2323 100644 --- a/sycl/doc/extensions/experimental/sycl_ext_oneapi_graph.asciidoc +++ b/sycl/doc/extensions/experimental/sycl_ext_oneapi_graph.asciidoc @@ -523,7 +523,7 @@ Table {counter: tableNumber}. Member functions of the `dynamic_parameter` class. | [source,c++] ---- -dynamic_parameter(command_graph graph, +dynamic_parameter(command_graph graph, const ValueT &initialValue); ---- |Constructs a dynamic parameter object that can be registered with command graph @@ -564,10 +564,10 @@ namespace ext::oneapi::experimental { class dynamic_command_group { public: dynamic_command_group( - command_graph graph, + command_graph &graph, const std::vector>& cgfList); - size_t get_active_cgf(); + size_t get_active_cgf() const; void set_active_cgf(size_t cgfIndex); }; ---- @@ -579,6 +579,8 @@ as active. When a dynamic command-group node is executed, the kernel of the acti command-group function will be run and all the other command-group functions in `cgfList` will be ignored. +The `dynamic_command_group` class provides the {crs}[common reference semantics]. + See <> for more information about updating command-groups. @@ -591,7 +593,8 @@ All the command-group functions in a dynamic command-group must have identical d It is not allowed for a dynamic command-group to have command-group functions that would result in a change to the graph topology when set to active. In practice, this means that any calls to `handler.depends_on()` must be identical for all the command-group functions -in a dynamic command-group. +in a dynamic command-group. The dependencies created by buffer accessors must also create +identical node dependencies across all of the command-group functions. Table {counter: tableNumber}. Member functions of the `dynamic_command_group` class. [cols="2a,a"] @@ -602,7 +605,7 @@ Table {counter: tableNumber}. Member functions of the `dynamic_command_group` cl [source,c++] ---- dynamic_command_group( -command_graph graph, +command_graph &graph, const std::vector>& cgfList); ---- @@ -618,21 +621,22 @@ Exceptions: * Throws synchronously with error code `invalid` if the graph wasn't created with the `property::graph::assume_buffer_outlives_graph` property and the `dynamic_command_group` - is created with command-group functions that use buffers. See the + is created with any command-group function that uses buffers. See the <> property for more information. * Throws with error code `invalid` if the `dynamic_command_group` is created with command-group functions that are not kernel executions. -* Throws with error code `invalid` if the command-group functions in `cgfList` have - event dependencies that are incompatible with each other and would result in - different graph topologies when set to active. +* Throws with error code `invalid` if `cgfList` is empty. + +* Throws with error code `invalid` if the command-group functions in `cgfList` + mix the use of `sycl::nd_range` and `sycl::range` in command-group functions. | [source,c++] ---- -size_t get_active_cgf(); +size_t get_active_cgf() const; ---- |Returns the index of the currently active command-group function in this `dynamic_command_group`. @@ -909,6 +913,14 @@ dynamic parameters can be used in command-group functions that are part of dynamic command-groups. Updates to such dynamic parameters will be reflected in the command-group functions once they are activated. +Note that the execution range is tied to the command-group, therefore updating +the range of a node which uses a dynamic command-group shared by another node +will also update the execution range of the nodes sharing the dynamic +command-group. Activating a command-group with `set_active_cgf` to a +command-group that previously had its execution range updated with +`node::update_range()` or `node::update_nd_range()` will not reset the execution +range to the original, but instead use the most recently updated value. + ====== Committing Updates Updating a node using the methods mentioned above will take effect immediately @@ -1230,6 +1242,14 @@ Exceptions: * Throws synchronously with error code `invalid` if a queue is recording commands to the graph. + +* Throws synchronously with error code `invalid` if the graph does not match + the graph used on construction of `dynamicCG`. + +* Throws with error code `invalid` if the command-group functions in `cgfList` have + event or accessor dependencies that are incompatible with each other and + would result in different graph topologies when set to active. + | [source,c++] ---- diff --git a/sycl/doc/syclgraph/SYCLGraphUsageGuide.md b/sycl/doc/syclgraph/SYCLGraphUsageGuide.md index c7c824b5191ee..1ae9b4c0cd225 100644 --- a/sycl/doc/syclgraph/SYCLGraphUsageGuide.md +++ b/sycl/doc/syclgraph/SYCLGraphUsageGuide.md @@ -497,7 +497,6 @@ ExecGraph.update(DynamicCGNode); Queue.ext_oneapi_graph(ExecGraph).wait(); ``` - ### Whole Graph Update Example that shows recording and updating several nodes with different