Rename sentinel.cuh -> types.cuh (#452)

sleeepyjack · web-flow · commit c620ce389c8a · 2024-04-03T03:33:58.000+02:00
This PR renames `include/cuco/sentinel.cuh` to `include/cuco/types.cuh` as preparation work for #429. The goal is to have a single header containing all strong types used across cuco. Note: Apparently Doxygen has become even pickier. I had to add some more inline docs to headers which we haven't touched in a while to get the pre-commit test to pass.
diff --git a/include/cuco/dynamic_map.cuh b/include/cuco/dynamic_map.cuh
@@ -18,8 +18,8 @@
 
 #include <cuco/detail/dynamic_map_kernels.cuh>
 #include <cuco/hash_functions.cuh>
-#include <cuco/sentinel.cuh>
 #include <cuco/static_map.cuh>
+#include <cuco/types.cuh>
 
 #include <thrust/device_vector.h>
 #include <thrust/functional.h>
diff --git a/include/cuco/operator.hpp b/include/cuco/operator.hpp
@@ -24,37 +24,37 @@ inline namespace op {
  * @brief `insert` operator tag
  */
 struct insert_tag {
-} inline constexpr insert;
+} inline constexpr insert;  ///< `cuco::insert` operator
 
 /**
  * @brief `insert_and_find` operator tag
  */
 struct insert_and_find_tag {
-} inline constexpr insert_and_find;
+} inline constexpr insert_and_find;  ///< `cuco::insert_and_find` operator
 
 /**
  * @brief `insert_or_assign` operator tag
  */
 struct insert_or_assign_tag {
-} inline constexpr insert_or_assign;
+} inline constexpr insert_or_assign;  ///< `cuco::insert_or_assign` operator
 
 /**
  * @brief `erase` operator tag
  */
 struct erase_tag {
-} inline constexpr erase;
+} inline constexpr erase;  ///< `cuco::erase` operator
 
 /**
  * @brief `contains` operator tag
  */
 struct contains_tag {
-} inline constexpr contains;
+} inline constexpr contains;  ///< `cuco::contains` operator
 
 /**
  * @brief `find` operator tag
  */
 struct find_tag {
-} inline constexpr find;
+} inline constexpr find;  ///< `cuco::find` operator
 
 }  // namespace op
 }  // namespace cuco
diff --git a/include/cuco/static_map.cuh b/include/cuco/static_map.cuh
@@ -22,8 +22,8 @@
 #include <cuco/detail/static_map_kernels.cuh>
 #include <cuco/hash_functions.cuh>
 #include <cuco/pair.cuh>
-#include <cuco/sentinel.cuh>
 #include <cuco/static_map_ref.cuh>
+#include <cuco/types.cuh>
 #include <cuco/utility/allocator.hpp>
 #include <cuco/utility/cuda_thread_scope.cuh>
 #include <cuco/utility/traits.hpp>
diff --git a/include/cuco/static_map_ref.cuh b/include/cuco/static_map_ref.cuh
@@ -20,8 +20,8 @@
 #include <cuco/hash_functions.cuh>
 #include <cuco/operator.hpp>
 #include <cuco/probing_scheme.cuh>
-#include <cuco/sentinel.cuh>
 #include <cuco/storage.cuh>
+#include <cuco/types.cuh>
 #include <cuco/utility/cuda_thread_scope.cuh>
 
 #include <cuda/std/atomic>
diff --git a/include/cuco/static_multimap.cuh b/include/cuco/static_multimap.cuh
@@ -20,7 +20,7 @@
 #include <cuco/detail/prime.hpp>
 #include <cuco/hash_functions.cuh>
 #include <cuco/probe_sequences.cuh>
-#include <cuco/sentinel.cuh>
+#include <cuco/types.cuh>
 #include <cuco/utility/allocator.hpp>
 #include <cuco/utility/traits.hpp>
 
diff --git a/include/cuco/static_multiset.cuh b/include/cuco/static_multiset.cuh
@@ -21,9 +21,9 @@
 #include <cuco/extent.cuh>
 #include <cuco/hash_functions.cuh>
 #include <cuco/probing_scheme.cuh>
-#include <cuco/sentinel.cuh>
 #include <cuco/static_multiset_ref.cuh>
 #include <cuco/storage.cuh>
+#include <cuco/types.cuh>
 #include <cuco/utility/allocator.hpp>
 #include <cuco/utility/cuda_thread_scope.cuh>
 #include <cuco/utility/traits.hpp>
diff --git a/include/cuco/static_multiset_ref.cuh b/include/cuco/static_multiset_ref.cuh
@@ -20,8 +20,8 @@
 #include <cuco/hash_functions.cuh>
 #include <cuco/operator.hpp>
 #include <cuco/probing_scheme.cuh>
-#include <cuco/sentinel.cuh>
 #include <cuco/storage.cuh>
+#include <cuco/types.cuh>
 #include <cuco/utility/cuda_thread_scope.cuh>
 
 #include <cuda/std/atomic>
diff --git a/include/cuco/static_set.cuh b/include/cuco/static_set.cuh
@@ -21,9 +21,9 @@
 #include <cuco/extent.cuh>
 #include <cuco/hash_functions.cuh>
 #include <cuco/probing_scheme.cuh>
-#include <cuco/sentinel.cuh>
 #include <cuco/static_set_ref.cuh>
 #include <cuco/storage.cuh>
