[llvm] [libsycl] Add sycl::queue stub (PR #184110)
Kseniya Tikhomirova via llvm-commits
llvm-commits at lists.llvm.org
Mon Mar 2 04:30:29 PST 2026
https://github.com/KseniyaTikhomirova created https://github.com/llvm/llvm-project/pull/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
>From 424934727409740bd6acd09837a4383efb6ae7db Mon Sep 17 00:00:00 2001
From: "Tikhomirova, Kseniya" <kseniya.tikhomirova at intel.com>
Date: Fri, 27 Feb 2026 10:21:46 -0800
Subject: [PATCH] [libsycl] Add sycl::queue stub
Signed-off-by: Tikhomirova, Kseniya <kseniya.tikhomirova at intel.com>
---
libsycl/docs/index.rst | 2 +
libsycl/include/sycl/__impl/async_handler.hpp | 33 ++++
.../__impl/detail/default_async_handler.hpp | 55 ++++++
libsycl/include/sycl/__impl/property_list.hpp | 33 ++++
libsycl/include/sycl/__impl/queue.hpp | 159 ++++++++++++++++++
libsycl/include/sycl/sycl.hpp | 1 +
libsycl/src/CMakeLists.txt | 2 +
libsycl/src/detail/queue_impl.cpp | 25 +++
libsycl/src/detail/queue_impl.hpp | 83 +++++++++
libsycl/src/queue.cpp | 36 ++++
10 files changed, 429 insertions(+)
create mode 100644 libsycl/include/sycl/__impl/async_handler.hpp
create mode 100644 libsycl/include/sycl/__impl/detail/default_async_handler.hpp
create mode 100644 libsycl/include/sycl/__impl/property_list.hpp
create mode 100644 libsycl/include/sycl/__impl/queue.hpp
create mode 100644 libsycl/src/detail/queue_impl.cpp
create mode 100644 libsycl/src/detail/queue_impl.hpp
create mode 100644 libsycl/src/queue.cpp
diff --git a/libsycl/docs/index.rst b/libsycl/docs/index.rst
index 01bfb19b3d432..7a0d1aa406f61 100644
--- a/libsycl/docs/index.rst
+++ b/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 to existing SYCL runtime classes supporting it
diff --git a/libsycl/include/sycl/__impl/async_handler.hpp b/libsycl/include/sycl/__impl/async_handler.hpp
new file mode 100644
index 0000000000000..e6550d75e9437
--- /dev/null
+++ b/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
diff --git a/libsycl/include/sycl/__impl/detail/default_async_handler.hpp b/libsycl/include/sycl/__impl/detail/default_async_handler.hpp
new file mode 100644
index 0000000000000..977a1dfa0c0a9
--- /dev/null
+++ b/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 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
diff --git a/libsycl/include/sycl/__impl/property_list.hpp b/libsycl/include/sycl/__impl/property_list.hpp
new file mode 100644
index 0000000000000..a21c366d09bbc
--- /dev/null
+++ b/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 exact object the property_list 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
diff --git a/libsycl/include/sycl/__impl/queue.hpp b/libsycl/include/sycl/__impl/queue.hpp
new file mode 100644
index 0000000000000..e475e83ec0a04
--- /dev/null
+++ b/libsycl/include/sycl/__impl/queue.hpp
@@ -0,0 +1,159 @@
+//===----------------------------------------------------------------------===//
+//
+// 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/detail/config.hpp>
+#include <sycl/__impl/detail/default_async_handler.hpp>
+#include <sycl/__impl/detail/obj_utils.hpp>
+
+#include <sycl/__impl/async_handler.hpp>
+#include <sycl/__impl/device.hpp>
+#include <sycl/__impl/property_list.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 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 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 = {});
+
+ /// Returns the SYCL backend that is associated with this queue.
+ ///
+ /// \return the backend associated with this queue.
+ backend get_backend() const noexcept;
+
+ /// Returns context that is associated with this queue.
+ ///
+ /// \return an associated SYCL context.
+ context get_context() const;
+
+ /// Returns device that is associated with this queue.
+ ///
+ /// \return SYCL device this queue was constructed with.
+ device get_device() const;
+
+ /// Returns whether the queue is in order or out of order.
+ ///
+ /// Equivalent to has_property<property::queue::in_order>().
+ ///
+ /// \return true if queue is in order.
+ bool is_in_order() const;
+
+ /// Queries SYCL queue for information.
+ ///
+ /// The return type depends on information being queried.
+ template <typename Param> typename Param::return_type get_info() const;
+
+ /// Queries SYCL queue for SYCL backend-specific information.
+ ///
+ /// The return type depends on 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
diff --git a/libsycl/include/sycl/sycl.hpp b/libsycl/include/sycl/sycl.hpp
index 5823f29268567..e1bd55e361561 100644
--- a/libsycl/include/sycl/sycl.hpp
+++ b/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
diff --git a/libsycl/src/CMakeLists.txt b/libsycl/src/CMakeLists.txt
index fa3bf81e17d2a..1e4e4178bd66d 100644
--- a/libsycl/src/CMakeLists.txt
+++ b/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"
)
diff --git a/libsycl/src/detail/queue_impl.cpp b/libsycl/src/detail/queue_impl.cpp
new file mode 100644
index 0000000000000..dec2d7d5507aa
--- /dev/null
+++ b/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
diff --git a/libsycl/src/detail/queue_impl.hpp b/libsycl/src/detail/queue_impl.hpp
new file mode 100644
index 0000000000000..81c327fcd03cc
--- /dev/null
+++ b/libsycl/src/detail/queue_impl.hpp
@@ -0,0 +1,83 @@
+//===----------------------------------------------------------------------===//
+//
+// 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
+ /// propList provided.
+ ///
+ /// \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 a provided arguments. Variadic helper.
+ /// Restrics ways of QueueImpl creation.
+ template <typename... Ts>
+ static std::shared_ptr<QueueImpl> create(Ts &&...args) {
+ return std::make_shared<QueueImpl>(std::forward<Ts>(args)..., PrivateTag{});
+ }
+
+ /// Returns backend this queue is associated with.
+ ///
+ /// \return SYCL backend.
+ backend getBackend() const noexcept;
+
+ /// Returns context this queue is associated with.
+ ///
+ /// \return context implementation object.
+ ContextImpl &getContext() { return MContext; }
+
+ /// Returns device this queue is associated with.
+ ///
+ /// \return device implementation object.
+ DeviceImpl &getDevice() { return MDevice; }
+
+ /// Returns whether the queue is in order or out of order.
+ ///
+ /// \return true if queue is in order.
+ bool isInOrder() const { return MIsInorder; }
+
+private:
+ // ol_queue_handle_t MOffloadQueue = {};
+ 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
diff --git a/libsycl/src/queue.cpp b/libsycl/src/queue.cpp
new file mode 100644
index 0000000000000..faed274674447
--- /dev/null
+++ b/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
More information about the llvm-commits
mailing list