experimental wrapper types for cudaEvent_t that provide a modern C++ interface.

cudax/include/cuda/experimental/__detail/utility.cuh

@@ -0,0 +1,24 @@
+//===----------------------------------------------------------------------===//
+//
+// Part of CUDA Experimental in CUDA C++ Core Libraries,
+// 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
+// SPDX-FileCopyrightText: Copyright (c) 2024 NVIDIA CORPORATION & AFFILIATES.
+//
+//===----------------------------------------------------------------------===//
+
+#ifndef __CUDAX_DETAIL_UTILITY_H
+#define __CUDAX_DETAIL_UTILITY_H
+
+namespace cuda::experimental
+{
+struct uninit_t
+{
+  explicit uninit_t() = default;
+};
+
+inline constexpr uninit_t uninit{};
+} // namespace cuda::experimental
+
+#endif // __CUDAX_DETAIL_UTILITY_H

cudax/include/cuda/experimental/__event/event.cuh

@@ -0,0 +1,156 @@
+//===----------------------------------------------------------------------===//
+//
+// Part of CUDA Experimental in CUDA C++ Core Libraries,
+// 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
+// SPDX-FileCopyrightText: Copyright (c) 2024 NVIDIA CORPORATION & AFFILIATES.
+//
+//===----------------------------------------------------------------------===//
+
+#ifndef _CUDAX_EVENT_DETAIL_H
+#define _CUDAX_EVENT_DETAIL_H
+
+#include <cuda_runtime_api.h>
+// cuda_runtime_api needs to come first
+
+#include <cuda/std/detail/__config>
+
+#if defined(_CCCL_IMPLICIT_SYSTEM_HEADER_GCC)
+#  pragma GCC system_header
+#elif defined(_CCCL_IMPLICIT_SYSTEM_HEADER_CLANG)
+#  pragma clang system_header
+#elif defined(_CCCL_IMPLICIT_SYSTEM_HEADER_MSVC)
+#  pragma system_header
+#endif // no system header
+
+#include <cuda/std/__cuda/api_wrapper.h>
+#include <cuda/std/cstddef>
+#include <cuda/std/utility>
+
+#include <cuda/experimental/__detail/utility.cuh>
+#include <cuda/experimental/__event/event_ref.cuh>
+
+namespace cuda::experimental
+{
+class timed_event;
+
+//! @brief An owning wrapper for an untimed `cudaEvent_t`.
+class event : public event_ref
+{
+  friend class timed_event;
+
+public:
+  //! @brief Flags to use when creating the event.
+  enum class flags : unsigned int
+  {
+    none          = cudaEventDefault,
+    blocking_sync = cudaEventBlockingSync,
+    interprocess  = cudaEventInterprocess
+  };
+
+  //! @brief Construct a new `event` object with timing disabled, and record
+  //!        the event in the specified stream.
+  //!
+  //! @throws cuda_error if the event creation fails.
+  explicit event(stream_ref __stream, flags __flags = flags::none)
+      : event(static_cast<unsigned int>(__flags) | cudaEventDisableTiming)
+  {
+    record(__stream);
+  }
+
+  //! @brief Construct a new `event` object into the moved-from state.
+  //!
+  //! @post `get()` returns `cudaEvent_t()`.
+  explicit constexpr event(uninit_t) noexcept
+      : event_ref(::cudaEvent_t{})
+  {}
+
+  //! @brief Move-construct a new `event` object
+  //!
+  //! @param __other
+  //!
+  //! @post `__other` is in a moved-from state.
+  constexpr event(event&& __other) noexcept
+      : event_ref(_CUDA_VSTD::exchange(__other.__event_, {}))
+  {}
+
+  // Disallow copy construction.
+  event(const event&) = delete;
+
+  //! @brief Destroy the `event` object
+  //!
+  //! @note If the event fails to be destroyed, the error is silently ignored.
+  ~event()
+  {
+    if (__event_ != nullptr)
+    {
+      [[maybe_unused]] auto __status = ::cudaEventDestroy(__event_);
+    }
+  }
+
+  //! @brief Move-assign an `event` object
+  //!
+  //! @param __other
+  //!
+  //! @post `__other` is in a moved-from state.
+  event& operator=(event&& __other) noexcept
+  {
+    event __tmp(_CUDA_VSTD::move(__other));
+    _CUDA_VSTD::swap(__event_, __tmp.__event_);
+    return *this;
+  }
+
+  // Disallow copy assignment.
+  event& operator=(const event&) = delete;
+
+  //! @brief Construct an `event` object from a native `cudaEvent_t` handle.
+  //!
+  //! @param __evnt The native handle
+  //!
+  //! @return event The constructed `event` object
+  //!
+  //! @note The constructed `event` object takes ownership of the native handle.
+  _CCCL_NODISCARD static event from_native_handle(::cudaEvent_t __evnt) noexcept
+  {
+    return event(__evnt);
+  }
+
+  // Disallow construction from an `int`, e.g., `0`.
+  static event from_native_handle(int) = delete;
+
+  // Disallow construction from `nullptr`.
+  static event from_native_handle(_CUDA_VSTD::nullptr_t) = delete;
+
+  //! @brief Retrieve the native `cudaEvent_t` handle and give up ownership.
+  //!
+  //! @return cudaEvent_t The native handle being held by the `event` object.
+  //!
+  //! @post The event object is in a moved-from state.
+  _CCCL_NODISCARD constexpr ::cudaEvent_t release() noexcept
+  {
+    return _CUDA_VSTD::exchange(__event_, {});
+  }
+
+  _CCCL_NODISCARD_FRIEND constexpr flags operator|(flags __lhs, flags __rhs) noexcept
+  {
+    return static_cast<flags>(static_cast<unsigned int>(__lhs) | static_cast<unsigned int>(__rhs));
+  }
+
+private:
+  // Use `event::from_native_handle(e)` to construct an owning `event`
+  // object from a `cudaEvent_t` handle.
+  explicit constexpr event(::cudaEvent_t __evnt) noexcept
+      : event_ref(__evnt)
+  {}
+
+  explicit event(unsigned int __flags)
+      : event_ref(::cudaEvent_t{})
+  {
+    _CCCL_TRY_CUDA_API(
+      ::cudaEventCreateWithFlags, "Failed to create CUDA event", &__event_, static_cast<unsigned int>(__flags));
+  }
+};
+} // namespace cuda::experimental
+
+#endif // _CUDAX_EVENT_DETAIL_H

