[libsycl] Add sycl::queue stub (#184110)

Part 2 of changes needed for USM alloc/dealloc impl.

This is part of the SYCL support upstreaming effort. The relevant RFCs
can be found here:


https://discourse.llvm.org/t/rfc-add-full-support-for-the-sycl-programming-model/74080
https://discourse.llvm.org/t/rfc-sycl-runtime-upstreaming/74479

---------

Signed-off-by: Tikhomirova, Kseniya <kseniya.tikhomirova@intel.com>

libsycl/docs/index.rst

@@ -106,3 +106,5 @@ TODO for added SYCL classes
 
 * device selection: to add compatibility with old SYCL 1.2.1 device selectors, still part of SYCL 2020 specification
 * ``context``: to implement get_info, properties & public constructors once context support is added to liboffload
+* ``queue``: to implement USM methods, to implement synchronization methods, to implement submit & copy with accessors (low priority), get_info & properties, ctors that accepts context (blocked by lack of liboffload support)
+* ``property_list``: to fully implement and integrate with existing SYCL runtime classes supporting it

libsycl/include/sycl/__impl/async_handler.hpp

@@ -0,0 +1,33 @@
+//===----------------------------------------------------------------------===//
+//
+// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+//
+//===----------------------------------------------------------------------===//
+///
+/// \file
+/// This file contains the declaration of the SYCL async_handler type, which
+/// is a callable, such as a function class or lambda, with an exception_list as
+/// a parameter. Invocation of an async_handler may be triggered by the queue
+/// member functions queue::wait_and_throw or queue::throw_asynchronous, by the
+/// event member function event::wait_and_throw, or automatically on destruction
+/// of a queue or context that contains unconsumed asynchronous errors.
+///
+//===----------------------------------------------------------------------===//
+
+#ifndef _LIBSYCL___IMPL_ASYNC_HANDLER_HPP
+#define _LIBSYCL___IMPL_ASYNC_HANDLER_HPP
+
+#include <functional>
+
+_LIBSYCL_BEGIN_NAMESPACE_SYCL
+
+class exception_list;
+
+// SYCL 2020 4.13.2. Exception class interface.
+using async_handler = std::function<void(sycl::exception_list)>;
+
+_LIBSYCL_END_NAMESPACE_SYCL
+
+#endif // _LIBSYCL___IMPL_ASYNC_HANDLER_HPP

libsycl/include/sycl/__impl/detail/default_async_handler.hpp

@@ -0,0 +1,55 @@
+//===----------------------------------------------------------------------===//
+//
+// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+//
+//===----------------------------------------------------------------------===//
+///
+/// \file
+/// This file contains the definition of an implementation-defined default
+/// async_handler, which is invoked when an asynchronous error occurs in a queue
+/// or context that has no user-supplied asynchronous error handler object (see
+/// SYCL 2020 4.13.1.2).
+///
+//===----------------------------------------------------------------------===//
+
+#ifndef _LIBSYCL___IMPL_DETAIL_DEFAULT_ASYNC_HANDLER_HPP
+#define _LIBSYCL___IMPL_DETAIL_DEFAULT_ASYNC_HANDLER_HPP
+
+#include <sycl/__impl/exception.hpp>
+
+#include <iostream>
+
+_LIBSYCL_BEGIN_NAMESPACE_SYCL
+
+namespace detail {
+
+// SYCL 2020 4.13.1.2. Behavior without an async handler.
+// If an asynchronous error occurs in a queue or context that has no
+// user-supplied asynchronous error handler object async_handler, then an
+// implementation-defined default async_handler is called to handle the error in
+// the same situations that a user-supplied async_handler would be. The default
+// async_handler must in some way report all errors passed to it, when possible,
+// and must then invoke std::terminate or equivalent.
+inline void defaultAsyncHandler(exception_list ExceptionList) {
+  std::cerr
+      << "Implementation-defined default async_handler caught exceptions:";
+  for (auto &Exception : ExceptionList) {
+    try {
+      if (Exception) {
+        std::rethrow_exception(Exception);
+      }
+    } catch (const std::exception &E) {
+      std::cerr << "\n\t" << E.what();
+    }
+  }
+  std::cerr << std::endl;
+  std::terminate();
+}
+
+} // namespace detail
+
+_LIBSYCL_END_NAMESPACE_SYCL
+
+#endif // _LIBSYCL___IMPL_DETAIL_DEFAULT_ASYNC_HANDLER_HPP

libsycl/include/sycl/__impl/property_list.hpp

@@ -0,0 +1,33 @@
+//===----------------------------------------------------------------------===//
+//
+// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+//
+//===----------------------------------------------------------------------===//
+///
+/// \file
+/// This file contains the declaration of the SYCL property_list type, which
+/// contains zero or more properties and is used as an optional parameter in
+/// SYCL runtime classes constructors. Each of those properties augments the
+/// semantics of the class with a particular feature.
+///
+//===----------------------------------------------------------------------===//
+
+#ifndef _LIBSYCL___IMPL_PROPERTY_LIST_HPP
+#define _LIBSYCL___IMPL_PROPERTY_LIST_HPP
+
+_LIBSYCL_BEGIN_NAMESPACE_SYCL
+
+/// Collection of properties for SYCL objects. Supported properties are defined
+/// by the exact object the property_list is passed to.
+// TODO: This is just a placeholder for initial stage.
+class property_list {
+public:
+  template <typename... Properties>
+  property_list([[maybe_unused]] Properties... props) {}
+};
+
+_LIBSYCL_END_NAMESPACE_SYCL
+
+#endif // _LIBSYCL___IMPL_PROPERTY_LIST_HPP

libsycl/include/sycl/__impl/queue.hpp

@@ -0,0 +1,151 @@
+//===----------------------------------------------------------------------===//
+//
+// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+//
+//===----------------------------------------------------------------------===//
+///
+/// \file
+/// This file contains the declaration of the SYCL queue class, which
+/// schedules kernels on a device.
+///
+//===----------------------------------------------------------------------===//
+
+#ifndef _LIBSYCL___IMPL_QUEUE_HPP
+#define _LIBSYCL___IMPL_QUEUE_HPP
+
+#include <sycl/__impl/async_handler.hpp>
+#include <sycl/__impl/device.hpp>
+#include <sycl/__impl/property_list.hpp>
+
+#include <sycl/__impl/detail/config.hpp>
+#include <sycl/__impl/detail/default_async_handler.hpp>
+#include <sycl/__impl/detail/obj_utils.hpp>
+
+_LIBSYCL_BEGIN_NAMESPACE_SYCL
+
+class context;
+
+namespace detail {
+class QueueImpl;
+} // namespace detail
+
+// SYCL 2020 4.6.5. Queue class.
+class _LIBSYCL_EXPORT queue {
+public:
+  queue(const queue &rhs) = default;
+
+  queue(queue &&rhs) = default;
+
+  queue &operator=(const queue &rhs) = default;
+
+  queue &operator=(queue &&rhs) = default;
+
+  friend bool operator==(const queue &lhs, const queue &rhs) {
+    return lhs.impl == rhs.impl;
+  }
+
+  friend bool operator!=(const queue &lhs, const queue &rhs) {
+    return !(lhs == rhs);
+  }
+
+  /// Constructs a SYCL queue instance using the device returned by an instance
+  /// of default_selector.
+  ///
+  /// \param propList is a list of properties for queue construction.
+  explicit queue(const property_list &propList = {})
+      : queue(detail::SelectDevice(default_selector_v),
+              detail::defaultAsyncHandler, propList) {}
+
+  /// Constructs a SYCL queue instance with an async_handler using the device
+  /// returned by an instance of default_selector.
+  ///
+  /// \param asyncHandler is a SYCL asynchronous exception handler.
+  /// \param propList is a list of properties for queue construction.
+  explicit queue(const async_handler &asyncHandler,
+                 const property_list &propList = {})
+      : queue(detail::SelectDevice(default_selector_v), asyncHandler,
+              propList) {}
+
+  /// Constructs a SYCL queue instance using the device identified by the
+  /// device selector provided.
+  /// \param deviceSelector is a SYCL 2020 Device Selector, a simple callable
+  /// that takes a device and returns an int
+  /// \param propList is a list of properties for queue construction.
+  template <
+      typename DeviceSelector,
+      typename = detail::EnableIfDeviceSelectorIsInvocable<DeviceSelector>>
+  explicit queue(const DeviceSelector &deviceSelector,
+                 const property_list &propList = {})
+      : queue(detail::SelectDevice(deviceSelector), detail::defaultAsyncHandler,
+              propList) {}
+
+  /// Constructs a SYCL queue instance using the device identified by the
+  /// device selector provided.
+  /// \param deviceSelector is a SYCL 2020 Device Selector, a simple callable
+  /// that takes a device and returns an int
+  /// \param asyncHandler is a SYCL asynchronous exception handler.
+  /// \param propList is a list of properties for queue construction.
+  template <
+      typename DeviceSelector,
+      typename = detail::EnableIfDeviceSelectorIsInvocable<DeviceSelector>>
+  explicit queue(const DeviceSelector &deviceSelector,
+                 const async_handler &asyncHandler,
+                 const property_list &propList = {})
+      : queue(detail::SelectDevice(deviceSelector), asyncHandler, propList) {}
+
+  /// Constructs a SYCL queue instance using the device provided.
+  ///
+  /// \param syclDevice is an instance of SYCL device.
+  /// \param propList is a list of properties for queue construction.
+  explicit queue(const device &syclDevice, const property_list &propList = {})
+      : queue(syclDevice, detail::defaultAsyncHandler, propList) {}
+
+  /// Constructs a SYCL queue instance with an async_handler using the device
+  /// provided.
+  ///
+  /// \param syclDevice is an instance of SYCL device.
+  /// \param asyncHandler is a SYCL asynchronous exception handler.
+  /// \param propList is a list of properties for queue construction.
+  explicit queue(const device &syclDevice, const async_handler &asyncHandler,
+                 const property_list &propList = {});
+
+  /// \return the SYCL backend associated with this queue.
+  backend get_backend() const noexcept;
+
+  /// \return the associated SYCL context.
+  context get_context() const;
+
+  /// \return the SYCL device this queue was constructed with.
+  device get_device() const;
+
+  /// Equivalent to has_property<property::queue::in_order>().
+  ///
+  /// \return true if and only if the queue is in order.
+  bool is_in_order() const;
+
+  /// Queries the queue for information.
+  ///
+  /// The return type depends on information being queried.
+  template <typename Param> typename Param::return_type get_info() const;
+
+  /// Queries the queue for SYCL backend-specific information.
+  ///
+  /// The return type depends on the information being queried.
+  template <typename Param>
+  typename Param::return_type get_backend_info() const;
+
+private:
+  queue(const std::shared_ptr<detail::QueueImpl> &Impl) : impl(Impl) {}
+  std::shared_ptr<detail::QueueImpl> impl;
+
+  friend sycl::detail::ImplUtils;
+}; // class queue
+
+_LIBSYCL_END_NAMESPACE_SYCL
+
+template <>
+struct std::hash<sycl::queue> : public sycl::detail::HashBase<sycl::queue> {};
+
+#endif // _LIBSYCL___IMPL_QUEUE_HPP

libsycl/include/sycl/sycl.hpp

@@ -19,5 +19,6 @@
 #include <sycl/__impl/device_selector.hpp>
 #include <sycl/__impl/exception.hpp>
 #include <sycl/__impl/platform.hpp>
+#include <sycl/__impl/queue.hpp>
 
 #endif // _LIBSYCL_SYCL_HPP

libsycl/src/CMakeLists.txt

@@ -87,10 +87,12 @@ set(LIBSYCL_SOURCES
     "device.cpp"
     "device_selector.cpp"
     "platform.cpp"
+    "queue.cpp"
     "detail/context_impl.cpp"
     "detail/device_impl.cpp"
     "detail/global_objects.cpp"
     "detail/platform_impl.cpp"
+    "detail/queue_impl.cpp"
     "detail/offload/offload_utils.cpp"
     "detail/offload/offload_topology.cpp"
 )

libsycl/src/detail/queue_impl.cpp

@@ -0,0 +1,25 @@
+//===----------------------------------------------------------------------===//
+//
+// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+//
+//===----------------------------------------------------------------------===//
+
+#include <detail/device_impl.hpp>
+#include <detail/queue_impl.hpp>
+
+_LIBSYCL_BEGIN_NAMESPACE_SYCL
+
+namespace detail {
+
+QueueImpl::QueueImpl(DeviceImpl &deviceImpl, const async_handler &asyncHandler,
+                     const property_list &propList, PrivateTag)
+    : MIsInorder(false), MAsyncHandler(asyncHandler), MPropList(propList),
+      MDevice(deviceImpl),
+      MContext(MDevice.getPlatformImpl().getDefaultContext()) {}
+
+backend QueueImpl::getBackend() const noexcept { return MDevice.getBackend(); }
+
+} // namespace detail
+_LIBSYCL_END_NAMESPACE_SYCL

libsycl/src/detail/queue_impl.hpp

@@ -0,0 +1,74 @@
+//===----------------------------------------------------------------------===//
+//
+// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+//
+//===----------------------------------------------------------------------===//
+
+#ifndef _LIBSYCL_QUEUE_IMPL
+#define _LIBSYCL_QUEUE_IMPL
+
+#include <sycl/__impl/detail/config.hpp>
+#include <sycl/__impl/queue.hpp>
+
+#include <OffloadAPI.h>
+
+#include <memory>
+
+_LIBSYCL_BEGIN_NAMESPACE_SYCL
+namespace detail {
+
+class ContextImpl;
+class DeviceImpl;
+
+class QueueImpl : public std::enable_shared_from_this<QueueImpl> {
+  struct PrivateTag {
+    explicit PrivateTag() = default;
+  };
+
+public:
+  ~QueueImpl() = default;
+
+  /// Constructs a SYCL queue from a device using an asyncHandler and
+  /// a propList.
+  ///
+  /// \param deviceImpl is a SYCL device that is used to dispatch tasks
+  /// submitted to the queue.
+  /// \param asyncHandler is a SYCL asynchronous exception handler.
+  /// \param propList is a list of properties to use for queue construction.
+  explicit QueueImpl(DeviceImpl &deviceImpl, const async_handler &asyncHandler,
+                     const property_list &propList, PrivateTag);
+
+  /// Constructs a QueueImpl with the provided arguments. Variadic helper.
+  /// Restricts QueueImpl creation to std::shared_ptr allocations.
+  template <typename... Ts>
+  static std::shared_ptr<QueueImpl> create(Ts &&...args) {
+    return std::make_shared<QueueImpl>(std::forward<Ts>(args)..., PrivateTag{});
+  }
+
+  /// \return the SYCL backend this queue is associated with.
+  backend getBackend() const noexcept;
+
+  /// \return the context implementation object this queue is associated with.
+  ContextImpl &getContext() { return MContext; }
+
+  /// \return the device implementation object this queue is associated with.
+  DeviceImpl &getDevice() { return MDevice; }
+
+  /// \return true if and only if the queue is in order.
+  bool isInOrder() const { return MIsInorder; }
+
+private:
+  const bool MIsInorder;
+  const async_handler MAsyncHandler;
+  const property_list MPropList;
+  DeviceImpl &MDevice;
+  ContextImpl &MContext;
+};
+
+} // namespace detail
+
+_LIBSYCL_END_NAMESPACE_SYCL
+
+#endif // _LIBSYCL_QUEUE_IMPL

libsycl/src/queue.cpp

@@ -0,0 +1,36 @@
+//===----------------------------------------------------------------------===//
+//
+// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+//
+//===----------------------------------------------------------------------===//
+
+#include <sycl/__impl/context.hpp>
+#include <sycl/__impl/queue.hpp>
+
+#include <detail/context_impl.hpp>
+#include <detail/device_impl.hpp>
+#include <detail/queue_impl.hpp>
+
+_LIBSYCL_BEGIN_NAMESPACE_SYCL
+
+queue::queue(const device &syclDevice, const async_handler &asyncHandler,
+             const property_list &propList) {
+  impl = detail::QueueImpl::create(*detail::getSyclObjImpl(syclDevice),
+                                   asyncHandler, propList);
+}
+
+backend queue::get_backend() const noexcept { return impl->getBackend(); }
+
+context queue::get_context() const {
+  return detail::createSyclObjFromImpl<context>(impl->getContext());
+}
+
+device queue::get_device() const {
+  return detail::createSyclObjFromImpl<device>(impl->getDevice());
+}
+
+bool queue::is_in_order() const { return impl->isInOrder(); }
+
+_LIBSYCL_END_NAMESPACE_SYCL