[SYCL] Refactor event to improve ABI stability (#907)

Alexander Batashev · bader · commit e3451692d2ef · 2019-12-09T16:24:10.000+03:00
This patch is a part of effort to decouple SYCL Runtime library
interface from its actual implementation. The goal is to improve
SYCL ABI/API compatibility between different versions of library.

The following modifications were applied to platform and platform_impl
classes:

1. Removed include of event_impl header from event.hpp and replaced
it with forward declaration.
2. std::shared_ptr was replaced with shared_ptr_class for platform class
3. Documentation was improved for both eventand event_impl
4. Both classes now try to follow LLVM code style
5. event_impl now uses PI interface.

Applying aforementioned changes requires modifying other header files.
While some of those may seem as a regression, affected classes will be
covered by future patches.

Signed-off-by: Alexander Batashev &lt;alexander.batashev@intel.com&gt;
diff --git a/sycl/include/CL/sycl/detail/event_impl.hpp b/sycl/include/CL/sycl/detail/event_impl.hpp
@@ -24,75 +24,148 @@ using ContextImplPtr = std::shared_ptr<cl::sycl::detail::context_impl>;
 class queue_impl;
 using QueueImplPtr = std::shared_ptr<cl::sycl::detail::queue_impl>;
 
-// Profiling info for the host execution.
+/// Profiling info for the host execution.
 class HostProfilingInfo {
   cl_ulong StartTime = 0;
   cl_ulong EndTime = 0;
 
 public:
+  /// Returns event's start time.
+  ///
+  /// @return event's start time in nanoseconds.
   cl_ulong getStartTime() const { return StartTime; }
+  /// Returns event's end time.
+  ///
+  /// @return event's end time in nanoseconds.
   cl_ulong getEndTime() const { return EndTime; }
 
+  /// Measures event's start time.
   void start();
+  /// Measures event's end time.
   void end();
 };
 
 class event_impl {
 public:
+  /// Constructs a ready SYCL event.
+  ///
+  /// If the constructed SYCL event is waited on it will complete immediately.
   event_impl() = default;
-  event_impl(cl_event CLEvent, const context &SyclContext);
+  /// Constructs an event instance from a plug-in event handle.
+  ///
+  /// The SyclContext must match the plug-in context associated with the ClEvent.
+  ///
+  /// @param Event is a valid instance of plug-in event.
+  /// @param SyclContext is an instance of SYCL context.
+  event_impl(RT::PiEvent Event, const context &SyclContext);
   event_impl(QueueImplPtr Queue);
 
-  // Threat all devices that don't support interoperability as host devices to
-  // avoid attempts to call method get on such events.
+  /// Checks if this event is a SYCL host event.
+  ///
+  /// All devices that do not support OpenCL interoperability are treated as
+  /// host device to avoid attempts to call method get on such events.
+  //
+  /// @return true if this event is a SYCL host event.
   bool is_host() const;
 
+  /// Returns a valid OpenCL event interoperability handle.
+  ///
+  /// @return a valid instance of OpenCL cl_event.
   cl_event get() const;
 
-  // Self is needed in order to pass shared_ptr to Scheduler.
+  /// Waits for the event.
+  ///
+  /// Self is needed in order to pass shared_ptr to Scheduler.
+  ///
+  /// @param Self is a pointer to this event.
   void wait(std::shared_ptr<cl::sycl::detail::event_impl> Self) const;
 
+  /// Waits for the event.
+  ///
+  /// If any uncaught asynchronous errors occurred on the context that the event
+  /// is waiting on executions from, then call that context's asynchronous error
+  /// handler with those errors.
+  /// Self is needed in order to pass shared_ptr to Scheduler.
+  ///
+  /// @param Self is a pointer to this event.
   void wait_and_throw(std::shared_ptr<cl::sycl::detail::event_impl> Self);
 
+  /// Queries this event for profiling information.
+  ///
+  /// If the requested info is not available when this member function is called
+  /// due to incompletion of command groups associated with the event, then the
+  /// call to this member function will block until the requested info is
+  /// available. If the queue which submitted the command group this event is
+  /// associated with was not constructed with the
+  /// property::queue::enable_profiling property, an invalid_object_error SYCL
+  /// exception is thrown.
+  ///
+  /// @return depends on template parameter.
   template <info::event_profiling param>
   typename info::param_traits<info::event_profiling, param>::return_type
   get_profiling_info() const;
 
+  /// Queries this SYCL event for information.
+  ///
+  /// @return depends on the information being requested.
   template <info::event param>
   typename info::param_traits<info::event, param>::return_type get_info() const;
 
   ~event_impl();
 
+  /// Waits for the event with respect to device type.
   void waitInternal() const;
 
+  /// Marks this event as completed.
   void setComplete();
 
-  // Warning. Returned reference will be invalid if event_impl was destroyed.
+  /// Returns raw interoperability event handle. Returned reference will be]
+  /// invalid if event_impl was destroyed.
+  ///
+  /// @return a reference to an instance of plug-in event handle.
   RT::PiEvent &getHandleRef();
+  /// Returns raw interoperability event handle. Returned reference will be]
+  /// invalid if event_impl was destroyed.
+  ///
+  /// @return a const reference to an instance of plug-in event handle.
   const RT::PiEvent &getHandleRef() const;
 
+  /// Returns context that is associated with this event.
+  ///
+  /// @return a shared pointer to a valid context_impl.
   const ContextImplPtr &getContextImpl();
 
-  // Warning. Provided cl_context inside ContextImplPtr must be associated
-  // with the cl_event object stored in this class
+  /// Associate event with the context.
+  ///
+  /// Provided PiContext inside ContextImplPtr must be associated
+  /// with the PiEvent object stored in this class
+  ///
+  /// @param Context is a shared pointer to an instance of valid context_impl.
   void setContextImpl(const ContextImplPtr &Context);
 
-  void *getCommand() { return m_Command; }
+  /// Returns command that is associated with the event.
+  ///
+  /// @return a generic pointer to Command object instance.
+  void *getCommand() { return MCommand; }
 
-  void setCommand(void *Command) { m_Command = Command; }
+  /// Associates this event with the command.
+  ///
+  /// @param Command is a generic pointer to Command object instance.
+  void setCommand(void *Command) { MCommand = Command; }
 
-  HostProfilingInfo *getHostProfilingInfo() {
-    return m_HostProfilingInfo.get();
-  }
+  /// Returns host profiling information.
+  ///
+  /// @return a pointer to HostProfilingInfo instance.
+  HostProfilingInfo *getHostProfilingInfo() { return MHostProfilingInfo.get(); }
 
 private:
-  RT::PiEvent m_Event = nullptr;
-  ContextImplPtr m_Context;
-  QueueImplPtr m_Queue;
-  bool m_OpenCLInterop = false;
-  bool m_HostEvent = true;
-  std::unique_ptr<HostProfilingInfo> m_HostProfilingInfo;
-  void *m_Command = nullptr;
+  RT::PiEvent MEvent = nullptr;
+  ContextImplPtr MContext;
+  QueueImplPtr MQueue;
+  bool MOpenCLInterop = false;
+  bool MHostEvent = true;
+  std::unique_ptr<HostProfilingInfo> MHostProfilingInfo;
+  void *MCommand = nullptr;
 };
 
 } // namespace detail
