docu traits iterator

Author: tonibohnlein

include/osp/concepts/graph_traits.hpp

@@ -20,12 +20,28 @@ limitations under the License.
 
 #include "iterator_concepts.hpp"
 
+/**
+ * @file graph_traits.hpp
+ * @brief Type traits and concepts for graph structures in OneStopParallel.
+ *
+ * This file defines the core requirements for types used by graph implementations in the library,
+ * specifically for computational DAGs. It provides mechanisms
+ * to extract types for vertex indices, edge descriptors, and weights,
+ * ensuring that graph implementations conform to the expected interfaces.
+ */
+
 namespace osp {
 
-#define DEFINE_TYPE_MEMBER_TEST(test_name, member_name)                                                                \
-    template<typename T, typename = void>                                                                              \
-    struct test_name : std::false_type {};                                                                             \
-    template<typename T>                                                                                               \
+/**
+ * @brief Macro to define a trait that checks for the existence of a specific type member.
+ *
+ * Creates a struct `test_name<T>` inheriting from `std::true_type` if `T::member_name` exists,
+ * otherwise inherits from `std::false_type`.
+ */
+#define DEFINE_TYPE_MEMBER_TEST(test_name, member_name) \
+    template<typename T, typename = void>               \
+    struct test_name : std::false_type {};              \
+    template<typename T>                                \
     struct test_name<T, std::void_t<typename T::member_name>> : std::true_type {};
 
 DEFINE_TYPE_MEMBER_TEST(has_vertex_idx_tmember, vertex_idx)
@@ -36,17 +52,33 @@ DEFINE_TYPE_MEMBER_TEST(has_vertex_mem_weight_tmember, vertex_mem_weight_type)
 DEFINE_TYPE_MEMBER_TEST(has_vertex_type_tmember, vertex_type_type)
 DEFINE_TYPE_MEMBER_TEST(has_edge_comm_weight_tmember, edge_comm_weight_type)
 
-// Every directed graph must have a vertex_idx type
+/**
+ * @brief Core traits for any directed graph type.
+ *
+ * Requires that the graph type `T` defines a `vertex_idx` type member.
+ *
+ * @tparam T The graph type.
+ */
 template<typename T>
 struct directed_graph_traits {
     static_assert(has_vertex_idx_tmember<T>::value, "graph must have vertex_idx");
     using vertex_idx = typename T::vertex_idx;
 };
 
-// Macro to extract the vertex_idx type from the graph
+/**
+ * @brief Alias to easily access the vertex index type of a graph.
+ */
 template<typename T>
 using vertex_idx_t = typename directed_graph_traits<T>::vertex_idx;
 
+/**
+ * @brief A default edge descriptor for directed graphs.
+ *
+ * This struct is used when the graph type does not provide its own edge descriptor.
+ * It simply holds the source and target vertex indices.
+ *
+ * @tparam Graph_t The graph type.
+ */
 template<typename Graph_t>
 struct directed_edge {
 
@@ -65,6 +97,11 @@ struct directed_edge {
     directed_edge(vertex_idx_t<Graph_t> src, vertex_idx_t<Graph_t> tgt) : source(src), target(tgt) {}
 };
 
+/**
+ * @brief Helper struct to extract the edge descriptor type of a directed graph.
+ *
+ * If the graph defines `directed_edge_descriptor`, it is extracted; otherwise, `directed_edge` is used as a default implementation.
+ */
 template<typename T, bool has_edge>
 struct directed_graph_edge_desc_traits_helper {
     using directed_edge_descriptor = directed_edge<T>;
@@ -84,6 +121,16 @@ struct directed_graph_edge_desc_traits {
 template<typename T>
 using edge_desc_t = typename directed_graph_edge_desc_traits<T>::directed_edge_descriptor;
 
+/**
+ * @brief Traits for computational Directed Acyclic Graphs (DAGs).
+ *
+ * Computational DAGs extend basic graphs by adding requirements for weight types:
+ * - `vertex_work_weight_type`: Represents computational cost of a task.
+ * - `vertex_comm_weight_type`: Represents data size/communication cost.
+ * - `vertex_mem_weight_type`: Represents memory usage of a task.
+ *
+ * @tparam T The computational DAG type.
+ */
 template<typename T>
 struct computational_dag_traits {
     static_assert(has_vertex_work_weight_tmember<T>::value, "cdag must have vertex work weight type");
@@ -104,6 +151,11 @@ using v_commw_t = typename computational_dag_traits<T>::vertex_comm_weight_type;
 template<typename T>
 using v_memw_t = typename computational_dag_traits<T>::vertex_mem_weight_type;
 
+/**
+ * @brief Traits to extract the vertex type of a computational DAG, if defined.
+ *
+ * If the DAG defines `vertex_type_type`, it is extracted; otherwise, `void` is used.
+ */
 template<typename T, typename = void>
 struct computational_dag_typed_vertices_traits {
     using vertex_type_type = void;
@@ -117,6 +169,11 @@ struct computational_dag_typed_vertices_traits<T, std::void_t<typename T::vertex
 template<typename T>
 using v_type_t = typename computational_dag_typed_vertices_traits<T>::vertex_type_type;
 
+/**
+ * @brief Traits to extract the edge communication weight type of a computational DAG, if defined.
+ *
+ * If the DAG defines `edge_comm_weight_type`, it is extracted; otherwise, `void` is used.
+ */
 template<typename T, typename = void>
 struct computational_dag_edge_desc_traits {
     using edge_comm_weight_type = void;
@@ -130,6 +187,14 @@ struct computational_dag_edge_desc_traits<T, std::void_t<typename T::edge_comm_w
 template<typename T>
 using e_commw_t = typename computational_dag_edge_desc_traits<T>::edge_comm_weight_type;
 
+// -----------------------------------------------------------------------------
+// Property Traits
+// -----------------------------------------------------------------------------
+
+/**
+ * @brief Check if a graph guarantees vertices are stored/iterated in topological order.
+ * It allows a graph implementation to notify algorithms that vertices are stored/iterated in topological order which can be used to optimize the algorithm.
+ */
 template<typename T, typename = void>
 struct has_vertices_in_top_order_trait : std::false_type {};
 
@@ -140,6 +205,9 @@ struct has_vertices_in_top_order_trait<T, std::void_t<decltype(T::vertices_in_to
 template<typename T>
 inline constexpr bool has_vertices_in_top_order_v = has_vertices_in_top_order_trait<T>::value;
 
+/**
+ * @brief Check if a graph guarantees children of a vertex are stored/iterated in vertex index order.
+ */
 template<typename T, typename = void>
 struct has_children_in_vertex_order_trait : std::false_type {};
 
@@ -150,6 +218,9 @@ struct has_children_in_vertex_order_trait<T, std::void_t<decltype(T::children_in
 template<typename T>
 inline constexpr bool has_children_in_vertex_order_v = has_children_in_vertex_order_trait<T>::value;
 
+/**
+ * @brief Check if a graph guarantees parents of a vertex are stored/iterated in vertex index order.
+ */
 template<typename T, typename = void>
 struct has_parents_in_vertex_order_trait : std::false_type {};
 
@@ -162,6 +233,11 @@ inline constexpr bool has_parents_in_vertex_order_v = has_parents_in_vertex_orde
 
 } // namespace osp
 
+/**
+ * @brief Specialization of std::hash for osp::directed_edge.
+ *
+ * This specialization provides a hash function for osp::directed_edge, which is used in hash-based containers like std::unordered_set and std::unordered_map.
+ */
 template<typename Graph_t>
 struct std::hash<osp::directed_edge<Graph_t>> {
     std::size_t operator()(const osp::directed_edge<Graph_t> &p) const noexcept {

include/osp/concepts/iterator_concepts.hpp

@@ -13,18 +13,35 @@ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 See the License for the specific language governing permissions and
 limitations under the License.
 
-@author Toni Boehnlein, Benjamin Lozes, Pal Andras Papp, Raphael S. Steiner   
+@author Toni Boehnlein, Benjamin Lozes, Pal Andras Papp, Raphael S. Steiner
 */
 
-
 #pragma once
 
 #include <iterator>
 #include <type_traits>
 
 namespace osp {
-
-// Concept for const_iterator with forward iterator category
+/**
+ * @file iterator_concepts.hpp
+ * @brief C++17 compatible concept checks (type traits) for iterators and ranges.
+ *
+ * This file provides type traits that emulate C++20 concepts for iterators and ranges.
+ * These are used to ensure type safety and correct usage of templates within the library
+ * while maintaining compatibility with C++17.
+ */
+
+/**
+ * @brief Checks if a type is a forward iterator.
+ *
+ * This type trait checks if `T` satisfies the requirements of a forward iterator.
+ * It verifies the existence of standard iterator typedefs and checks if the iterator category
+ * is derived from `std::forward_iterator_tag`.
+ *
+ * @note Equivalent to C++20 `std::forward_iterator`.
+ *
+ * @tparam T The type to check.
+ */
 template<typename T, typename = void>
 struct is_forward_iterator : std::false_type {};
 
@@ -41,14 +58,24 @@ struct is_forward_iterator<
 template<typename T>
 inline constexpr bool is_forward_iterator_v = is_forward_iterator<T>::value;
 
-// Concept for ranges with const forward iterators supporting begin or cbegin
+/**
+ * @brief Checks if a type is a range of forward iterators with a specific value type.
+ *
+ * This type trait checks if `T` is a range (provides `begin()` and `end()`) whose iterator
+ * satisfies `is_forward_iterator` and whose value type matches `ValueType`.
+ *
+ * @note Equivalent to C++20 `std::ranges::forward_range` combined with a value type check.
+ *
+ * @tparam T The range type to check.
+ * @tparam ValueType The expected value type of the range.
+ */
 template<typename T, typename ValueType, typename = void>
 struct is_forward_range_of : std::false_type {};
 
 template<typename T, typename ValueType>
 struct is_forward_range_of<
     T, ValueType,
-    std::void_t<decltype(std::begin(std::declval<T>())), 
+    std::void_t<decltype(std::begin(std::declval<T>())),
                 decltype(std::end(std::declval<T>()))>>
     : std::conjunction<
           is_forward_iterator<decltype(std::begin(std::declval<T>()))>,
@@ -57,7 +84,17 @@ struct is_forward_range_of<
 template<typename T, typename ValueType>
 inline constexpr bool is_forward_range_of_v = is_forward_range_of<T, ValueType>::value;
 
-// Concept for containers
+/**
+ * @brief Checks if a type is a container (sized forward range).
+ *
+ * This type trait checks if `T` satisfies `is_forward_range_of` and additionally provides
+ * a `size()` member function.
+ *
+ * @note Equivalent to C++20 `std::ranges::sized_range` combined with `std::ranges::forward_range`.
+ *
+ * @tparam T The container type to check.
+ * @tparam ValueType The expected value type of the container.
+ */
 template<typename T, typename ValueType, typename = void>
 struct is_container_of : std::false_type {};
 
@@ -71,9 +108,17 @@ struct is_container_of<
 template<typename T, typename ValueType>
 inline constexpr bool is_container_of_v = is_container_of<T, ValueType>::value;
 
-
-
-// Concept for const_iterator with forward iterator category
+/**
+ * @brief Checks if a type is an input iterator.
+ *
+ * This type trait checks if `T` satisfies the requirements of an input iterator.
+ * It verifies the existence of standard iterator typedefs and checks if the iterator category
+ * is derived from `std::input_iterator_tag`.
+ *
+ * @note Equivalent to C++20 `std::input_iterator`.
+ *
+ * @tparam T The type to check.
+ */
 template<typename T, typename = void>
 struct is_input_iterator : std::false_type {};
 
@@ -90,14 +135,24 @@ struct is_input_iterator<
 template<typename T>
 inline constexpr bool is_input_iterator_v = is_input_iterator<T>::value;
 
-// Concept for ranges with const input iterators supporting begin or cbegin
+/**
+ * @brief Checks if a type is a range of input iterators with a specific value type.
+ *
+ * This type trait checks if `T` is a range (provides `begin()` and `end()`) whose iterator
+ * satisfies `is_input_iterator` and whose value type matches `ValueType`.
+ *
+ * @note Equivalent to C++20 `std::ranges::input_range` combined with a value type check.
+ *
+ * @tparam T The range type to check.
+ * @tparam ValueType The expected value type of the range.
+ */
 template<typename T, typename ValueType, typename = void>
 struct is_input_range_of : std::false_type {};
 
 template<typename T, typename ValueType>
 struct is_input_range_of<
     T, ValueType,
-    std::void_t<decltype(std::begin(std::declval<T>())), 
+    std::void_t<decltype(std::begin(std::declval<T>())),
                 decltype(std::end(std::declval<T>()))>>
     : std::conjunction<
           is_input_iterator<decltype(std::begin(std::declval<T>()))>,
@@ -106,5 +161,4 @@ struct is_input_range_of<
 template<typename T, typename ValueType>
 inline constexpr bool is_input_range_of_v = is_input_range_of<T, ValueType>::value;
 
-
 } // namespace osp