Skip to content

Commit

Permalink
Refine based on implementation findings
Browse files Browse the repository at this point in the history
  • Loading branch information
EwanC committed Oct 15, 2024
1 parent 9055cc9 commit fcf08a6
Show file tree
Hide file tree
Showing 2 changed files with 30 additions and 11 deletions.
40 changes: 30 additions & 10 deletions sycl/doc/extensions/experimental/sycl_ext_oneapi_graph.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -523,7 +523,7 @@ Table {counter: tableNumber}. Member functions of the `dynamic_parameter` class.
|
[source,c++]
----
dynamic_parameter(command_graph<graph_state::modifiable> graph,
dynamic_parameter(command_graph<graph_state::modifiable> graph,
const ValueT &initialValue);
----
|Constructs a dynamic parameter object that can be registered with command graph
Expand Down Expand Up @@ -564,10 +564,10 @@ namespace ext::oneapi::experimental {
class dynamic_command_group {
public:
dynamic_command_group(
command_graph<graph_state::modifiable> graph,
command_graph<graph_state::modifiable> &graph,
const std::vector<std::function<void(handler &)>>& cgfList);
size_t get_active_cgf();
size_t get_active_cgf() const;
void set_active_cgf(size_t cgfIndex);
};
----
Expand All @@ -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 <<executable-graph-update, Executable Graph Update>> for more information
about updating command-groups.

Expand All @@ -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"]
Expand All @@ -602,7 +605,7 @@ Table {counter: tableNumber}. Member functions of the `dynamic_command_group` cl
[source,c++]
----
dynamic_command_group(
command_graph<graph_state::modifiable> graph,
command_graph<graph_state::modifiable> &graph,
const std::vector<std::function<void(handler &)>>& cgfList);
----

Expand All @@ -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
<<assume-buffer-outlives-graph-property, Assume-Buffer-Outlives-Graph>>
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`.
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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++]
----
Expand Down
1 change: 0 additions & 1 deletion sycl/doc/syclgraph/SYCLGraphUsageGuide.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down

0 comments on commit fcf08a6

Please sign in to comment.