diff --git a/sycl/include/CL/sycl/detail/queue_impl.hpp b/sycl/include/CL/sycl/detail/queue_impl.hpp
@@ -11,6 +11,7 @@
 #include <CL/sycl/context.hpp>
 #include <CL/sycl/detail/context_impl.hpp>
 #include <CL/sycl/detail/device_impl.hpp>
+#include <CL/sycl/detail/event_impl.hpp>
 #include <CL/sycl/detail/scheduler/scheduler.hpp>
 #include <CL/sycl/device.hpp>
 #include <CL/sycl/event.hpp>
diff --git a/sycl/include/CL/sycl/event.hpp b/sycl/include/CL/sycl/event.hpp
@@ -9,7 +9,6 @@
 #pragma once
 
 #include <CL/sycl/detail/common.hpp>
-#include <CL/sycl/detail/event_impl.hpp>
 #include <CL/sycl/stl.hpp>
 
 #include <memory>
@@ -18,11 +17,24 @@ namespace cl {
 namespace sycl {
 // Forward declaration
 class context;
+namespace detail {
+class event_impl;
+}
+
 class event {
 public:
+  /// Constructs a ready SYCL event.
+  ///
+  /// If the constructed SYCL event is waited on it will complete immediately.
   event();
 
-  event(cl_event clEvent, const context &syclContext);
+  /// Constructs a SYCL event instance from an OpenCL cl_event.
+  ///
+  /// The SyclContext must match the OpenCL context associated with the ClEvent.
+  ///
+  /// @param ClEvent is a valid instance of OpenCL cl_event.
+  /// @param SyclContext is an instance of SYCL context.
+  event(cl_event ClEvent, const context &SyclContext);
 
   event(const event &rhs) = default;
 
@@ -36,31 +48,73 @@ class event {
 
   bool operator!=(const event &rhs) const;
 
+  /// Returns a valid OpenCL event interoperability handle.
+  ///
+  /// @return a valid instance of OpenCL cl_event.
   cl_event get();
 
+  /// Checks if this event is a SYCL host event.
+  ///
+  /// @return true if this event is a SYCL host event.
   bool is_host() const;
 
+  /// Return the list of events that this event waits for.
+  ///
+  /// Only direct dependencies are returned. Already completed events are not
+  /// included in the returned vector.
+  ///
+  /// @return a vector of SYCL events.
   vector_class<event> get_wait_list();
 
+  /// Wait for the event.
   void wait();
 
+  /// Synchronously wait on a list of events.
+  ///
+  /// @param EventList is a vector of SYCL events.
   static void wait(const vector_class<event> &EventList);
 
+  /// Wait for the event.
+  ///
+  /// If any uncaught asynchronous errors occurred on the context that the event
+  /// is waiting on executions from, then call that context's asynchronous error
+  /// handler with those errors.
   void wait_and_throw();
 
+  /// Synchronously wait on a list of events.
+  ///
+  /// If any uncaught asynchronous errors occurred on the context that the
+  /// events are waiting on executions from, then call those contexts'
+  /// asynchronous error handlers with those errors.
+  ///
+  /// @param EventList is a vector of SYCL events.
   static void wait_and_throw(const vector_class<event> &EventList);
 
+  /// Queries this SYCL event for information.
+  ///
+  /// @return depends on the information being requested.
   template <info::event param>
   typename info::param_traits<info::event, param>::return_type get_info() const;
 
+  /// Queries this SYCL event for profiling information.
+  ///
+  /// If the requested info is not available when this member function is called
+  /// due to incompletion of command groups associated with the event, then the
+  /// call to this member function will block until the requested info is
+  /// available. If the queue which submitted the command group this event is
+  /// associated with was not constructed with the
+  /// property::queue::enable_profiling property, an invalid_object_error SYCL
+  /// exception is thrown.
+  ///
+  /// @return depends on template parameter.
   template <info::event_profiling param>
   typename info::param_traits<info::event_profiling, param>::return_type
   get_profiling_info() const;
 
 private:
-  event(std::shared_ptr<detail::event_impl> event_impl);
+  event(shared_ptr_class<detail::event_impl> EventImpl);
 
-  std::shared_ptr<detail::event_impl> impl;
+  shared_ptr_class<detail::event_impl> impl;
 
   template <class Obj>
   friend decltype(Obj::impl) detail::getSyclObjImpl(const Obj &SyclObject);
@@ -75,7 +129,7 @@ class event {
 namespace std {
 template <> struct hash<cl::sycl::event> {
   size_t operator()(const cl::sycl::event &e) const {
-    return hash<std::shared_ptr<cl::sycl::detail::event_impl>>()(
+    return hash<cl::sycl::shared_ptr_class<cl::sycl::detail::event_impl>>()(
         cl::sycl::detail::getSyclObjImpl(e));
   }
 };
diff --git a/sycl/include/CL/sycl/info/event_profiling_traits.def b/sycl/include/CL/sycl/info/event_profiling_traits.def
@@ -0,0 +1,4 @@
+PARAM_TRAITS_SPEC(event_profiling, command_submit, cl_ulong)
+PARAM_TRAITS_SPEC(event_profiling, command_start, cl_ulong)
+PARAM_TRAITS_SPEC(event_profiling, command_end, cl_ulong)
+
diff --git a/sycl/include/CL/sycl/info/event_traits.def b/sycl/include/CL/sycl/info/event_traits.def
@@ -0,0 +1,3 @@
+PARAM_TRAITS_SPEC(event, command_execution_status, info::event_command_status)
+PARAM_TRAITS_SPEC(event, reference_count, cl_uint)
+
diff --git a/sycl/include/CL/sycl/info/info_desc.hpp b/sycl/include/CL/sycl/info/info_desc.hpp
@@ -258,12 +258,9 @@ template <typename T, T param> class param_traits {};
 
 #include <CL/sycl/info/context_traits.def>
 
-PARAM_TRAITS_SPEC(event, command_execution_status, event_command_status)
-PARAM_TRAITS_SPEC(event, reference_count, cl_uint)
+#include <CL/sycl/info/event_traits.def>
 
-PARAM_TRAITS_SPEC(event_profiling, command_submit, cl_ulong)
-PARAM_TRAITS_SPEC(event_profiling, command_start, cl_ulong)
-PARAM_TRAITS_SPEC(event_profiling, command_end, cl_ulong)
+#include <CL/sycl/info/event_profiling_traits.def>
 
 #include <CL/sycl/info/kernel_sub_group_traits.def>
 #include <CL/sycl/info/kernel_traits.def>
diff --git a/sycl/source/detail/event_impl.cpp b/sycl/source/detail/event_impl.cpp
diff --git a/sycl/source/detail/helpers.cpp b/sycl/source/detail/helpers.cpp
diff --git a/sycl/source/event.cpp b/sycl/source/event.cpp

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+PARAM_TRAITS_SPEC(event, command_execution_status, info::event_command_status)`
	`2`	`+PARAM_TRAITS_SPEC(event, reference_count, cl_uint)`
	`3`	`+`