[SYCL][COMPAT] Added wait and throw free function. Minor fixes in documentation. (#13029)

This PR is mostly cleanup:
- adds a free function to call to wrap queue wait and throw, which was
in the documentation but not implemented.
- It reduces testing coupling by including the relevant headers.
- Adds a missing header in launch.cpp, which was detected when fixing
the testing header includes.
- Fixes a lot of function definitions in the documentation which didn't
match the actual definition in the library.

Author: Alcpz

sycl/doc/syclcompat/README.md

@@ -82,9 +82,9 @@ namespace syclcompat {
 class dim3 {
 public:
   const size_t x, y, z;
-  constexpr dim3(const sycl::range<3> &r);
-  constexpr dim3(const sycl::range<2> &r);
-  constexpr dim3(const sycl::range<1> &r);
+  dim3(const sycl::range<3> &r);
+  dim3(const sycl::range<2> &r);
+  dim3(const sycl::range<1> &r);
   constexpr dim3(size_t x, size_t y = 1, size_t z = 1);
 
   constexpr size_t size();
@@ -95,9 +95,9 @@ public:
 };
 
 // Element-wise operators
-dim3 operator*(const dim3 &a, const dim3 &b);
-dim3 operator+(const dim3 &a, const dim3 &b);
-dim3 operator-(const dim3 &a, const dim3 &b);
+inline dim3 operator*(const dim3 &a, const dim3 &b);
+inline dim3 operator+(const dim3 &a, const dim3 &b);
+inline dim3 operator-(const dim3 &a, const dim3 &b);
 
 } // syclcompat
 ```
@@ -113,39 +113,39 @@ addition to the global range, the following helper functions are also provided:
 namespace syclcompat {
 
 namespace local_id {
-size_t x();
-size_t y();
-size_t z();
+inline size_t x();
+inline size_t y();
+inline size_t z();
 } // namespace local_id
 
 namespace local_range {
-size_t x();
-size_t y();
-size_t z();
+inline size_t x();
+inline size_t y();
+inline size_t z();
 } // namespace local_range
 
 namespace work_group_id {
-size_t x();
-size_t y();
-size_t z();
+inline size_t x();
+inline size_t y();
+inline size_t z();
 } // namespace work_group_id
 
 namespace work_group_range {
-size_t x();
-size_t y();
-size_t z();
+inline size_t x();
+inline size_t y();
+inline size_t z();
 } // namespace work_group_range
 
 namespace global_range {
-size_t x();
-size_t y();
-size_t z();
+inline size_t x();
+inline size_t y();
+inline size_t z();
 } // namespace global_range
 
 namespace global_id {
-size_t x();
-size_t y();
-size_t z();
+inline size_t x();
+inline size_t y();
+inline size_t z();
 } // namespace global_id
 
 } // syclcompat
@@ -308,12 +308,13 @@ group size in each dimension.
 ```c++
 namespace syclcompat {
 
-void wg_barrier();
+inline void wg_barrier();
 
 template <int Dim>
-sycl::nd_range<Dim> compute_nd_range(sycl::range<Dim> global_size_in,
-                                     sycl::range<Dim> work_group_size);
-sycl::nd_range<1> compute_nd_range(int global_size_in, int work_group_size);
+inline sycl::nd_range<Dim> compute_nd_range(sycl::range<Dim> global_size_in,
+                                            sycl::range<Dim> work_group_size);
+inline sycl::nd_range<1> compute_nd_range(int global_size_in, 
+                                          int work_group_size);
 
 } // syclcompat
 ```
@@ -330,8 +331,8 @@ out-of-order queue, either created manually or retrieved via a call to
 ```c++
 namespace syclcompat {
 
-sycl::queue create_queue(bool print_on_async_exceptions = false,
-                         bool in_order = true);
+inline sycl::queue create_queue(bool print_on_async_exceptions = false,
+                                bool in_order = true);
 
 } // syclcompat
 ```
@@ -739,46 +740,46 @@ follows:
 namespace syclcompat {
 
 // Util function to create a new queue for the current device
-sycl::queue create_queue(bool print_on_async_exceptions = false,
-                         bool in_order = true);
+static inline sycl::queue create_queue(bool print_on_async_exceptions = false,
+                                       bool in_order = true);
 
 // Util function to get the default queue of current device in
 // device manager.
-sycl::queue get_default_queue();
+static inline sycl::queue get_default_queue();
 
 // Util function to set the default queue of the current device in the
 // device manager.
 // If the device extension saved queue is the default queue, 
 // the previous saved queue will be overwritten as well.
 // This function will be blocking if there are submitted kernels in the
 // previous default queue.
-void set_default_queue(const sycl::queue &q);
+static inline void set_default_queue(const sycl::queue &q);
 
 // Util function to wait for the queued kernels.
-void wait(sycl::queue q = get_default_queue());
+static inline void wait(sycl::queue q = get_default_queue());
 
 // Util function to wait for the queued kernels and throw unhandled errors.
-void wait_and_throw(sycl::queue q = get_default_queue());
+static inline void wait_and_throw(sycl::queue q = get_default_queue());
 
 // Util function to get the id of current device in
 // device manager.
-unsigned int get_current_device_id();
+static inline unsigned int get_current_device_id();
 
 // Util function to get the current device.
-device_ext &get_current_device();
+static inline device_ext &get_current_device();
 
 // Util function to get a device by id.
-device_ext &get_device(unsigned int id);
+static inline device_ext &get_device(unsigned int id);
 
 // Util function to get the context of the default queue of current
 // device in device manager.
-sycl::context get_default_context();
+static inline sycl::context get_default_context();
 
 // Util function to get a CPU device.
-device_ext &cpu_device();
+static inline device_ext &cpu_device();
 
 // Util function to select a device by its id
-unsigned int select_device(unsigned int id);
+static inline unsigned int select_device(unsigned int id);
 
 } // syclcompat
 ```

sycl/include/syclcompat/device.hpp

@@ -45,7 +45,9 @@
 #include <unistd.h>
 #endif
 #if defined(_WIN64)
+#ifndef NOMINMAX
 #define NOMINMAX
+#endif
 #include <windows.h>
 #endif
 
@@ -56,11 +58,10 @@
 
 namespace syclcompat {
 
-// Note: this is all code from SYCLomatic's device.hpp helper header
 namespace detail {
 
 /// SYCL default exception handler
-auto exception_handler = [](sycl::exception_list exceptions) {
+inline auto exception_handler = [](sycl::exception_list exceptions) {
   for (std::exception_ptr const &e : exceptions) {
     try {
       std::rethrow_exception(e);
@@ -514,8 +515,8 @@ class dev_mgr {
 
 } // namespace detail
 
-inline sycl::queue create_queue(bool print_on_async_exceptions = false,
-                                bool in_order = true) {
+static inline sycl::queue create_queue(bool print_on_async_exceptions = false,
+                                       bool in_order = true) {
   return *detail::dev_mgr::instance().current_device().create_queue(
       print_on_async_exceptions, in_order);
 }
@@ -537,7 +538,11 @@ static inline void set_default_queue(const sycl::queue &q) {
   detail::dev_mgr::instance().current_device().set_default_queue(q);
 }
 
-inline void wait(sycl::queue q = get_default_queue()) { q.wait(); }
+static inline void wait(sycl::queue q = get_default_queue()) { q.wait(); }
+
+static inline void wait_and_throw(sycl::queue q = get_default_queue()) {
+  q.wait_and_throw();
+}
 
 /// Util function to get the id of current device in
 /// device manager.

sycl/include/syclcompat/launch.hpp

@@ -90,8 +90,8 @@ sycl::event launch(const sycl::nd_range<3> &range, size_t mem_size,
 } // namespace detail
 
 template <int Dim>
-sycl::nd_range<Dim> compute_nd_range(sycl::range<Dim> global_size_in,
-                                     sycl::range<Dim> work_group_size) {
+inline sycl::nd_range<Dim> compute_nd_range(sycl::range<Dim> global_size_in,
+                                            sycl::range<Dim> work_group_size) {
 
   if (global_size_in.size() == 0 || work_group_size.size() == 0) {
     throw std::invalid_argument("Global or local size is zero!");

sycl/test-e2e/syclcompat/id_query/id_query_fixt.hpp

@@ -23,7 +23,10 @@
 #pragma once
 
 #include <sycl/sycl.hpp>
-#include <syclcompat.hpp>
+
+#include <syclcompat/id_query.hpp>
+#include <syclcompat/launch.hpp>
+#include <syclcompat/memory.hpp>
 
 // Class to launch a kernel and run a lambda on output data
 template <auto F> class QueryLauncher {

sycl/test-e2e/syclcompat/launch/launch.cpp

@@ -23,11 +23,13 @@
 // RUN: %clangxx -std=c++20 -fsycl -fsycl-device-code-split=per_kernel -fsycl-targets=%{sycl_triple} %s -o %t.out
 // RUN: %{run} %t.out
 
+#include <type_traits>
+
 #include <sycl/sycl.hpp>
+
 #include <syclcompat/device.hpp>
 #include <syclcompat/launch.hpp>
-
-#include <type_traits>
+#include <syclcompat/memory.hpp>
 
 #include "../common.hpp"
 #include "launch_fixt.hpp"

sycl/test-e2e/syclcompat/launch/launch_fixt.hpp

@@ -23,7 +23,9 @@
 #pragma once
 
 #include <sycl/sycl.hpp>
-#include <syclcompat.hpp>
+
+#include <syclcompat/device.hpp>
+#include <syclcompat/dims.hpp>
 
 // Struct containing test case data (local & global ranges)
 template <int Dim> struct RangeParams {