Skip to content

Commit

Permalink
Change "Topologically Identical" Definition
Browse files Browse the repository at this point in the history
Avoid mixing UB and exception conditions of topologically
identical. Only specify violating topologically identical
conditions as UB.
  • Loading branch information
EwanC committed Jul 3, 2024
1 parent 8b66a0b commit 0c42b9a
Showing 1 changed file with 27 additions and 33 deletions.
60 changes: 27 additions & 33 deletions sycl/doc/extensions/experimental/sycl_ext_oneapi_graph.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -206,7 +206,7 @@ Table {counter: tableNumber}. Values of the `SYCL_EXT_ONEAPI_GRAPH` macro.
|1 |Initial extension version. Base features are supported.
|===

=== SYCL Graph Terminology
=== SYCL Graph Terminology [[terminology]]

Table {counter: tableNumber}. Terminology.
[%header,cols="1,3"]
Expand Down Expand Up @@ -776,34 +776,37 @@ conditions:

* Both graphs must have been created with the same device and context.
* Both graphs must be topologically identical. The graphs are considered
topologically identical when:

** Both graphs have the same number of nodes and edges.
** Where edges are specified through the `depends_on` property or through event
dependencies in recorded queue submisions, these must be specified in the same
order.
** Nodes with dependencies on events outside of the graph must have the same
number of these dependencies.
** A kernel node's command function must have the same type in both graphs,
whether that be a lambda function, function object or otherwise.
** When creating both graphs all graph-related API calls or operations which
modify the structure of the graph must have been done in the same order, these
are:

*** Explicit API calls to add nodes to the graph or calls to `make_edge()`.
*** Nodes added to a graph via recorded queue submissions.
topologically identical when:

** Both graphs must have the same number of nodes and edges.
** Internal edges must be between corresponding nodes in each graph.
** Nodes must be added in the same order in the two graphs. Nodes may be added
via `command_graph::add`, or for a recorded queue via `queue::submit` or
queue shortcut functions.
** Corresponding nodes in each graph must be kernels that have the same type:

*** When the kernel is defined as a lambda, the lambda must be the same.
*** When the kernel is defined as a named function object, the kernel class
must be the same.
*** When the kernel is defined as a plain function, the function must be the
same.

** Edge dependencies for each node in the two graphs must be created in the
same order and using the same API mechanism to create each edge. See
the <<terminology, terminology section>> for an exhaustive definition of
how edges are defined in a graph for each of the two graph construction
APIs.

Attempting to use whole-graph update with source or target graphs which do not
satisfy these conditions results in undefined behaviour as it may prevent the
runtime from pairing nodes in the source and target graphs.
satisfy the conditions of topological identity results in undefined behaviour,
as it may prevent the runtime from pairing nodes in the source and target
graphs.

It is valid to use nodes that contain dynamic parameters in whole graph updates.
If a node containing a dynamic parameter is updated through the whole graph
update API, then any previous updates to the dynamic parameter will be reflected
in the new graph.

:sycl-kernel-function: https://registry.khronos.org/SYCL/specs/sycl-2020/html/sycl-2020.html#sycl-kernel-function

==== Graph Properties [[graph-properties]]

===== No-Cycle-Check Property
Expand Down Expand Up @@ -1228,7 +1231,7 @@ The characteristics in the executable graph which will be updated are detailed
in the section on <<executable-graph-update, Executable Graph Update>>.

It is not an error to update an executable graph such that all parameters of
nodes in `graph` are identical to the arguments of the executable graph prior to
nodes in `source` are identical to the arguments of the executable graph prior to
the update.

The implementation may perform a blocking wait during this call on
Expand All @@ -1248,22 +1251,13 @@ Parameters:

Exceptions:

* Throws synchronously with error code `invalid` if the topology of
`source` is not the same as the target graph topology in the following ways:

** The number of nodes in the graph does not match.
** The number of edges between nodes does not match.
** Any node in `source` has a dependency which does not matched the paired node
in the target graph.

* Throws synchronously with error code `invalid` if `source` contains any node
which is not of the following `node_type`s:
which is not one of the following types:

** `node_type::empty`
** `node_type::empty`
** `node_type::ext_oneapi_barrier`
** `node_type::kernel`


* Throws synchronously with error code `invalid` if the context or device
associated with `source` does not match that of the `command_graph` being
updated.
Expand Down

0 comments on commit 0c42b9a

Please sign in to comment.