DPC++ Runtime
Runtime libraries for oneAPI DPC++
context.hpp
Go to the documentation of this file.
1 //==---------------- context.hpp - SYCL context ----------------------------==//
2 //
3 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
4 // See https://llvm.org/LICENSE.txt for license information.
5 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
6 //
7 //===----------------------------------------------------------------------===//
8 
9 #pragma once
10 
11 #include <sycl/async_handler.hpp> // for async_handler
12 #include <sycl/backend_types.hpp> // for backend, backend_return_t
13 #include <sycl/detail/defines_elementary.hpp> // for __SYCL2020_DEPRECATED
14 #include <sycl/detail/export.hpp> // for __SYCL_EXPORT
15 #include <sycl/detail/helpers.hpp> // for context_impl
16 #include <sycl/detail/info_desc_helpers.hpp> // for is_context_info_desc
17 #include <sycl/detail/owner_less_base.hpp> // for OwnerLessBase
18 #include <sycl/detail/pi.h> // for pi_native_handle
19 #include <sycl/platform.hpp> // for platform
20 #include <sycl/property_list.hpp> // for property_list
21 
22 #ifdef __SYCL_INTERNAL_API
23 #include <sycl/detail/cl.h>
24 #endif
25 
26 #include <cstddef> // for size_t
27 #include <memory> // for shared_ptr, hash, opera...
28 #include <type_traits> // for add_pointer_t
29 #include <variant> // for hash
30 #include <vector> // for vector
31 
32 // 4.6.2 Context class
33 
34 namespace sycl {
35 inline namespace _V1 {
36 // Forward declarations
37 class device;
38 class platform;
39 
40 namespace detail {
41 class context_impl;
42 }
43 template <backend Backend, class SyclT>
44 auto get_native(const SyclT &Obj) -> backend_return_t<Backend, SyclT>;
45 
50 class __SYCL_EXPORT context : public detail::OwnerLessBase<context> {
51 public:
60  explicit context(const property_list &PropList = {});
61 
73  explicit context(const async_handler &AsyncHandler,
74  const property_list &PropList = {});
75 
85  explicit context(const device &Device, const property_list &PropList = {});
86 
99  explicit context(const device &Device, async_handler AsyncHandler,
100  const property_list &PropList = {});
101 
111  explicit context(const platform &Platform,
112  const property_list &PropList = {});
113 
126  explicit context(const platform &Platform, async_handler AsyncHandler,
127  const property_list &PropList = {});
128 
139  explicit context(const std::vector<device> &DeviceList,
140  const property_list &PropList = {});
141 
155  explicit context(const std::vector<device> &DeviceList,
156  async_handler AsyncHandler,
157  const property_list &PropList = {});
158 
167 #ifdef __SYCL_INTERNAL_API
168  context(cl_context ClContext, async_handler AsyncHandler = {});
169 #endif
170 
174  template <typename Param>
175  typename detail::is_context_info_desc<Param>::return_type get_info() const;
176 
180  template <typename Param>
182  get_backend_info() const;
183 
184  context(const context &rhs) = default;
185 
186  context(context &&rhs) = default;
187 
188  context &operator=(const context &rhs) = default;
189 
190  context &operator=(context &&rhs) = default;
191 
192  bool operator==(const context &rhs) const { return impl == rhs.impl; }
193 
194  bool operator!=(const context &rhs) const { return !(*this == rhs); }
195 
199  template <typename propertyT> bool has_property() const noexcept;
200 
207  template <typename propertyT> propertyT get_property() const;
208 
214 #ifdef __SYCL_INTERNAL_API
215  cl_context get() const;
216 #endif
217 
222  "is_host() is deprecated as the host device is no longer supported.")
223  bool is_host() const;
224 
228  backend get_backend() const noexcept;
229 
233  platform get_platform() const;
234 
238  std::vector<device> get_devices() const;
239 
240 private:
242  context(std::shared_ptr<detail::context_impl> Impl);
243 
244  pi_native_handle getNative() const;
245 
246  std::shared_ptr<detail::context_impl> impl;
247 
248  template <backend Backend, class SyclT>
249  friend auto get_native(const SyclT &Obj) -> backend_return_t<Backend, SyclT>;
250 
251  template <class Obj>
252  friend decltype(Obj::impl) detail::getSyclObjImpl(const Obj &SyclObject);
253 
254  template <class T>
255  friend typename std::add_pointer_t<typename decltype(T::impl)::element_type>
256  detail::getRawSyclObjImpl(const T &SyclObject);
257 
258  template <class T>
259  friend T detail::createSyclObjFromImpl(decltype(T::impl) ImplObj);
260 };
261 
262 #ifdef __INTEL_PREVIEW_BREAKING_CHANGES
263 // context.hpp depends on exception.hpp but we can't define these ctors in
264 // exception.hpp while context is still an incomplete type.
266  const std::string &WhatArg)
267  : exception(EC, std::make_shared<context>(Ctx), WhatArg) {}
268 
270  const char *WhatArg)
271  : exception(Ctx, EC, std::string(WhatArg)) {}
272 
274  : exception(Ctx, EC, "") {}
275 
276 inline exception::exception(context Ctx, int EV,
277  const std::error_category &ECat,
278  const char *WhatArg)
279  : exception(Ctx, {EV, ECat}, std::string(WhatArg)) {}
280 
281 inline exception::exception(context Ctx, int EV,
282  const std::error_category &ECat,
283  const std::string &WhatArg)
284  : exception(Ctx, {EV, ECat}, WhatArg) {}
285 
286 inline exception::exception(context Ctx, int EV,
287  const std::error_category &ECat)
288  : exception(Ctx, EV, ECat, "") {}
289 #endif
290 
291 } // namespace _V1
292 } // namespace sycl
293 
294 namespace std {
295 template <> struct hash<sycl::context> {
296  size_t operator()(const sycl::context &Context) const {
297  return hash<std::shared_ptr<sycl::detail::context_impl>>()(
299  }
300 };
301 } // namespace std
The context class represents a SYCL context on which kernel functions may be executed.
Definition: context.hpp:50
context & operator=(const context &rhs)=default
bool operator==(const context &rhs) const
Definition: context.hpp:192
context & operator=(context &&rhs)=default
__SYCL2020_DEPRECATED("is_host() is deprecated as the host device is no longer supported.") bool is_host() const
Gets OpenCL interoperability context.
bool operator!=(const context &rhs) const
Definition: context.hpp:194
context(context &&rhs)=default
bool has_property() const noexcept
Checks if this context has a property of type propertyT.
context(const context &rhs)=default
The SYCL device class encapsulates a single SYCL device on which kernels may be executed.
Definition: device.hpp:64
exception(std::error_code, const char *Msg)
Definition: exception.cpp:19
Encapsulates a SYCL platform on which kernels may be executed.
Definition: platform.hpp:99
Objects of the property_list class are containers for the SYCL properties.
std::add_pointer_t< typename decltype(T::impl)::element_type > getRawSyclObjImpl(const T &SyclObject)
Definition: impl_utils.hpp:40
decltype(Obj::impl) getSyclObjImpl(const Obj &SyclObject)
Definition: impl_utils.hpp:30
T createSyclObjFromImpl(decltype(T::impl) ImplObj)
Definition: impl_utils.hpp:48
static constexpr auto get_property()
pointer get() const
Definition: multi_ptr.hpp:544
auto get_native(const SyclObjectT &Obj) -> backend_return_t< BackendName, SyclObjectT >
Definition: backend.hpp:136
typename backend_traits< Backend >::template return_type< SyclType > backend_return_t
Definition: backend.hpp:87
std::function< void(sycl::exception_list)> async_handler
Definition: access.hpp:18
error_code
Definition: defs.hpp:59
uintptr_t pi_native_handle
Definition: pi.h:226
_Abi const simd< _Tp, _Abi > & noexcept
Definition: simd.hpp:1324
size_t operator()(const sycl::context &Context) const
Definition: context.hpp:296