[CTL] Add CTL functionality (by handle access)

This commit introduces the control and introspection mechanism
that can be accessed using pointer to supported pool or provider.

Author: KFilipek

include/umf/base.h

@@ -50,6 +50,43 @@ typedef enum umf_result_t {
     UMF_RESULT_ERROR_UNKNOWN = 0x7ffffffe ///< Unknown or internal error
 } umf_result_t;
 
+/// @brief Type of the CTL query
+typedef enum umf_ctl_query_type {
+    CTL_QUERY_READ,
+    CTL_QUERY_WRITE,
+    CTL_QUERY_RUNNABLE,
+    CTL_QUERY_SUBTREE,
+
+    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
+/// @return UMF_RESULT_SUCCESS on success or UMF_RESULT_ERROR_UNKNOWN on failure.
+///
+umf_result_t umfCtlGet(const char *name, void *ctx, void *arg);
+
+///
+/// @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
+/// @param arg [in] pointer to the value that will be set
+/// @return UMF_RESULT_SUCCESS on success or UMF_RESULT_ERROR_UNKNOWN on failure.
+///
+umf_result_t umfCtlSet(const char *name, void *ctx, void *arg);
+
+///
+/// @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
+/// @return UMF_RESULT_SUCCESS on success or UMF_RESULT_ERROR_UNKNOWN on failure.
+///
+umf_result_t umfCtlExec(const char *name, void *ctx, void *arg);
+
 #ifdef __cplusplus
 }
 #endif

include/umf/memory_pool_ops.h

@@ -22,6 +22,25 @@ extern "C" {
 /// has been modified.
 #define UMF_POOL_OPS_VERSION_CURRENT UMF_MAKE_VERSION(0, 11)
 
+/// @brief This structure comprises function pointers used by corresponding umfMemoryPool calls.
+typedef struct umf_memory_pool_ext_ops_t {
+    ///
+    /// @brief Control operation for the memory pool.
+    ///        The function is used to perform various control operations
+    ///        on the memory pool.
+    ///
+    /// @param hPool handle to the memory pool.
+    /// @param operationType type of the operation to be performed.
+    /// @param name name associated with the operation.
+    /// @param arg argument for the operation.
+    /// @param queryType type of the query to be performed.
+    ///
+    /// @return umf_result_t result of the control operation.
+    ///
+    umf_result_t (*ctl)(void *hPool, int operationType, const char *name,
+                        void *arg, umf_ctl_query_type_t queryType);
+} umf_memory_pool_ext_ops_t;
+
 ///
 /// @brief This structure comprises function pointers used by corresponding umfPool*
 /// calls. Each memory pool implementation should initialize all function
@@ -125,6 +144,11 @@ typedef struct umf_memory_pool_ops_t {
     ///         The value is undefined if the previous allocation was successful.
     ///
     umf_result_t (*get_last_allocation_error)(void *pool);
+
+    ///
+    /// @brief Optional ops
+    ///
+    umf_memory_provider_ext_ops_t ext;
 } umf_memory_pool_ops_t;
 
 #ifdef __cplusplus

include/umf/memory_provider_ops.h

@@ -6,7 +6,6 @@
  * SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
  *
  */
-
 #ifndef UMF_MEMORY_PROVIDER_OPS_H
 #define UMF_MEMORY_PROVIDER_OPS_H 1
 
@@ -83,6 +82,22 @@ typedef struct umf_memory_provider_ext_ops_t {
     umf_result_t (*allocation_split)(void *hProvider, void *ptr,
                                      size_t totalSize, size_t firstSize);
 
+    ///
+    /// @brief Control operation for the memory provider.
+    ///        The function is used to perform various control operations
+    ///        on the memory provider.
+    ///
+    /// @param hProvider handle to the memory provider.
+    /// @param operationType type of the operation to be performed.
+    /// @param name name associated with the operation.
+    /// @param arg argument for the operation.
+    /// @param queryType type of the query to be performed.
+    ///
+    /// @return umf_result_t result of the control operation.
+    ///
+    umf_result_t (*ctl)(void *hProvider, int operationType, const char *name,
+                        void *arg, umf_ctl_query_type_t queryType);
+
 } umf_memory_provider_ext_ops_t;
 
 ///