[SYCL][Graph] Add node and graph queries for mixed usage (#12366)

This PR adds queries to both nodes and modifiable graphs which enable
better mixed usage of both the explicit and record & replay APIs in a
single program.

It also reworks how subgraphs are handled: previously nodes were merged
into the modifiable graph, but this would pose a problem for users
querying the graph since they would not see a single subgraph node, and
this merging behaviour was an implementation detail. This has been
changed so that now subgraph nodes are only merged in the executable
graph, and are stored as a single node of type `subgraph` in the
modifiable graph.

As a consequence of this change all nodes are now also copied when
making the executable graph, where previously they were not.

- Reworked how subgraphs are handled
- Add graph and node queries to the SYCL-Graph spec
- Implement graph and node queries
- New node_type enum
- Explicit nodes now also have associated events (fixes mixed usage
issue)
- New tests for queries
- Update ABI symbols

Author: Bensuo

sycl/doc/extensions/experimental/sycl_ext_oneapi_graph.asciidoc

@@ -315,6 +315,19 @@ enum class graph_support_level {
   emulated
 };
 
+enum class node_type {
+  empty,
+  subgraph,
+  kernel,
+  memcpy,
+  memset,
+  memfill,
+  prefetch,
+  memadvise,
+  ext_oneapi_barrier,
+  host_task,
+};
+
 namespace property {
 
 namespace graph {
@@ -355,7 +368,18 @@ struct graphs_support;
 } // namespace device
 } // namespace info
 
-class node {};
+class node {
+public:
+  node() = delete;
+
+  node_type get_type() const;
+
+  std::vector<node> get_predecessors() const;
+
+  std::vector<node> get_successors() const;
+
+  static node get_node_from_event(event nodeEvent);
+};
 
 // State of a graph
 enum class graph_state {
@@ -394,6 +418,9 @@ public:
   void make_edge(node& src, node& dest);
 
   void print_graph(std::string path, bool verbose = false) const;
+
+  std::vector<node> get_nodes() const;
+  std::vector<node> get_root_nodes() const;
 };
 
 template<>
@@ -467,12 +494,56 @@ edges.
 
 The `node` class provides the {crs}[common reference semantics].
 
+==== Node Member Functions
+
+Table {counter: tableNumber}. Member functions of the `node` class.
+[cols="2a,a"]
+|===
+|Member Function|Description
+
+|
 [source,c++]
 ----
-namespace sycl::ext::oneapi::experimental {
-  class node {};
-}
+node_type get_type() const;
+----
+|Returns a value representing the type of command this node represents.
+
+|
+[source,c++]
+----
+std::vector<node> get_predecessors() const;
+----
+|Returns a list of the predecessor nodes which this node directly depends on.
+
+|
+[source,c++]
+----
+std::vector<node> get_successors() const;
 ----
+|Returns a list of the successor nodes which directly depend on this node.
+
+|
+[source,c++]
+----
+static node get_node_from_event(event nodeEvent);
+----
+|Finds the node associated with an event created from a submission to a queue
+ in the recording state.
+
+Parameters:
+
+* `nodeEvent` - Event returned from a submission to a queue in the recording
+  state.
+
+Returns: Graph node that was created when the command that returned
+`nodeEvent` was submitted.
+
+Exceptions:
+
+* Throws with error code `invalid` if `nodeEvent` is not associated with a
+  graph node.
+
+|===
 
 ==== Depends-On Property
 
@@ -809,6 +880,21 @@ Exceptions:
 * Throws synchronously with error code `invalid` if the path is invalid or
 the file extension is not supported or if the write operation failed.
 
+|
+[source,c++]
+----
+std::vector<node> get_nodes() const;
+----
+|Returns a list of all the nodes present in the graph in the order that they
+were added.
+
+|
+[source,c++]
+----
+std::vector<node> get_root_nodes() const;
+----
+|Returns a list of all nodes in the graph which have no dependencies.
+
 |===
 
 Table {counter: tableNumber}. Member functions of the `command_graph` class for queue recording.

sycl/include/sycl/detail/cg.hpp

@@ -33,6 +33,10 @@ inline namespace _V1 {
 // Forward declarations
 class queue;
 
+namespace ext::oneapi::experimental::detail {
+class exec_graph_impl;
+}
+
 namespace detail {
 
 class event_impl;
@@ -573,11 +577,16 @@ class CGSemaphoreSignal : public CG {
 class CGExecCommandBuffer : public CG {
 public:
   sycl::detail::pi::PiExtCommandBuffer MCommandBuffer;
-
-  CGExecCommandBuffer(const sycl::detail::pi::PiExtCommandBuffer &CommandBuffer,
-                      CG::StorageInitHelper CGData)
+  std::shared_ptr<sycl::ext::oneapi::experimental::detail::exec_graph_impl>
+      MExecGraph;
+
+  CGExecCommandBuffer(
+      const sycl::detail::pi::PiExtCommandBuffer &CommandBuffer,
+      const std::shared_ptr<
+          sycl::ext::oneapi::experimental::detail::exec_graph_impl> &ExecGraph,
+      CG::StorageInitHelper CGData)
       : CG(CGTYPE::ExecCommandBuffer, std::move(CGData)),
-        MCommandBuffer(CommandBuffer) {}
+        MCommandBuffer(CommandBuffer), MExecGraph(ExecGraph) {}
 };
 
 } // namespace detail

sycl/include/sycl/ext/oneapi/experimental/graph.hpp

@@ -82,8 +82,37 @@ enum class graph_state {
   executable, ///< In executable state, the graph is ready to execute.
 };
 
+enum class node_type {
+  empty = 0,
+  subgraph = 1,
+  kernel = 2,
+  memcpy = 3,
+  memset = 4,
+  memfill = 5,
+  prefetch = 6,
+  memadvise = 7,
+  ext_oneapi_barrier = 8,
+  host_task = 9
+};
+
 /// Class representing a node in the graph, returned by command_graph::add().
 class __SYCL_EXPORT node {
+public:
+  node() = delete;
+
+  /// Get the type of command associated with this node.
+  node_type get_type() const;
+
+  /// Get a list of all the node dependencies of this node.
+  std::vector<node> get_predecessors() const;
+
+  /// Get a list of all nodes which depend on this node.
+  std::vector<node> get_successors() const;
+
+  /// Get the node associated with a SYCL event returned from a queue recording
+  /// submission.
+  static node get_node_from_event(event nodeEvent);
+
 private:
   node(const std::shared_ptr<detail::node_impl> &Impl) : impl(Impl) {}
 
@@ -259,6 +288,12 @@ class __SYCL_EXPORT modifiable_command_graph {
   /// as kernel args or memory access where applicable.
   void print_graph(const std::string path, bool verbose = false) const;
 
+  /// Get a list of all nodes contained in this graph.
+  std::vector<node> get_nodes() const;
+
+  /// Get a list of all root nodes (nodes without dependencies) in this graph.
+  std::vector<node> get_root_nodes() const;
+
 protected:
   /// Constructor used internally by the runtime.
   /// @param Impl Detail implementation class to construct object with.

sycl/include/sycl/handler.hpp

@@ -1777,6 +1777,14 @@ class __SYCL_EXPORT handler {
   std::shared_ptr<ext::oneapi::experimental::detail::graph_impl>
   getCommandGraph() const;
 
+  /// Sets the user facing node type of this operation, used for operations
+  /// which are recorded to a graph. Since some operations may actually be a
+  /// different type than the user submitted, e.g. a fill() which is performed
+  /// as a kernel submission.
+  /// @param Type The actual type based on what handler functions the user
+  /// called.
+  void setUserFacingNodeType(ext::oneapi::experimental::node_type Type);
+
 public:
   handler(const handler &) = delete;
   handler(handler &&) = delete;
@@ -2720,6 +2728,7 @@ class __SYCL_EXPORT handler {
       checkIfPlaceholderIsBoundToHandler(Dst);
 
     throwIfActionIsCreated();
+    setUserFacingNodeType(ext::oneapi::experimental::node_type::memfill);
     // TODO add check:T must be an integral scalar value or a SYCL vector type
     static_assert(isValidTargetForExplicitOp(AccessTarget),
                   "Invalid accessor target for the fill method.");
@@ -2758,6 +2767,7 @@ class __SYCL_EXPORT handler {
   /// \param Count is the number of times to fill Pattern into Ptr.
   template <typename T> void fill(void *Ptr, const T &Pattern, size_t Count) {
     throwIfActionIsCreated();
+    setUserFacingNodeType(ext::oneapi::experimental::node_type::memfill);
     static_assert(is_device_copyable<T>::value,
                   "Pattern must be device copyable");
     parallel_for<__usmfill<T>>(range<1>(Count), [=](id<1> Index) {