Skip to content

Commit c4183c8

Browse files
committed
Change "Topologically Identical" Definition
Avoid mixing UB and exception conditions of topologically identical. Only specify violating topologically identical conditions as UB.
1 parent 8b66a0b commit c4183c8

File tree

1 file changed

+27
-33
lines changed

1 file changed

+27
-33
lines changed

sycl/doc/extensions/experimental/sycl_ext_oneapi_graph.asciidoc

Lines changed: 27 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -206,7 +206,7 @@ Table {counter: tableNumber}. Values of the `SYCL_EXT_ONEAPI_GRAPH` macro.
206206
|1 |Initial extension version. Base features are supported.
207207
|===
208208

209-
=== SYCL Graph Terminology
209+
=== SYCL Graph Terminology [[terminology]]
210210

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

777777
* Both graphs must have been created with the same device and context.
778778
* Both graphs must be topologically identical. The graphs are considered
779-
topologically identical when:
780-
781-
** Both graphs have the same number of nodes and edges.
782-
** Where edges are specified through the `depends_on` property or through event
783-
dependencies in recorded queue submisions, these must be specified in the same
784-
order.
785-
** Nodes with dependencies on events outside of the graph must have the same
786-
number of these dependencies.
787-
** A kernel node's command function must have the same type in both graphs,
788-
whether that be a lambda function, function object or otherwise.
789-
** When creating both graphs all graph-related API calls or operations which
790-
modify the structure of the graph must have been done in the same order, these
791-
are:
792-
793-
*** Explicit API calls to add nodes to the graph or calls to `make_edge()`.
794-
*** Nodes added to a graph via recorded queue submissions.
779+
topologically identical when:
780+
781+
** Both graphs must have the same number of nodes and edges.
782+
** Internal edges must be between corresponding nodes in each graph.
783+
** Nodes must be added in the same order in the two graphs. Nodes may be added
784+
via `command_graph::add`, or for a recorded queue via `queue::submit` or
785+
queue shortcut functions.
786+
** Corresponding nodes in each graph must be kernels that have the same type:
787+
788+
*** When the kernel is defined as a lambda, the lambda must be the same.
789+
*** When the kernel is defined as a named function object, the kernel class
790+
must be the same.
791+
*** When the kernel is defined as a plain function, the function must be the
792+
same.
793+
794+
** Edge dependencies for each node in the two graphs must be created in the
795+
same order and using the same API invocation to create each edge. See
796+
the <<terminology, terminology section>> for an exhaustive definition of
797+
how edges are defined in a graph for each of the two graph construction
798+
APIs.
795799

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

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

805-
:sycl-kernel-function: https://registry.khronos.org/SYCL/specs/sycl-2020/html/sycl-2020.html#sycl-kernel-function
806-
807810
==== Graph Properties [[graph-properties]]
808811

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

12301233
It is not an error to update an executable graph such that all parameters of
1231-
nodes in `graph` are identical to the arguments of the executable graph prior to
1234+
nodes in `source` are identical to the arguments of the executable graph prior to
12321235
the update.
12331236

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

12491252
Exceptions:
12501253

1251-
* Throws synchronously with error code `invalid` if the topology of
1252-
`source` is not the same as the target graph topology in the following ways:
1253-
1254-
** The number of nodes in the graph does not match.
1255-
** The number of edges between nodes does not match.
1256-
** Any node in `source` has a dependency which does not matched the paired node
1257-
in the target graph.
1258-
12591254
* Throws synchronously with error code `invalid` if `source` contains any node
1260-
which is not of the following `node_type`s:
1255+
which is not one of the following types:
12611256

1262-
** `node_type::empty`
1257+
** `node_type::empty`
12631258
** `node_type::ext_oneapi_barrier`
12641259
** `node_type::kernel`
12651260

1266-
12671261
* Throws synchronously with error code `invalid` if the context or device
12681262
associated with `source` does not match that of the `command_graph` being
12691263
updated.

0 commit comments

Comments
 (0)