[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

@@ -1,6 +1,6 @@
 /*
  *
- * Copyright (C) 2023-2024 Intel Corporation
+ * Copyright (C) 2023-2025 Intel Corporation
  *
  * Under the Apache License v2.0 with LLVM Exceptions. See LICENSE.TXT.
  * SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
@@ -48,6 +48,20 @@ 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;
+
+int umf_ctl_get(const char *name, void *ctx, void *arg);
+int umf_ctl_set(const char *name, void *ctx, void *arg);
+int umf_ctl_exec(const char *name, void *ctx, void *arg);
+
 #ifdef __cplusplus
 }
 #endif

include/umf/memory_pool_ops.h

@@ -17,6 +17,25 @@
 extern "C" {
 #endif
 
+/// @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 query_type 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 query_type);
+} 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
@@ -120,6 +139,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

@@ -1,12 +1,11 @@
 /*
  *
- * Copyright (C) 2023-2024 Intel Corporation
+ * Copyright (C) 2023-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_MEMORY_PROVIDER_OPS_H
 #define UMF_MEMORY_PROVIDER_OPS_H 1
 
@@ -78,6 +77,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 query_type 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 query_type);
+
 } umf_memory_provider_ext_ops_t;
 
 ///

src/ctl/ctl.c

@@ -27,6 +27,7 @@
 #include "base_alloc/base_alloc_global.h"
 #include "utils/utils_common.h"
 #include "utlist.h"
+#include <umf/base.h>
 
 #ifdef _WIN32
 #define strtok_r strtok_s
@@ -43,6 +44,7 @@
 #define CTL_QUERY_NODE_SEPARATOR "."
 #define CTL_VALUE_ARG_SEPARATOR ","
 
+/* GLOBAL TREE */
 static int ctl_global_first_free = 0;
 static struct ctl_node CTL_NODE(global)[CTL_MAX_ENTRIES];
 
@@ -78,16 +80,34 @@ char *Strdup(const char *s) {
     return p;
 }
 
+int umf_ctl_get(const char *name, void *ctx, void *arg) {
+    return ctl_query(NULL, ctx, CTL_QUERY_PROGRAMMATIC, name, CTL_QUERY_READ,
+                     arg);
+}
+
+int umf_ctl_set(const char *name, void *ctx, void *arg) {
+    return ctl_query(NULL, ctx, CTL_QUERY_PROGRAMMATIC, name, CTL_QUERY_WRITE,
+                     arg);
+}
+
+int umf_ctl_exec(const char *name, void *ctx, void *arg) {
+    return ctl_query(NULL, ctx, CTL_QUERY_PROGRAMMATIC, name,
+                     CTL_QUERY_RUNNABLE, arg);
+}
+
 /*
  * ctl_find_node -- (internal) searches for a matching entry point in the
  *    provided nodes
  *
+ * Name offset is used to return the offset of the name in the query string.
  * The caller is responsible for freeing all of the allocated indexes,
  * regardless of the return value.
  */
 static const struct ctl_node *ctl_find_node(const struct ctl_node *nodes,
                                             const char *name,
-                                            struct ctl_index_utlist *indexes) {
+                                            struct ctl_index_utlist *indexes,
+                                            int *name_offset) {
+    assert(name_offset != NULL);
     const struct ctl_node *n = NULL;
     char *sptr = NULL;
     char *parse_str = Strdup(name);
@@ -102,6 +122,10 @@ static const struct ctl_node *ctl_find_node(const struct ctl_node *nodes,
      * in the main ctl tree.
      */
     while (node_name != NULL) {
+        *name_offset = (int)(node_name - parse_str);
+        if (n != NULL && n->type == CTL_NODE_SUBTREE) {
+            break;
+        }
         char *endptr;
         /*
          * Ignore errno from strtol: FreeBSD returns EINVAL if no
@@ -128,6 +152,7 @@ static const struct ctl_node *ctl_find_node(const struct ctl_node *nodes,
                 break;
             }
         }
+
         if (n->name == NULL) {
             goto error;
         }
@@ -244,21 +269,29 @@ static void ctl_query_cleanup_real_args(const struct ctl_node *n,
  */
 static int ctl_exec_query_read(void *ctx, const struct ctl_node *n,
                                enum ctl_query_source source, void *arg,
-                               struct ctl_index_utlist *indexes) {
+                               struct ctl_index_utlist *indexes,
+                               char *extra_name,
+                               umf_ctl_query_type_t query_type) {
+    (void)extra_name, (void)query_type;
     if (arg == NULL) {
         errno = EINVAL;
         return -1;
     }
 
-    return n->cb[CTL_QUERY_READ](ctx, source, arg, indexes);
+    assert(MAX_CTL_QUERY_TYPE != query_type);
+    return n->cb[CTL_QUERY_READ](ctx, source, arg, indexes, NULL,
+                                 MAX_CTL_QUERY_TYPE);
 }
 
 /*
  * ctl_exec_query_write -- (internal) calls the write callback of a node
  */
 static int ctl_exec_query_write(void *ctx, const struct ctl_node *n,
                                 enum ctl_query_source source, void *arg,
-                                struct ctl_index_utlist *indexes) {
+                                struct ctl_index_utlist *indexes,
+                                char *extra_name,
+                                umf_ctl_query_type_t query_type) {
+    (void)extra_name, (void)query_type;
     if (arg == NULL) {
         errno = EINVAL;
         return -1;
@@ -269,7 +302,9 @@ static int ctl_exec_query_write(void *ctx, const struct ctl_node *n,
         return -1;
     }
 
-    int ret = n->cb[CTL_QUERY_WRITE](ctx, source, real_arg, indexes);
+    assert(MAX_CTL_QUERY_TYPE != query_type);
+    int ret = n->cb[CTL_QUERY_WRITE](ctx, source, real_arg, indexes, NULL,
+                                     MAX_CTL_QUERY_TYPE);
     ctl_query_cleanup_real_args(n, real_arg, source);
 
     return ret;
@@ -280,24 +315,40 @@ static int ctl_exec_query_write(void *ctx, const struct ctl_node *n,
  */
 static int ctl_exec_query_runnable(void *ctx, const struct ctl_node *n,
                                    enum ctl_query_source source, void *arg,
-                                   struct ctl_index_utlist *indexes) {
-    return n->cb[CTL_QUERY_RUNNABLE](ctx, source, arg, indexes);
+                                   struct ctl_index_utlist *indexes,
+                                   char *extra_name,
+                                   umf_ctl_query_type_t query_type) {
+    (void)extra_name, (void)query_type;
+    assert(MAX_CTL_QUERY_TYPE != query_type);
+    return n->cb[CTL_QUERY_RUNNABLE](ctx, source, arg, indexes, NULL,
+                                     MAX_CTL_QUERY_TYPE);
+}
+
+static int ctl_exec_query_subtree(void *ctx, const struct ctl_node *n,
+                                  enum ctl_query_source source, void *arg,
+                                  struct ctl_index_utlist *indexes,
+                                  char *extra_name,
+                                  umf_ctl_query_type_t query_type) {
+    return n->cb[CTL_QUERY_SUBTREE](ctx, source, arg, indexes, extra_name,
+                                    query_type);
 }
 
 static int (*ctl_exec_query[MAX_CTL_QUERY_TYPE])(
     void *ctx, const struct ctl_node *n, enum ctl_query_source source,
-    void *arg, struct ctl_index_utlist *indexes) = {
+    void *arg, struct ctl_index_utlist *indexes, char *extra_name,
+    umf_ctl_query_type_t query_type) = {
     ctl_exec_query_read,
     ctl_exec_query_write,
     ctl_exec_query_runnable,
+    ctl_exec_query_subtree,
 };
 
 /*
  * ctl_query -- (internal) parses the name and calls the appropriate methods
  *    from the ctl tree
  */
 int ctl_query(struct ctl *ctl, void *ctx, enum ctl_query_source source,
-              const char *name, enum ctl_query_type type, void *arg) {
+              const char *name, umf_ctl_query_type_t type, void *arg) {
     if (name == NULL) {
         errno = EINVAL;
         return -1;
@@ -315,22 +366,28 @@ int ctl_query(struct ctl *ctl, void *ctx, enum ctl_query_source source,
     }
 
     int ret = -1;
+    int name_offset = 0;
 
-    const struct ctl_node *n = ctl_find_node(CTL_NODE(global), name, indexes);
+    const struct ctl_node *n =
+        ctl_find_node(CTL_NODE(global), name, indexes, &name_offset);
 
     if (n == NULL && ctl) {
         ctl_delete_indexes(indexes);
         indexes = NULL;
-        n = ctl_find_node(ctl->root, name, indexes);
+        n = ctl_find_node(ctl->root, name, indexes, &name_offset);
     }
 
-    if (n == NULL || n->type != CTL_NODE_LEAF || n->cb[type] == NULL) {
+    if (n == NULL ||
+        (n->type != CTL_NODE_LEAF && n->type != CTL_NODE_SUBTREE) ||
+        n->cb[n->type == CTL_NODE_SUBTREE ? CTL_QUERY_SUBTREE : type] == NULL) {
         errno = EINVAL;
         goto out;
     }
 
-    ret = ctl_exec_query[type](ctx, n, source, arg, indexes);
-
+    char *extra_name = (char *)&name[0] + name_offset;
+    ret =
+        ctl_exec_query[n->type == CTL_NODE_SUBTREE ? CTL_QUERY_SUBTREE : type](
+            ctx, n, source, arg, indexes, extra_name, type);
 out:
     ctl_delete_indexes(indexes);