diff --git a/.ci/pipeline/docs.yml b/.ci/pipeline/docs.yml index 08ddea7d8d7..d4e3899c97d 100644 --- a/.ci/pipeline/docs.yml +++ b/.ci/pipeline/docs.yml @@ -7,6 +7,7 @@ trigger: paths: include: - cpp/daal/include + - cpp/oneapi - docs - examples @@ -19,6 +20,7 @@ pr: paths: include: - cpp/daal/include + - cpp/oneapi - docs - examples diff --git a/cpp/oneapi/dal/algo/kmeans/common.hpp b/cpp/oneapi/dal/algo/kmeans/common.hpp index 55b6627b47e..c1784373706 100644 --- a/cpp/oneapi/dal/algo/kmeans/common.hpp +++ b/cpp/oneapi/dal/algo/kmeans/common.hpp @@ -23,7 +23,11 @@ namespace oneapi::dal::kmeans { namespace task { namespace v1 { +/// Tag-type that parameterizes entities used for solving +/// :capterm:`clustering problem `. struct clustering {}; + +/// Alias tag-type for the clustering task. using by_default = clustering; } // namespace v1 @@ -34,7 +38,12 @@ using v1::by_default; namespace method { namespace v1 { +/// Tag-type that denotes `Lloyd's `_ computational +/// method. struct lloyd_dense {}; + +/// Alias tag-type for `Lloyd's `_ computational +/// method. using by_default = lloyd_dense; } // namespace v1 @@ -74,8 +83,19 @@ class descriptor_base : public base { descriptor_base(); + /// The number of clusters k + /// @invariant :expr:`cluster_count > 0` + /// @remark default = 2 std::int64_t get_cluster_count() const; + + /// The maximum number of iterations :literal:`T` + /// @invariant :expr:`max_iteration_count >= 0` + /// @remark default = 100 std::int64_t get_max_iteration_count() const; + + /// The threshold $\\varepsilon$ for the stop condition + /// @invariant :expr:`accuracy_threshold >= 0.0` + /// @remark default = 0.0 double get_accuracy_threshold() const; protected: @@ -102,6 +122,13 @@ using v1::is_valid_task_v; namespace v1 { +/// @tparam Float The floating-point type that the algorithm uses for +/// intermediate computations. Can be :expr:`float` or +/// :expr:`double`. +/// @tparam Method Tag-type that specifies an implementation of algorithm. Can +/// be :expr:`method::lloyd`. +/// @tparam Task Tag-type that specifies the type of the problem to solve. Can +/// be :expr:`task::clustering`. template ::float_t, typename Method = detail::descriptor_base<>::method_t, typename Task = detail::descriptor_base<>::task_t> @@ -117,6 +144,7 @@ class descriptor : public detail::descriptor_base { using method_t = Method; using task_t = Task; + /// Creates a new instance of the class with the given :literal:`cluster_count` explicit descriptor(std::int64_t cluster_count = 2) { set_cluster_count(cluster_count); } @@ -137,6 +165,8 @@ class descriptor : public detail::descriptor_base { } }; +/// @tparam Task Tag-type that specifies type of the problem to solve. Can +/// be :expr:`task::clustering`. template class model : public base { static_assert(detail::is_valid_task_v); @@ -145,8 +175,12 @@ class model : public base { public: using task_t = Task; + /// Creates a new instance of the class with the default property values. model(); + /// A $k \\times p$ table with the cluster centroids. Each row of the + /// table stores one centroid. + /// @remark default = table{} const table& get_centroids() const; auto& set_centroids(const table& value) { @@ -154,6 +188,9 @@ class model : public base { return *this; } + /// Number of clusters k in the trained model. + /// @invariant :expr:`cluster_count == centroids.row_count` + /// @remark default = 0 std::int64_t get_cluster_count() const; protected: diff --git a/cpp/oneapi/dal/algo/kmeans/infer_types.hpp b/cpp/oneapi/dal/algo/kmeans/infer_types.hpp index 0553dcb4507..be3204c36ab 100644 --- a/cpp/oneapi/dal/algo/kmeans/infer_types.hpp +++ b/cpp/oneapi/dal/algo/kmeans/infer_types.hpp @@ -36,6 +36,8 @@ using v1::infer_result_impl; namespace v1 { +/// @tparam Task Tag-type that specifies type of the problem to solve. Can +/// be :expr:`task::clustering`. template class infer_input : public base { static_assert(detail::is_valid_task_v); @@ -43,8 +45,13 @@ class infer_input : public base { public: using task_t = Task; + /// Creates a new instance of the class with the given :literal:`model` and + /// :literal:`data` infer_input(const model& trained_model, const table& data); + /// An $n \\times p$ table with the data to be assigned to the clusters, + /// where each row stores one feature vector. + /// @remark default = model{} const model& get_model() const; auto& set_model(const model& value) { @@ -52,6 +59,8 @@ class infer_input : public base { return *this; } + /// The trained K-Means model + /// @remark default = table{} const table& get_data() const; auto& set_data(const table& value) { @@ -67,6 +76,8 @@ class infer_input : public base { dal::detail::pimpl> impl_; }; +/// @tparam Task Tag-type that specifies type of the problem to solve. Can +/// be :expr:`task::clustering`. template class infer_result { static_assert(detail::is_valid_task_v); @@ -74,14 +85,22 @@ class infer_result { public: using task_t = Task; + /// Creates a new instance of the class with the default property values. infer_result(); + /// An $n \\times 1$ table with assignments labels to feature + /// vectors in the input data. + /// @remark default = table{} const table& get_labels() const; auto& set_labels(const table& value) { set_labels_impl(value); return *this; } + /// The value of the objective function $\\Phi_X(C)$, where C is + /// defined by the corresponding :expr:`infer_input::model::centroids`. + /// @invariant :expr:`objective_function_value >= 0.0` + /// @remark default = 0.0 double get_objective_function_value() const; auto& set_objective_function_value(double value) { diff --git a/cpp/oneapi/dal/algo/kmeans/train_types.hpp b/cpp/oneapi/dal/algo/kmeans/train_types.hpp index 97f78814a03..ade44d09007 100644 --- a/cpp/oneapi/dal/algo/kmeans/train_types.hpp +++ b/cpp/oneapi/dal/algo/kmeans/train_types.hpp @@ -36,6 +36,8 @@ using v1::train_result_impl; namespace v1 { +/// @tparam Task Tag-type that specifies type of the problem to solve. Can +/// be :expr:`task::clustering`. template class train_input : public base { static_assert(detail::is_valid_task_v); @@ -44,8 +46,13 @@ class train_input : public base { using task_t = Task; train_input(const table& data); + + /// Creates a new instance of the class with the given :literal:`data` and + /// :literal:`initial_centroids` train_input(const table& data, const table& initial_centroids); + /// An $n \\times p$ table with the data to be clustered, where each row + /// stores one feature vector. const table& get_data() const; auto& set_data(const table& data) { @@ -53,6 +60,8 @@ class train_input : public base { return *this; } + /// A $k \\times p$ table with the initial centroids, where each row + /// stores one centroid. const table& get_initial_centroids() const; auto& set_initial_centroids(const table& data) { @@ -68,6 +77,8 @@ class train_input : public base { dal::detail::pimpl> impl_; }; +/// @tparam Task Tag-type that specifies type of the problem to solve. Can +/// be :expr:`task::clustering`. template class train_result { static_assert(detail::is_valid_task_v); @@ -75,8 +86,11 @@ class train_result { public: using task_t = Task; + /// Creates a new instance of the class with the default property values. train_result(); + /// The trained K-means model + /// @remark default = model{} const model& get_model() const; auto& set_model(const model& value) { @@ -84,6 +98,9 @@ class train_result { return *this; } + /// An $n \\times 1$ table with the labels $y_i$ assigned to the + /// samples $x_i$ in the input data, $1 \\leq 1 \\leq n$. + /// @remark default = table{} const table& get_labels() const; auto& set_labels(const table& value) { @@ -91,6 +108,9 @@ class train_result { return *this; } + /// The number of iterations performed by the algorithm. + /// @remark default = 0 + /// @invariant :expr:`iteration_count >= 0` int64_t get_iteration_count() const; auto& set_iteration_count(std::int64_t value) { @@ -98,6 +118,9 @@ class train_result { return *this; } + /// The value of the objective function $\\Phi_X(C)$, where C is + /// :expr:`model.centroids` (see :expr:`kmeans::model::centroids`). + /// @invariant :expr:`objective_function_value >= 0.0` double get_objective_function_value() const; auto& set_objective_function_value(double value) { diff --git a/cpp/oneapi/dal/algo/kmeans_init/common.hpp b/cpp/oneapi/dal/algo/kmeans_init/common.hpp index e43e7d6f684..fcdbac0cca3 100644 --- a/cpp/oneapi/dal/algo/kmeans_init/common.hpp +++ b/cpp/oneapi/dal/algo/kmeans_init/common.hpp @@ -23,7 +23,10 @@ namespace oneapi::dal::kmeans_init { namespace task { namespace v1 { +/// Tag-type that parameterizes entities used for obtaining the initial K-Means centroids. struct init {}; + +/// Alias tag-type for the initialization task. using by_default = init; } // namespace v1 @@ -34,6 +37,8 @@ using v1::by_default; namespace method { namespace v1 { +/// Tag-type that denotes `dense `_ +/// computational method. struct dense {}; struct random_dense {}; struct plus_plus_dense {}; @@ -81,6 +86,9 @@ class descriptor_base : public base { descriptor_base(); + /// The number of clusters k + /// @invariant :expr:`cluster_count > 0` + /// @remark default = 2 std::int64_t get_cluster_count() const; protected: @@ -104,6 +112,13 @@ using v1::is_valid_task_v; namespace v1 { +/// @tparam Float The floating-point type that the algorithm uses for +/// intermediate computations. Can be :expr:`float` or +/// :expr:`double`. +/// @tparam Method Tag-type that specifies an implementation +/// of K-Means Initialization algorithm. +/// @tparam Task Tag-type that specifies the type of the problem to solve. Can +/// be :expr:`task::init`. template ::float_t, typename Method = detail::descriptor_base<>::method_t, typename Task = detail::descriptor_base<>::task_t> @@ -119,6 +134,7 @@ class descriptor : public detail::descriptor_base { using method_t = Method; using task_t = Task; + /// Creates a new instance of the class with the given :literal:`cluster_count` explicit descriptor(std::int64_t cluster_count = 2) { set_cluster_count(cluster_count); } diff --git a/cpp/oneapi/dal/algo/kmeans_init/compute_types.hpp b/cpp/oneapi/dal/algo/kmeans_init/compute_types.hpp index 6d0833feeb6..5cd02c2df83 100644 --- a/cpp/oneapi/dal/algo/kmeans_init/compute_types.hpp +++ b/cpp/oneapi/dal/algo/kmeans_init/compute_types.hpp @@ -36,6 +36,8 @@ using v1::compute_result_impl; namespace v1 { +/// @tparam Task Tag-type that specifies type of the problem to solve. Can +/// be :expr:`task::init`. template class compute_input : public base { static_assert(detail::is_valid_task_v); @@ -43,8 +45,12 @@ class compute_input : public base { public: using task_t = Task; + /// Creates a new instance of the class with the given :literal:`data`. compute_input(const table& data); + /// An $n \\times p$ table with the data to be clustered, where each row + /// stores one feature vector. + /// @remark default = table{} const table& get_data() const; auto& set_data(const table& data) { @@ -58,6 +64,8 @@ class compute_input : public base { dal::detail::pimpl> impl_; }; +/// @tparam Task Tag-type that specifies type of the problem to solve. Can +/// be :expr:`task::clustering`. template class compute_result { static_assert(detail::is_valid_task_v); @@ -65,8 +73,12 @@ class compute_result { public: using task_t = Task; + /// Creates a new instance of the class with the default property values. compute_result(); + /// A $k \\times p$ table with the initial centroids. Each row of the + /// table stores one centroid. + /// @remark default = table{} const table& get_centroids() const; auto& set_centroids(const table& value) { diff --git a/cpp/oneapi/dal/algo/knn/common.hpp b/cpp/oneapi/dal/algo/knn/common.hpp index 9a75d50427b..c3df0bdd3e7 100644 --- a/cpp/oneapi/dal/algo/knn/common.hpp +++ b/cpp/oneapi/dal/algo/knn/common.hpp @@ -23,7 +23,11 @@ namespace oneapi::dal::knn { namespace task { namespace v1 { +/// Tag-type that parameterizes entities used for solving +/// :capterm:`classification problem `. struct classification {}; + +/// Alias tag-type for classification task. using by_default = classification; } // namespace v1 @@ -34,8 +38,15 @@ using v1::by_default; namespace method { namespace v1 { +/// Tag-type that denotes `k-d tree `_ computational method. struct kd_tree {}; + +/// Tag-type that denotes `brute-force `_ computational +/// method. struct brute_force {}; + +/// Alias tag-type for `brute-force `_ computational +/// method. using by_default = brute_force; } // namespace v1 @@ -76,7 +87,12 @@ class descriptor_base : public base { descriptor_base(); + /// The number of classes c + /// @invariant :expr:`class_count > 1` std::int64_t get_class_count() const; + + /// The number of neighbors k + /// @invariant :expr:`neighbor_count > 0` std::int64_t get_neighbor_count() const; protected: @@ -102,6 +118,13 @@ using v1::is_valid_task_v; namespace v1 { +/// @tparam Float The floating-point type that the algorithm uses for +/// intermediate computations. Can be :expr:`float` or +/// :expr:`double`. +/// @tparam Method Tag-type that specifies an implementation of algorithm. Can +/// be :expr:`method::bruteforce` or :expr:`method::kd_tree`. +/// @tparam Task Tag-type that specifies type of the problem to solve. Can +/// be :expr:`task::classification`. template ::float_t, typename Method = detail::descriptor_base<>::method_t, typename Task = detail::descriptor_base<>::task_t> @@ -117,6 +140,8 @@ class descriptor : public detail::descriptor_base { using method_t = Method; using task_t = Task; + /// Creates a new instance of the class with the given :literal:`class_count` + /// and :literal:`neighbor_count` property values explicit descriptor(std::int64_t class_count, std::int64_t neighbor_count) { set_class_count(class_count); set_neighbor_count(neighbor_count); @@ -133,12 +158,15 @@ class descriptor : public detail::descriptor_base { } }; +/// @tparam Task Tag-type that specifies type of the problem to solve. Can +/// be :expr:`task::classification`. template class model : public base { static_assert(detail::is_valid_task_v); friend dal::detail::pimpl_accessor; public: + /// Creates a new instance of the class with the default property values. model(); private: diff --git a/cpp/oneapi/dal/algo/knn/infer_types.hpp b/cpp/oneapi/dal/algo/knn/infer_types.hpp index 7eb329be8da..b192897ca39 100644 --- a/cpp/oneapi/dal/algo/knn/infer_types.hpp +++ b/cpp/oneapi/dal/algo/knn/infer_types.hpp @@ -36,6 +36,8 @@ using v1::infer_result_impl; namespace v1 { +/// @tparam Task Tag-type that specifies type of the problem to solve. Can +/// be :expr:`task::classification`. template class infer_input : public base { static_assert(detail::is_valid_task_v); @@ -43,8 +45,12 @@ class infer_input : public base { public: using task_t = Task; + /// Creates a new instance of the class with the given :literal:`model` + /// and :literal:`data` property values infer_input(const table& data, const model& model); + /// The dataset for inference $X'$ + /// @remark default = table{} const table& get_data() const; auto& set_data(const table& data) { @@ -52,6 +58,8 @@ class infer_input : public base { return *this; } + /// The trained k-NN model + /// @remark default = model{} const model& get_model() const; auto& set_model(const model& m) { @@ -67,6 +75,8 @@ class infer_input : public base { dal::detail::pimpl> impl_; }; +/// @tparam Task Tag-type that specifies type of the problem to solve. Can +/// be :expr:`task::classification`. template class infer_result { static_assert(detail::is_valid_task_v); @@ -74,8 +84,11 @@ class infer_result { public: using task_t = Task; + /// Creates a new instance of the class with the default property values. infer_result(); + /// The predicted labels + /// @remark default = table{} const table& get_labels() const; auto& set_labels(const table& value) { diff --git a/cpp/oneapi/dal/algo/knn/train_types.hpp b/cpp/oneapi/dal/algo/knn/train_types.hpp index 4818ed431c7..dcfc9418bf4 100644 --- a/cpp/oneapi/dal/algo/knn/train_types.hpp +++ b/cpp/oneapi/dal/algo/knn/train_types.hpp @@ -36,6 +36,8 @@ using v1::train_result_impl; namespace v1 { +/// @tparam Task Tag-type that specifies type of the problem to solve. Can +/// be :expr:`task::classification`. template class train_input : public base { static_assert(detail::is_valid_task_v); @@ -43,8 +45,12 @@ class train_input : public base { public: using task_t = Task; + /// Creates a new instance of the class with the given :literal:`data` + /// and :literal:`labels` property values train_input(const table& data, const table& labels); + /// The training set X + /// @remark default = table{} const table& get_data() const; auto& set_data(const table& data) { @@ -52,6 +58,8 @@ class train_input : public base { return *this; } + /// Vector of labels y for the training set X + /// @remark default = table{} const table& get_labels() const; auto& set_labels(const table& labels) { @@ -67,6 +75,8 @@ class train_input : public base { dal::detail::pimpl> impl_; }; +/// @tparam Task Tag-type that specifies type of the problem to solve. Can +/// be :expr:`task::classification`. template class train_result { static_assert(detail::is_valid_task_v); @@ -74,8 +84,11 @@ class train_result { public: using task_t = Task; + /// Creates a new instance of the class with the default property values. train_result(); + /// The trained k-NN model + /// @remark default = model{} const model& get_model() const; auto& set_model(const model& value) { diff --git a/cpp/oneapi/dal/algo/pca/common.hpp b/cpp/oneapi/dal/algo/pca/common.hpp index c31507796c2..7999c545337 100644 --- a/cpp/oneapi/dal/algo/pca/common.hpp +++ b/cpp/oneapi/dal/algo/pca/common.hpp @@ -23,7 +23,11 @@ namespace oneapi::dal::pca { namespace task { namespace v1 { +/// Tag-type that parameterizes entities used for solving +/// :capterm:`dimensionality reduction problem `. struct dim_reduction {}; + +/// Alias tag-type for dimensionality reduction task. using by_default = dim_reduction; } // namespace v1 @@ -34,8 +38,15 @@ using v1::by_default; namespace method { namespace v1 { +/// Tag-type that denotes `Covariance `_ computational +/// method. struct cov {}; + +/// Tag-type that denotes `SVD `_ computational method. struct svd {}; + +/// Alias tag-type for `Covariance `_ computational +/// method. using by_default = cov; } // namespace v1 @@ -76,7 +87,15 @@ class descriptor_base : public base { descriptor_base(); + /// The number of principal components :literal:`r`. If it is zero, the algorithm + /// computes the eigenvectors for all features, $r = p$. + /// @remark default = 0 + /// @invariant :expr:`component_count >= 0` std::int64_t get_component_count() const; + + /// Specifies whether the algorithm applies the `Sign-flip technique`_. + /// If it is `true`, the directions of the eigenvectors must be deterministic. + /// @remark default = true bool get_deterministic() const; protected: @@ -102,6 +121,13 @@ using v1::is_valid_task_v; namespace v1 { +/// @tparam Float The floating-point type that the algorithm uses for +/// intermediate computations. Can be :expr:`float` or +/// :expr:`double`. +/// @tparam Method Tag-type that specifies an implementation of algorithm. Can +/// be :expr:`method::cov` or :expr:`method::svd`. +/// @tparam Task Tag-type that specifies type of the problem to solve. Can +/// be :expr:`task::dim_reduction`. template ::float_t, typename Method = detail::descriptor_base<>::method_t, typename Task = detail::descriptor_base<>::task_t> @@ -117,6 +143,8 @@ class descriptor : public detail::descriptor_base { using method_t = Method; using task_t = Task; + /// Creates a new instance of the class with the given :literal:`component_count` + /// property value explicit descriptor(std::int64_t component_count = 0) { set_component_count(component_count); } @@ -132,6 +160,8 @@ class descriptor : public detail::descriptor_base { } }; +/// @tparam Task Tag-type that specifies type of the problem to solve. Can +/// be :expr:`task::dim_reduction`. template class model : public base { static_assert(detail::is_valid_task_v); @@ -140,8 +170,12 @@ class model : public base { public: using task_t = Task; + /// Creates a new instance of the class with the default property values. model(); + /// An $r \\times p$ table with the eigenvectors. Each row contains one + /// eigenvector. + /// @remark default = table{} const table& get_eigenvectors() const; auto& set_eigenvectors(const table& value) { diff --git a/cpp/oneapi/dal/algo/pca/infer_types.hpp b/cpp/oneapi/dal/algo/pca/infer_types.hpp index 0d9b6a7fa3a..03bb2553b75 100644 --- a/cpp/oneapi/dal/algo/pca/infer_types.hpp +++ b/cpp/oneapi/dal/algo/pca/infer_types.hpp @@ -36,6 +36,8 @@ using v1::infer_result_impl; namespace v1 { +/// @tparam Task Tag-type that specifies type of the problem to solve. Can +/// be :expr:`task::dim_reduction`. template class infer_input : public base { static_assert(detail::is_valid_task_v); @@ -43,8 +45,12 @@ class infer_input : public base { public: using task_t = Task; + /// Creates a new instance of the class with the given :literal:`model` + /// and :literal:`data` property values infer_input(const model& trained_model, const table& data); + /// The trained PCA model + /// @remark default = model{} const model& get_model() const; auto& set_model(const model& value) { @@ -52,6 +58,8 @@ class infer_input : public base { return *this; } + /// The dataset for inference $X'$ + /// @remark default = table{} const table& get_data() const; auto& set_data(const table& value) { @@ -67,6 +75,8 @@ class infer_input : public base { dal::detail::pimpl> impl_; }; +/// @tparam Task Tag-type that specifies type of the problem to solve. Can +/// be :expr:`task::dim_reduction`. template class infer_result { static_assert(detail::is_valid_task_v); @@ -74,8 +84,12 @@ class infer_result { public: using task_t = Task; + /// Creates a new instance of the class with the default property values. infer_result(); + /// An $n \\times r$ table that contains data projected to the :literal:`r` + /// principal components. + /// @remark default = table{} const table& get_transformed_data() const; auto& set_transformed_data(const table& value) { diff --git a/cpp/oneapi/dal/algo/pca/train_types.hpp b/cpp/oneapi/dal/algo/pca/train_types.hpp index 080fafafbbb..24d20edf732 100644 --- a/cpp/oneapi/dal/algo/pca/train_types.hpp +++ b/cpp/oneapi/dal/algo/pca/train_types.hpp @@ -36,6 +36,8 @@ using v1::train_result_impl; namespace v1 { +/// @tparam Task Tag-type that specifies type of the problem to solve. Can +/// be :expr:`task::dim_reduction`. template class train_input : public base { static_assert(detail::is_valid_task_v); @@ -43,8 +45,13 @@ class train_input : public base { public: using task_t = Task; + /// Creates a new instance of the class with the given :literal:`data` + /// property value train_input(const table& data); + /// An $n \\times p$ table with the training data, where each row stores one + /// feature vector. + /// @remark default = table{} const table& get_data() const; auto& set_data(const table& data) { @@ -59,6 +66,8 @@ class train_input : public base { dal::detail::pimpl> impl_; }; +/// @tparam Task Tag-type that specifies type of the problem to solve. Can +/// be :expr:`task::dim_reduction`. template class train_result { static_assert(detail::is_valid_task_v); @@ -66,10 +75,17 @@ class train_result { public: using task_t = Task; + /// Creates a new instance of the class with the default property values. train_result(); + /// An $r \\times p$ table with the eigenvectors. Each row contains one + /// eigenvector. + /// @remark default = table{} + /// @invariant :expr:`eigenvectors == model.eigenvectors` const table& get_eigenvectors() const; + /// The trained PCA model + /// @remark default = model{} const model& get_model() const; auto& set_model(const model& value) { @@ -77,6 +93,9 @@ class train_result { return *this; } + /// A $1 \\times r$ table that contains the eigenvalues for for the first + /// :literal:`r` features. + /// @remark default = table{} const table& get_eigenvalues() const; auto& set_eigenvalues(const table& value) { @@ -84,6 +103,9 @@ class train_result { return *this; } + /// A $1 \\times r$ table that contains the variances for the first :literal:`r` + /// features. + /// @remark default = table{} const table& get_variances() const; auto& set_variances(const table& value) { @@ -91,6 +113,9 @@ class train_result { return *this; } + /// A $1 \\times r$ table that contains the mean values for the first :literal:`r` + /// features. + /// @remark default = table{} const table& get_means() const; auto& set_means(const table& value) { diff --git a/cpp/oneapi/dal/array.hpp b/cpp/oneapi/dal/array.hpp index a8707ab946d..a759a309e5a 100644 --- a/cpp/oneapi/dal/array.hpp +++ b/cpp/oneapi/dal/array.hpp @@ -24,6 +24,10 @@ namespace oneapi::dal { namespace v1 { +/// @tparam T The type of the memory block elements within the array. +/// :literal:`T` can represent any type. +/// +/// @pre :literal:`T` cannot be const-qualified. template class array { static_assert(!std::is_const_v, "array class cannot have const-qualified type of data"); @@ -37,6 +41,12 @@ class array { using data_t = T; public: + /// Allocates a new memory block for mutable data, does not initialize it, + /// creates a new array instance by passing a pointer to the memory block. + /// The array owns the memory block (for details, see :txtref:`data_ownership_requirements`). + /// + /// @param count The number of elements of type :literal:`Data` to allocate memory for. + /// @pre :expr:`count > 0` static array empty(std::int64_t count) { return array{ impl_t::empty(detail::default_host_policy{}, count, detail::host_allocator()) @@ -44,6 +54,15 @@ class array { } #ifdef ONEDAL_DATA_PARALLEL + + /// Allocates a new memory block for mutable data, does not initialize it, + /// creates a new array instance by passing a pointer to the memory block. + /// The array owns the memory block (for details, see :txtref:`data_ownership_requirements`). + /// + /// @param queue The SYCL* queue object. + /// @param count The number of elements of type :literal:`T` to allocate memory for. + /// @param alloc The kind of USM to be allocated. + /// @pre :expr:`count > 0` static array empty(const sycl::queue& queue, std::int64_t count, const sycl::usm::alloc& alloc = sycl::usm::alloc::shared) { @@ -53,6 +72,16 @@ class array { } #endif + /// Allocates a new memory block for mutable data, fills it with a scalar value, + /// creates a new array instance by passing a pointer to the memory block. + /// The array owns the memory block (for details, see :txtref:`data_ownership_requirements`). + /// + /// @tparam Element The type from which array elements of type :literal:`T` can be constructed. + /// + /// @param count The number of elements of type :literal:`T` to allocate memory for. + /// @param element The value that is used to fill a memory block. + /// @pre :expr:`count > 0` + /// @pre Elements of type ``T`` are constructible from the ``Element`` type. template static array full(std::int64_t count, K&& element) { return array{ impl_t::full(detail::default_host_policy{}, @@ -62,6 +91,18 @@ class array { } #ifdef ONEDAL_DATA_PARALLEL + /// Allocates a new memory block for mutable data, fills it with a scalar value, + /// creates a new array instance by passing a pointer to the memory block. + /// The array owns the memory block (for details, see :txtref:`data_ownership_requirements`). + /// + /// @tparam Element The type from which array elements of type :literal:`Data` can be constructed. + /// + /// @param queue The SYCL* queue object. + /// @param count The number of elements of type :literal:`Data` to allocate memory for. + /// @param element The value that is used to fill a memory block. + /// @param alloc The kind of USM to be allocated. + /// @pre :expr:`count > 0` + /// @pre Elements of type ``Data`` are constructible from the ``Element`` type. template static array full(sycl::queue& queue, std::int64_t count, @@ -74,6 +115,12 @@ class array { } #endif + /// Allocates a new memory block on mutable data, fills it with zeros, + /// creates a new array instance by passing a pointer to the memory block. + /// The array owns the memory block (for details, see :txtref:`data_ownership_requirements`). + /// + /// @param count The number of elements of type :literal:`Data` to allocate memory for. + /// @pre :expr:`count > 0` static array zeros(std::int64_t count) { // TODO: can be optimized in future return array{ @@ -82,6 +129,15 @@ class array { } #ifdef ONEDAL_DATA_PARALLEL + + /// Allocates a new memory block on mutable data, fills it with zeros, + /// creates a new array instance by passing a pointer to the memory block. + /// The array owns the memory block (for details, see :txtref:`data_ownership_requirements`). + /// + /// @param queue The SYCL* queue object. + /// @param count The number of elements of type :literal:`T` to allocate memory for. + /// @param alloc The kind of USM to be allocated. + /// @pre :expr:`count > 0`s static array zeros(sycl::queue& queue, std::int64_t count, const sycl::usm::alloc& alloc = sycl::usm::alloc::shared) { @@ -92,12 +148,31 @@ class array { detail::data_parallel_allocator(queue, alloc)) }; } #endif + + /// Creates a new array instance by passing the pointer to externally-allocated memory block + /// for mutable data. It is the responsibility of the calling application to free the memory block + /// as the array does not free it when the reference count is zero. + /// + /// @param data The pointer to externally-allocated memory block. + /// @param count The number of elements of type :literal:`Data` in the memory block. + /// @pre :expr:`data != nullptr` + /// @pre :expr:`count > 0` template static array wrap(Y* data, std::int64_t count) { return array{ data, count, dal::detail::empty_delete{} }; } #ifdef ONEDAL_DATA_PARALLEL + + /// Creates a new array instance by passing the pointer to externally-allocated memory block + /// for mutable data. It is the responsibility of the calling application to free the memory block + /// as the array does not free it when the reference count is zero. + /// + /// @param data The pointer to externally-allocated memory block. + /// @param count The number of elements of type :literal:`T` in the memory block. + /// @param dependencies Events indicating availability of the :literal:`Data` for reading or writing. + /// @pre :expr:`data != nullptr` + /// @pre :expr:`count > 0` template static array wrap(Y* data, std::int64_t count, @@ -107,25 +182,51 @@ class array { #endif public: + /// Creates a new instance of the class without memory allocation: + /// :expr:`mutable_data` and :expr:`data` pointers should be set to ``nullptr``, + /// :expr:`count` should be zero; the pointer to the ownership structure should be set to ``nullptr``. array() : impl_(new impl_t()) { const T* null_data = nullptr; update_data(null_data, 0); } + /// Creates a new array instance that shares an ownership with :literal:`other` on its memory block. array(const array& a) : impl_(new impl_t(*a.impl_)) { update_data(impl_.get()); } + /// Moves :expr:`data`, :expr:`mutable_data` pointers, :expr:`count`, and pointer to the ownership structure + /// in :literal:`other` to the new array instance array(array&& a) : impl_(std::move(a.impl_)) { update_data(impl_.get()); } + /// Creates a new array instance which owns a memory block of externally-allocated mutable data. + /// The ownership structure is created for a block, the input :literal:`deleter` + /// is assigned to it. + /// + /// @tparam Deleter The type of a deleter used to free the :literal:`Data`. + /// The deleter provides ``void operator()(Data*)`` member function. + /// + /// @param data The pointer to externally-allocated memory block. + /// @param count The number of elements of type :literal:`Data` in the memory block. + /// @param deleter The object used to free :literal:`Data`. template explicit array(T* data, std::int64_t count, Deleter&& deleter) : impl_(new impl_t(data, count, std::forward(deleter))) { update_data(impl_.get()); } + /// Creates a new array instance which owns a memory block of externally-allocated immutable data. + /// The ownership structure is created for a block, the input :literal:`deleter` + /// is assigned to it. + /// + /// @tparam ConstDeleter The type of a deleter used to free the :literal:`Data`. + /// The deleter implements ``void operator()(const Data*)`` member function. + /// + /// @param data The pointer to externally-allocated memory block. + /// @param count The number of elements of type :literal:`Data` in the :literal:`Data`. + /// @param deleter The object used to free :literal:`Data`. template explicit array(const T* data, std::int64_t count, ConstDeleter&& deleter) : impl_(new impl_t(data, count, std::forward(deleter))) { @@ -133,6 +234,18 @@ class array { } #ifdef ONEDAL_DATA_PARALLEL + /// Creates a new array instance which owns a memory block of externally-allocated mutable data. + /// The ownership structure is created for a block, the input :literal:`deleter` + /// is assigned to it. + /// + /// @tparam Deleter The type of a deleter used to free the :literal:`Data`. + /// The deleter provides ``void operator()(T*)`` member function. + /// + /// @param queue The SYCL* queue object. + /// @param data The pointer to externally-allocated memory block. + /// @param count The number of elements of type :literal:`T` in the memory block. + /// @param deleter The object used to free :literal:`Data`. + /// @param dependencies Events that indicate when :literal:`Data` becomes ready to be read or written template explicit array(const sycl::queue& queue, T* data, @@ -144,6 +257,17 @@ class array { detail::wait_and_throw(dependencies); } + /// Creates the ownership structure for memory block of externally-allocated immutable data, + /// assigns input :literal:`deleter` object to it, + /// sets :expr:`data` pointer to this block. + /// + /// @tparam ConstDeleter The type of a deleter used to free. + /// The deleter implements `void operator()(const T*)`` member function. + /// + /// @param data The immutable memory block pointer to be assigned inside the array + /// @param count The number of elements of type :literal:`T` into the block + /// @param deleter The object used to free :literal:`Data`. + /// @param dependencies Events indicating availability of the :literal:`Data` for reading or writing. template explicit array(const sycl::queue& queue, const T* data, @@ -156,23 +280,49 @@ class array { } #endif + /// An aliasing constructor: creates a new array instance that stores :literal:`Data` pointer, + /// assigns the pointer to the ownership structure of :literal:`ref` to the new instance. + /// Array returns :literal:`Data` pointer as its mutable or immutable block depending + /// on the :literal:`Data` type. + /// + /// @tparam ref The type of elements in the referenced array. + /// @tparam data Either :literal:`T` or $const T$ type. + /// + /// @param ref The array which shares ownership structure with created + /// one. + /// @param data Mutable or immutable unmanaged pointer hold by + /// created array. + /// @param count The number of elements of type :literal:`T` in the :literal:`Data`. + /// + /// @pre :expr:`std::is_same_v || std::is_same_v` template explicit array(const array& ref, K* data, std::int64_t count) : impl_(new impl_t(*ref.impl_, data, count)) { update_data(impl_.get()); } + /// Replaces the :expr:`data`, :expr:`mutable_data` pointers, :expr:`count`, and pointer + /// to the ownership structure in the array instance by the values in :literal:`other`. + /// + /// @post :expr:`data == other.data` + /// @post :expr:`mutable_data == other.mutable_data` + /// @post :expr:`count == other.count` array operator=(const array& other) { array tmp{ other }; swap(*this, tmp); return *this; } + /// Swaps the values of :expr:`data`, :expr:`mutable_data` pointers, :expr:`count`, and pointer + /// to the ownership structure in the array instance and :literal:`other`. array operator=(array&& other) { swap(*this, other); return *this; } + /// The pointer to the memory block holding mutable data. + /// @pre :expr:`has_mutable_data() == true`, othewise throws `domain_error` + /// @invariant :expr:`mutable_data != nullptr` if :expr:`has_mutable_data() && count > 0` T* get_mutable_data() const { if (!has_mutable_data()) { throw domain_error(dal::detail::error_messages::array_does_not_contain_mutable_data()); @@ -180,14 +330,26 @@ class array { return mutable_data_ptr_; } + /// The pointer to the memory block holding immutable data. + /// @invariant :expr:`data != nullptr` if :expr:`count > 0` + /// @invariant if :expr:`has_mutable_data() == true` then :expr:`data == mutable_data` const T* get_data() const noexcept { return data_ptr_; } + /// Returns whether array contains :expr:`mutable_data` or not + /// + /// @invariant :expr:`mutable_data != nullptr` if this returns `true` and :expr:`count > 0` bool has_mutable_data() const noexcept { return mutable_data_ptr_ != nullptr; } + /// Returns mutable_data, if array contains it. Otherwise, allocates a + /// memory block for mutable data and fills it with the data stored at :expr:`data`. + /// Creates the ownership structure for allocated memory block and stores + /// the pointer. + /// + /// @post :expr:`has_mutable_data() == true` array& need_mutable_data() { impl_->need_mutable_data(detail::default_host_policy{}, detail::host_allocator{}); update_data(impl_->get_mutable_data(), impl_->get_count()); @@ -195,6 +357,15 @@ class array { } #ifdef ONEDAL_DATA_PARALLEL + /// Returns mutable_data, if array contains it. Otherwise, allocates a + /// memory block for mutable data and fills it with the data stored at :expr:`data`. + /// Creates the ownership structure for allocated memory block and stores + /// the pointer. + /// + /// @param queue The SYCL* queue object. + /// @param alloc The kind of USM to be allocated + /// + /// @post :expr:`has_mutable_data() == true` array& need_mutable_data(sycl::queue& queue, const sycl::usm::alloc& alloc = sycl::usm::alloc::shared) { impl_->need_mutable_data(detail::data_parallel_policy{ queue }, @@ -204,26 +375,43 @@ class array { } #endif + /// The number of elements of type :literal:`T` in a memory block std::int64_t get_count() const noexcept { return count_; } + /// The size of memory block in bytes + /// @invariant :expr:`size == count * sizeof(T)` std::int64_t get_size() const noexcept { return count_ * sizeof(T); } + /// Resets ownership structure pointer to ``nullptr``, + /// sets :expr:`count` to zero, :expr:`data` and :expr:`mutable_data` to :expr:`nullptr`. void reset() { impl_->reset(); const T* null_data = nullptr; update_data(null_data, 0); } + /// Allocates a new memory block for mutable data, does not initialize it, + /// creates ownership structure for this block, assigns the structure inside the array. + /// The array owns allocated memory block. + /// + /// @param count The number of elements of type :literal:`Data` to allocate memory for. void reset(std::int64_t count) { impl_->reset(detail::default_host_policy{}, count, detail::host_allocator{}); update_data(impl_->get_mutable_data(), count); } #ifdef ONEDAL_DATA_PARALLEL + /// Allocates a new memory block for mutable data, does not initialize it, + /// creates ownership structure for this block, assigns the structure inside the array. + /// The array owns allocated memory block. + /// + /// @param queue The SYCL* queue object. + /// @param count The number of elements of type :literal:`T` to allocate memory for. + /// @param alloc The kind of USM to be allocated void reset(const sycl::queue& queue, std::int64_t count, const sycl::usm::alloc& alloc = sycl::usm::alloc::shared) { @@ -234,6 +422,16 @@ class array { } #endif + /// Creates the ownership structure for memory block of externally-allocated mutable data, + /// assigns input :literal:`deleter` object to it, + /// sets :expr:`data` and :expr:`mutable_data` pointers to this block. + /// + /// @tparam Deleter The type of a deleter used to free the :literal:`Data`. + /// The deleter implements ``void operator()(Data*)`` member function. + /// + /// @param data The mutable memory block pointer to be assigned inside the array + /// @param count The number of elements of type :literal:`Data` into the block + /// @param deleter The object used to free :literal:`Data`. template void reset(T* data, std::int64_t count, Deleter&& deleter) { // TODO: check input parameters @@ -241,6 +439,16 @@ class array { update_data(data, count); } + /// Creates the ownership structure for memory block of externally-allocated immutable data, + /// assigns input :literal:`deleter` object to it, + /// sets :expr:`data` pointer to this block. + /// + /// @tparam ConstDeleter The type of a deleter used to free. + /// The deleter implements `void operator()(const Data*)`` member function. + /// + /// @param data The immutable memory block pointer to be assigned inside the array + /// @param count The number of elements of type :literal:`Data` into the block + /// @param deleter The object used to free :literal:`Data`. template void reset(const T* data, std::int64_t count, ConstDeleter&& deleter) { // TODO: check input parameters @@ -259,18 +467,40 @@ class array { } #endif + /// Initializes :expr:`data` and :expr:`mutable_data` with data pointer, + /// :expr:`count` with input :literal:`count` value, initializes + /// the pointer to ownership structure with the one from ref. Array + /// returns :literal:`Data` pointer as its mutable block. + + /// @tparam ref The type of elements in the referenced array. + /// + /// @param ref The array which is used to share ownership structure with current one. + /// @param data Mutable unmanaged pointer to be assigned to the array. + /// @param count The number of elements of type :literal:`T` in the :literal:`Data`. template void reset(const array& ref, T* data, std::int64_t count) { impl_->reset(*ref.impl_, data, count); update_data(data, count); } + /// Initializes :expr:`data` with data pointer, + /// :expr:`count` with input :literal:`count` value, initializes + /// the pointer to ownership structure with the one from ref. Array + /// returns :literal:`Data` pointer as its immutable block. + /// + /// @tparam ref The type of elements in the referenced array. + /// + /// @param ref The array which is used to share ownership structure with current one. + /// @param data Immutable unmanaged pointer to be assigned to the array. + /// @param count The number of elements of type :literal:`T` in the :literal:`Data`. template void reset(const array& ref, const T* data, std::int64_t count) { impl_->reset(*ref.impl_, data, count); update_data(data, count); } + /// Provides a read-only access to the elements of array. + /// Does not perform boundary checks. const T& operator[](std::int64_t index) const noexcept { // TODO: add asserts on data_ptr_ return data_ptr_[index]; diff --git a/cpp/oneapi/dal/table/column_accessor.hpp b/cpp/oneapi/dal/table/column_accessor.hpp index 00b493ef36a..4c55e8c6134 100644 --- a/cpp/oneapi/dal/table/column_accessor.hpp +++ b/cpp/oneapi/dal/table/column_accessor.hpp @@ -22,6 +22,9 @@ namespace oneapi::dal { namespace v1 { +/// @tparam T The type of data values in blocks returned by the accessor. +/// Should be const-qualified for read-only access. +/// An accessor supports at least :expr:`float`, :expr:`double`, and :expr:`std::int32_t` types of :literal:`T`. template class column_accessor : private detail::accessor_base { using base = detail::accessor_base; @@ -31,6 +34,10 @@ class column_accessor : private detail::accessor_base || @@ -46,6 +53,19 @@ class column_accessor : private detail::accessor_base pull(sycl::queue& queue, std::int64_t column_index, const range& rows = { 0, -1 }, @@ -64,6 +84,22 @@ class column_accessor : private detail::accessor_base& block, std::int64_t column_index, diff --git a/cpp/oneapi/dal/table/common.hpp b/cpp/oneapi/dal/table/common.hpp index 827ac55886e..7578f32ca95 100644 --- a/cpp/oneapi/dal/table/common.hpp +++ b/cpp/oneapi/dal/table/common.hpp @@ -62,11 +62,26 @@ class ONEDAL_EXPORT table_metadata { using pimpl = detail::pimpl; public: + /// Creates the metadata instance without information about the features. + /// The :expr:`feature_count` sshould be set to zero. + /// The :expr:`data_type` and :expr:`feature_type` properties should not be initialized. table_metadata(); + + /// Creates the metadata instance from external information about the data types and the + /// feature types. + /// @param dtypes The data types of the features. Assigned into the :expr:`data_type` property. + /// @param ftypes The feature types. Assigned into the :expr:`feature_type` property. + /// @pre :expr:`dtypes.get_count() == ftypes.get_count()` table_metadata(const array& dtypes, const array& ftypes); + /// The number of features that metadata contains information about + /// @pre :expr:`feature_count >= 0` std::int64_t get_feature_count() const; + + /// Feature types in the metadata object. Should be within the range ``[0, feature_count)`` const feature_type& get_feature_type(std::int64_t feature_index) const; + + /// Data types of the features in the metadata object. Should be within the range ``[0, feature_count)`` const data_type& get_data_type(std::int64_t feature_index) const; private: @@ -81,8 +96,15 @@ class ONEDAL_EXPORT table { using pimpl = detail::pimpl; public: + /// An empty table constructor: creates the table instance with zero number of rows and columns. + /// Implementation is set to the special "empty" object that returns all the property values + /// set to default (see Properties section). table(); + + /// Creates a new table instance that shares the implementation with another one. table(const table&) = default; + + /// Creates a new table instance and moves implementation from another one into it. table(table&&); template (impl))); } + /// Replaces the implementation by another one. table& operator=(const table&) = default; + + /// Swaps the implementation of this object and another one. table& operator=(table&&); + /// Indicates whether a table contains non-zero number of rows and columns. bool has_data() const noexcept; + + /// The number of columns in the table. + /// @remark default = 0 std::int64_t get_column_count() const; + + /// The number of rows in the table. + /// @remark default = 0 std::int64_t get_row_count() const; + + /// The metadata object that holds additional information + /// about the data within the table. + /// @remark default = table_metadata() const table_metadata& get_metadata() const; + + /// The runtime id of the table type. + /// Each table sub-type has its unique ``kind``. + /// An empty table (see the default constructor) has a unique ``kind`` value as well. + /// @remark default = empty_table_kind std::int64_t get_kind() const; + + /// The layout of the data within the table + /// @remark default = data_layout::unknown data_layout get_data_layout() const; protected: diff --git a/cpp/oneapi/dal/table/homogen.hpp b/cpp/oneapi/dal/table/homogen.hpp index 40f55fa9f0d..46726205d61 100644 --- a/cpp/oneapi/dal/table/homogen.hpp +++ b/cpp/oneapi/dal/table/homogen.hpp @@ -53,8 +53,24 @@ class ONEDAL_EXPORT homogen_table : public table { using pimpl = detail::pimpl; public: + /// Returns the unique id of ``homogen_table`` class. static std::int64_t kind(); + /// Creates a new ``homogen_table`` instance from externally-defined data block. Table + /// object refers to the data but does not own it. The responsibility to + /// free the data remains on the user side. + /// The :expr:`data` should point to the ``data_pointer`` memory block. + /// + /// @tparam Data The type of elements in the data block that will be stored into the table. + /// The table initializes data types of metadata with this data type. + /// The feature types should be set to default values for :literal:`Data` type: contiguous for floating-point, + /// ordinal for integer types. + /// The :literal:`Data` type should be at least :expr:`float`, :expr:`double` or :expr:`std::int32_t`. + /// @param data_pointer The pointer to a homogeneous data block. + /// @param row_count The number of rows in the table. + /// @param column_count The number of columns in the table. + /// @param layout The layout of the data. Should be ``data_layout::row_major`` or + /// ``data_layout::column_major``. template static homogen_table wrap(const Data* data_pointer, std::int64_t row_count, @@ -68,6 +84,23 @@ class ONEDAL_EXPORT homogen_table : public table { } #ifdef ONEDAL_DATA_PARALLEL + /// Creates a new ``homogen_table`` instance from externally-defined data block. Table + /// object refers to the data but does not own it. The responsibility to + /// free the data remains on the user side. + /// The :expr:`data` should point to the ``data_pointer`` memory block. + /// + /// @tparam Data The type of elements in the data block that will be stored into the table. + /// The table initializes data types of metadata with this data type. + /// The feature types should be set to default values for :literal:`Data` type: contiguous for floating-point, + /// ordinal for integer types. + /// The :literal:`Data` type should be at least :expr:`float`, :expr:`double` or :expr:`std::int32_t`. + /// @param queue The SYCL* queue object + /// @param data_pointer The pointer to a homogeneous data block. + /// @param row_count The number of rows in the table. + /// @param column_count The number of columns in the table. + /// @param dependencies Events indicating availability of the :literal:`Data` for reading or writing. + /// @param layout The layout of the data. Should be ``data_layout::row_major`` or + /// ``data_layout::column_major``. template static homogen_table wrap(const sycl::queue& queue, const Data* data_pointer, @@ -86,6 +119,9 @@ class ONEDAL_EXPORT homogen_table : public table { #endif public: + /// Creates a new ``homogen_table`` instance with zero number of rows and columns. + /// The :expr:`kind` is set to``homogen_table::kind()``. + /// All the properties should be set to default values (see the Properties section). homogen_table(); template (impl)); } + /// Creates a new ``homogen_table`` instance from externally-defined data block. + /// Table object owns the data pointer. + /// The :expr:`data` should point to the ``data_pointer`` memory block. + /// + /// @tparam Data The type of elements in the data block that will be stored into the table. + /// The :literal:`Data` type should be at least :expr:`float`, :expr:`double` or :expr:`std::int32_t`. + /// @tparam ConstDeleter The type of a deleter called on ``data_pointer`` when + /// the last table that refers it is out of the scope. + /// + /// @param data_pointer The pointer to a homogeneous data block. + /// @param row_count The number of rows in the table. + /// @param column_count The number of columns in the table. + /// @param data_deleter The deleter that is called on the ``data_pointer`` when the last table that refers it + /// is out of the scope. + /// @param layout The layout of the data. Should be ``data_layout::row_major`` or + /// ``data_layout::column_major``. template homogen_table(const Data* data_pointer, std::int64_t row_count, @@ -111,6 +163,24 @@ class ONEDAL_EXPORT homogen_table : public table { } #ifdef ONEDAL_DATA_PARALLEL + /// Creates a new ``homogen_table`` instance from externally-defined data block. + /// Table object owns the data pointer. + /// The :expr:`data` should point to the ``data_pointer`` memory block. + /// + /// @tparam Data The type of elements in the data block that will be stored into the table. + /// The :literal:`Data` type should be at least :expr:`float`, :expr:`double` or :expr:`std::int32_t`. + /// @tparam ConstDeleter The type of a deleter called on ``data_pointer`` when + /// the last table that refers it is out of the scope. + /// + /// @param queue The SYCL* queue object + /// @param data_pointer The pointer to a homogeneous data block. + /// @param row_count The number of rows in the table. + /// @param column_count The number of columns in the table. + /// @param data_deleter The deleter that is called on the ``data_pointer`` when the last table that refers it + /// is out of the scope. + /// @param dependencies Events indicating availability of the :literal:`Data` for reading or writing. + /// @param layout The layout of the data. Should be ``data_layout::row_major`` or + /// ``data_layout::column_major``. template homogen_table(const sycl::queue& queue, const Data* data_pointer, @@ -129,13 +199,18 @@ class ONEDAL_EXPORT homogen_table : public table { } #endif + /// Returns the :expr:`data` pointer cast to the :literal:`Data` type. No checks are + /// performed that this type is the actual type of the data within the table. template const Data* get_data() const { return reinterpret_cast(this->get_data()); } + /// The pointer to the data block within the table. + /// Should be equal to ``nullptr`` when :expr:`row_count == 0` and :expr:`column_count == 0`. const void* get_data() const; + /// The unique id of the homogen table type. std::int64_t get_kind() const { return kind(); } diff --git a/cpp/oneapi/dal/table/row_accessor.hpp b/cpp/oneapi/dal/table/row_accessor.hpp index d1cbe50fe9d..306d42f45ba 100644 --- a/cpp/oneapi/dal/table/row_accessor.hpp +++ b/cpp/oneapi/dal/table/row_accessor.hpp @@ -22,6 +22,9 @@ namespace oneapi::dal { namespace v1 { +/// @tparam T The type of data values in blocks returned by the accessor. +/// Should be const-qualified for read-only access. +/// An accessor supports at least :expr:`float`, :expr:`double`, and :expr:`std::int32_t` types of :literal:`T`. template class row_accessor : private detail::accessor_base { using base = detail::accessor_base; @@ -30,6 +33,10 @@ class row_accessor : private detail::accessor_base { using data_t = typename base::data_t; static constexpr bool is_readonly = base::is_readonly; + /// Creates a new read-only accessor object from the table. + /// The check that the accessor supports the table kind of :literal:`obj` is performed. + /// The reference to the :literal:`obj` table is stored within the accessor to + /// obtain data from the table. template < typename K, typename = std::enable_if_t || @@ -45,6 +52,17 @@ class row_accessor : private detail::accessor_base { } #ifdef ONEDAL_DATA_PARALLEL + /// Provides access to the rows of the table. + /// The method returns an array that directly points to the memory within the table + /// if it is possible. In that case, the array refers to the memory as to immutable data. + /// Otherwise, the new memory block is allocated, the data from the table rows is converted + /// and copied into this block. The array refers to the block as to mutable data. + /// + /// @param[in] queue The SYCL* queue object. + /// @param[in] rows The range of rows that data is returned from the accessor. + /// @param[in] alloc The requested kind of USM in the returned block. + /// + /// @pre ``rows`` are within the range of ``[0, obj.row_count)``. array pull(sycl::queue& queue, const range& rows = { 0, -1 }, const sycl::usm::alloc& alloc = sycl::usm::alloc::shared) const { @@ -62,6 +80,20 @@ class row_accessor : private detail::accessor_base { } #ifdef ONEDAL_DATA_PARALLEL + /// Provides access to the rows of the table. + /// The method returns the :expr:`block.data` pointer. + /// + /// @param[in] queue The SYCL* queue object. + /// @param[in,out] block The block which memory is reused (if it is possible) to obtain the data from the table. + /// The block memory is reset either when + /// its size is not big enough, or when it contains immutable data, or when direct + /// memory from the table can be used. + /// If the block is reset to use a direct memory pointer from the object, + /// it refers to this pointer as to immutable memory block. + /// @param[in] rows The range of rows that data is returned from the accessor. + /// @param[in] alloc The requested kind of USM in the returned block. + /// + /// @pre ``rows`` are within the range of ``[0, obj.row_count)``. T* pull(sycl::queue& queue, array& block, const range& rows = { 0, -1 },