cudax/include/cuda/experimental/__event/event_ref.cuh

@@ -0,0 +1,134 @@
+//===----------------------------------------------------------------------===//
+//
+// Part of CUDA Experimental in CUDA C++ Core Libraries,
+// 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
+// SPDX-FileCopyrightText: Copyright (c) 2024 NVIDIA CORPORATION & AFFILIATES.
+//
+//===----------------------------------------------------------------------===//
+
+#ifndef _CUDAX_EVENT_REF_DETAIL_H
+#define _CUDAX_EVENT_REF_DETAIL_H
+
+#include <cuda_runtime_api.h>
+// cuda_runtime_api needs to come first
+
+#include <cuda/std/detail/__config>
+
+#if defined(_CCCL_IMPLICIT_SYSTEM_HEADER_GCC)
+#  pragma GCC system_header
+#elif defined(_CCCL_IMPLICIT_SYSTEM_HEADER_CLANG)
+#  pragma clang system_header
+#elif defined(_CCCL_IMPLICIT_SYSTEM_HEADER_MSVC)
+#  pragma system_header
+#endif // no system header
+
+#include <cuda/std/__cuda/api_wrapper.h>
+#include <cuda/std/cassert>
+#include <cuda/std/cstddef>
+#include <cuda/std/utility>
+#include <cuda/stream_ref>
+
+namespace cuda::experimental
+{
+class event;
+class timed_event;
+
+//! @brief An non-owning wrapper for an untimed `cudaEvent_t`.
+class event_ref
+{
+private:
+  friend class event;
+  friend class timed_event;
+
+  ::cudaEvent_t __event_{};
+
+public:
+  using value_type = ::cudaEvent_t;
+
+  //! @brief Construct a new `event_ref` object from a `cudaEvent_t`
+  //!
+  //! This constructor provides an implicit conversion from `cudaEvent_t`
+  //!
+  //! @post `get() == __evnt`
+  //!
+  //! @note: It is the callers responsibilty to ensure the `event_ref` does not
+  //! outlive the event denoted by the `cudaEvent_t` handle.
+  constexpr event_ref(::cudaEvent_t __evnt) noexcept
+      : __event_(__evnt)
+  {}
+
+  /// Disallow construction from an `int`, e.g., `0`.
+  event_ref(int) = delete;
+
+  /// Disallow construction from `nullptr`.
+  event_ref(_CUDA_VSTD::nullptr_t) = delete;
+
+  //! @brief Records an event on the specified stream
+  //!
+  //! @param __stream
+  //!
+  //! @throws cuda_error if the event record fails
+  void record(stream_ref __stream) const
+  {
+    assert(__event_ != nullptr);
+    assert(__stream.get() != nullptr);
+    _CCCL_TRY_CUDA_API(::cudaEventRecord, "Failed to record CUDA event", __event_, __stream.get());
+  }
+
+  //! @brief Waits until all the work in the stream prior to the record of the
+  //!        event has completed.
+  //!
+  //! @throws cuda_error if waiting for the event fails
+  void wait() const
+  {
+    assert(__event_ != nullptr);
+    _CCCL_TRY_CUDA_API(::cudaEventSynchronize, "Failed to wait for CUDA event", __event_);
+  }
+
+  //! @brief Retrieve the native `cudaEvent_t` handle.
+  //!
+  //! @return cudaEvent_t The native handle being held by the event_ref object.
+  _CCCL_NODISCARD constexpr ::cudaEvent_t get() const noexcept
+  {
+    return __event_;
+  }
+
+  //! @brief Checks if the `event_ref` is valid
+  //!
+  //! @return true if the `event_ref` is valid, false otherwise.
+  _CCCL_NODISCARD explicit constexpr operator bool() const noexcept
+  {
+    return __event_ != nullptr;
+  }
+
+  //! @brief Compares two `event_ref`s for equality
+  //!
+  //! @note Allows comparison with `cudaEvent_t` due to implicit conversion to
+  //! `event_ref`.
+  //!
+  //! @param lhs The first `event_ref` to compare
+  //! @param rhs The second `event_ref` to compare
+  //! @return true if `lhs` and `rhs` refer to the same `cudaEvent_t` object.
+  _CCCL_NODISCARD_FRIEND constexpr bool operator==(event_ref __lhs, event_ref __rhs) noexcept
+  {
+    return __lhs.__event_ == __rhs.__event_;
+  }
+
+  //! @brief Compares two `event_ref`s for inequality
+  //!
+  //! @note Allows comparison with `cudaEvent_t` due to implicit conversion to
+  //! `event_ref`.
+  //!
+  //! @param lhs The first `event_ref` to compare
+  //! @param rhs The second `event_ref` to compare
+  //! @return true if `lhs` and `rhs` refer to different `cudaEvent_t` objects.
+  _CCCL_NODISCARD_FRIEND constexpr bool operator!=(event_ref __lhs, event_ref __rhs) noexcept
+  {
+    return __lhs.__event_ != __rhs.__event_;
+  }
+};
+} // namespace cuda::experimental
+
+#endif // _CUDAX_EVENT_REF_DETAIL_H