Merge pull request #1405 from lplewa/ctl_experiment

move ctl to experimental

Author: lukaszstolarczuk

benchmark/benchmark_umf.hpp

@@ -9,6 +9,7 @@
 #include <thread>
 
 #include <benchmark/benchmark.h>
+#include <umf/experimental/ctl.h>
 #include <umf/memory_pool.h>
 #include <umf/memory_provider.h>
 #include <umf/pools/pool_disjoint.h>

include/umf/base.h

@@ -61,36 +61,6 @@ typedef enum umf_ctl_query_type {
     MAX_CTL_QUERY_TYPE
 } umf_ctl_query_type_t;
 
-///
-/// @brief Get value of a specified attribute at the given name.
-/// @param name name of an attribute to be retrieved
-/// @param ctx pointer to the pool or the provider
-/// @param arg [out] pointer to the variable where the value will be stored
-/// @param size size of the value, depends on the context
-/// @return UMF_RESULT_SUCCESS on success or UMF_RESULT_ERROR_UNKNOWN on failure.
-///
-umf_result_t umfCtlGet(const char *name, void *ctx, void *arg, size_t size);
-
-///
-/// @brief Set value of a specified attribute at the given name.
-/// @param name name of an attribute to be set
-/// @param ctx pointer to the pool or the provider, NULL for the 'default' path
-/// @param arg [in] pointer to the value that will be set
-/// @param size [in] size of the value, depends on the context
-/// @return UMF_RESULT_SUCCESS on success or UMF_RESULT_ERROR_UNKNOWN on failure.
-///
-umf_result_t umfCtlSet(const char *name, void *ctx, void *arg, size_t size);
-
-///
-/// @brief Execute callback related with the specified attribute.
-/// @param name name of an attribute to be executed
-/// @param ctx pointer to the pool or the provider
-/// @param arg [in/out] pointer to the value, can be used as an input or output
-/// @param size [in] size of the value, depends on the context
-/// @return UMF_RESULT_SUCCESS on success or UMF_RESULT_ERROR_UNKNOWN on failure.
-///
-umf_result_t umfCtlExec(const char *name, void *ctx, void *arg, size_t size);
-
 #ifdef __cplusplus
 }
 #endif

include/umf/experimental/ctl.h

@@ -0,0 +1,53 @@
+/*
+ *
+ * Copyright (C) 2024-2025 Intel Corporation
+ *
+ * Under the Apache License v2.0 with LLVM Exceptions. See LICENSE.TXT.
+ * SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+ *
+ */
+
+#ifndef UMF_CTL_H
+#define UMF_CTL_H 1
+
+#include <umf/base.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+///
+/// @brief Get value of a specified attribute at the given name.
+/// @param name name of an attribute to be retrieved
+/// @param ctx pointer to the pool or the provider
+/// @param arg [out] pointer to the variable where the value will be stored
+/// @param size size of the value, depends on the context
+/// @return UMF_RESULT_SUCCESS on success or UMF_RESULT_ERROR_UNKNOWN on failure.
+///
+umf_result_t umfCtlGet(const char *name, void *ctx, void *arg, size_t size);
+
+///
+/// @brief Set value of a specified attribute at the given name.
+/// @param name name of an attribute to be set
+/// @param ctx pointer to the pool or the provider, NULL for the 'default' path
+/// @param arg [in] pointer to the value that will be set
+/// @param size [in] size of the value, depends on the context
+/// @return UMF_RESULT_SUCCESS on success or UMF_RESULT_ERROR_UNKNOWN on failure.
+///
+umf_result_t umfCtlSet(const char *name, void *ctx, void *arg, size_t size);
+
+///
+/// @brief Execute callback related with the specified attribute.
+/// @param name name of an attribute to be executed
+/// @param ctx pointer to the pool or the provider
+/// @param arg [in/out] pointer to the value, can be used as an input or output
+/// @param size [in] size of the value, depends on the context
+/// @return UMF_RESULT_SUCCESS on success or UMF_RESULT_ERROR_UNKNOWN on failure.
+///
+umf_result_t umfCtlExec(const char *name, void *ctx, void *arg, size_t size);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* UMF_CTL_H */

include/umf/memory_provider_ops.h

@@ -258,6 +258,9 @@ typedef struct umf_memory_provider_ops_t {
     /// @brief Control operation for the memory provider.
     ///        The function is used to perform various control operations
     ///        on the memory provider.
+    /// \details
+    /// * This API is experimental and may change in future releases.
+    ///   Backward compatibility is not guaranteed.
     ///
     /// @param provider handle to the memory provider.
     /// @param operationType type of the operation to be performed.

test/ctl/ctl_api.cpp

@@ -19,6 +19,7 @@
 
 #include <umf.h>
 #include <umf/base.h>
+#include <umf/experimental/ctl.h>
 #include <umf/memory_pool.h>
 #include <umf/memory_provider.h>
 #include <umf/pools/pool_disjoint.h>

test/poolFixtures.hpp

@@ -13,6 +13,7 @@
 #include <string>
 #include <thread>
 
+#include <umf/experimental/ctl.h>
 #include <umf/pools/pool_proxy.h>
 #include <umf/providers/provider_devdax_memory.h>
 #include <umf/providers/provider_fixed_memory.h>

test/pools/disjoint_pool_ctl.cpp

@@ -3,6 +3,7 @@
 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exceptiongi
 
 #include <gtest/gtest.h>
+#include <umf/experimental/ctl.h>
 #include <umf/memory_pool.h>
 #include <umf/memory_provider.h>
 #include <umf/memory_provider_ops.h>