+#include <cuco/types.cuh>
 #include <cuco/utility/allocator.hpp>
 #include <cuco/utility/cuda_thread_scope.cuh>
 #include <cuco/utility/traits.hpp>
diff --git a/include/cuco/static_set_ref.cuh b/include/cuco/static_set_ref.cuh
@@ -20,8 +20,8 @@
 #include <cuco/hash_functions.cuh>
 #include <cuco/operator.hpp>
 #include <cuco/probing_scheme.cuh>
-#include <cuco/sentinel.cuh>
 #include <cuco/storage.cuh>
+#include <cuco/types.cuh>
 #include <cuco/utility/cuda_thread_scope.cuh>
 
 #include <cuda/std/atomic>
diff --git a/include/cuco/types.cuh b/include/cuco/types.cuh
@@ -18,6 +18,16 @@
 
 #include <cuco/detail/utility/strong_type.cuh>
 
+/**
+ * @brief Defines various strong type wrappers used across this library.
+ *
+ * @note Each strong type inherits from `cuco::detail::strong_type<T>`. `CUCO_DEFINE_STRONG_TYPE`
+ * and `CUCO_DEFINE_TEMPLATE_STRONG_TYPE` are convenience macros used to define a named type in a
+ * single line, e.g., `CUCO_DEFINE_STRONG_TYPE(foo, double)` defines `struct foo : public
+ * cuco::detail::strong_type<double> {...};`, where `cuco::foo{42.0}` is implicitly convertible to
+ * `double{42.0}`.
+ */
+
 namespace cuco {
 /**
  * @brief A strong type wrapper `cuco::empty_key<Key>` used to denote the empty key sentinel.
diff --git a/include/cuco/utility/allocator.hpp b/include/cuco/utility/allocator.hpp
@@ -60,12 +60,31 @@ class cuda_allocator {
   void deallocate(value_type* p, std::size_t) { CUCO_CUDA_TRY(cudaFree(p)); }
 };
 
+/**
+ * @brief Equality comparison operator.
+ *
+ * @tparam T Value type of LHS object
+ * @tparam U Value type of RHS object
+ *
+ * @return `true` iff given arguments are equal
+ */
 template <typename T, typename U>
 bool operator==(cuda_allocator<T> const&, cuda_allocator<U> const&) noexcept
 {
   return true;
 }
 
+/**
+ * @brief Inequality comparison operator.
+ *
+ * @tparam T Value type of LHS object
+ * @tparam U Value type of RHS object
+ *
+ * @param lhs Left-hand side object to compare
+ * @param rhs Right-hand side object to compare
+ *
+ * @return `true` iff given arguments are not equal
+ */
 template <typename T, typename U>
 bool operator!=(cuda_allocator<T> const& lhs, cuda_allocator<U> const& rhs) noexcept
 {
diff --git a/include/cuco/utility/cuda_thread_scope.cuh b/include/cuco/utility/cuda_thread_scope.cuh
@@ -36,9 +36,13 @@ struct cuda_thread_scope {
 };
 
 // alias definitions
-inline constexpr auto thread_scope_system = cuda_thread_scope<cuda::thread_scope_system>{};
-inline constexpr auto thread_scope_device = cuda_thread_scope<cuda::thread_scope_device>{};
-inline constexpr auto thread_scope_block  = cuda_thread_scope<cuda::thread_scope_block>{};
-inline constexpr auto thread_scope_thread = cuda_thread_scope<cuda::thread_scope_thread>{};
+inline constexpr auto thread_scope_system =
+  cuda_thread_scope<cuda::thread_scope_system>{};  ///< `cuco::thread_scope_system`
+inline constexpr auto thread_scope_device =
+  cuda_thread_scope<cuda::thread_scope_device>{};  ///< `cuco::thread_scope_device`
+inline constexpr auto thread_scope_block =
+  cuda_thread_scope<cuda::thread_scope_block>{};  ///< `cuco::thread_scope_block`
+inline constexpr auto thread_scope_thread =
+  cuda_thread_scope<cuda::thread_scope_thread>{};  ///< `cuco::thread_scope_thread`
 
 }  // namespace cuco
diff --git a/include/cuco/utility/traits.hpp b/include/cuco/utility/traits.hpp
@@ -46,7 +46,8 @@ struct is_bitwise_comparable<T, std::enable_if_t<std::has_unique_object_represen
   : std::true_type {};
 
 template <typename T>
-inline constexpr bool is_bitwise_comparable_v = is_bitwise_comparable<T>::value;
+inline constexpr bool is_bitwise_comparable_v =
+  is_bitwise_comparable<T>::value;  ///< Shortcut definition
 
 /**
  * @brief Declares that a type `Type` is bitwise comparable.
@@ -59,9 +60,11 @@ inline constexpr bool is_bitwise_comparable_v = is_bitwise_comparable<T>::value;
   }
 
 template <bool value, typename... Args>
-inline constexpr bool dependent_bool_value = value;
+inline constexpr bool dependent_bool_value = value;  ///< Unpacked dependent bool value
 
 template <typename... Args>
-inline constexpr bool dependent_false = dependent_bool_value<false, Args...>;
+inline constexpr bool dependent_false =
+  dependent_bool_value<false, Args...>;  ///< Emits a `false` value which is dependent on the given
+                                         ///< argument types
 
 }  // namespace cuco
