use actual pool name instead of default name

Author: lplewa

docs/config/ctl.rst

@@ -37,7 +37,7 @@ Every ``{}`` in the path is replaced with an extra argument passed to the CTL
 function. Alternative addressing methods are described below.
 
 Pool / Provider addressing
-==========================
+============================
 
 Two addressing schemes are provided: ``by_handle`` and ``by_name``. Each pool
 and provider has a unique handle and an optional user-defined name that can be
@@ -56,7 +56,7 @@ appending an index after the name::
 The number of pools with a given name can be obtained with the ``count`` node.
 
 Wildcards
-=========
+===========
 
 A ``{}`` in the path acts as a wildcard and is replaced with successive
 arguments of ``umfCtlGet``, ``umfCtlSet`` or ``umfCtlExec``. Wildcards can
@@ -74,18 +74,21 @@ replace any node, not only handles. For example::
 Ensure that the types of wildcard arguments match the expected node types.
 
 Default addressing
-==================
+===================
 
 ``umf.provider.default`` and ``umf.pool.default`` store default values applied
 to providers or pools created after the defaults are set. For example::
 
-  const char *name = "custom";
-  umfCtlSet("umf.pool.default.disjoint.name", (void *)name, strlen(name)+1);
+  size_t capacity = 16;
+  umfCtlSet("umf.pool.default.disjoint.params.capacity", &capacity,
+            sizeof(capacity));
 
-Every subsequently created disjoint pool will use ``custom`` as its name unless
-overridden by explicit parameters. Defaults may be supplied programmatically or
-via configuration and are saved internally and applied during initalization of
-a matching provider or pool.
+Every subsequently created disjoint pool will use ``16`` as its starting
+capacity overriding it's creation parameters. Defaults are keyed by the
+name returned from the provider or pool ``get_name`` callback, so if pool/provider
+has custom name it must be addressed explicitly.  Defaults may be supplied programmatically
+or via environment variable and are saved internally and applied during initialization of a
+matching provider or pool.
 
 Environment variables
 =====================
@@ -116,7 +119,7 @@ Within each subsystem the path continues with an addressing scheme followed by
 the module or leaf of interest.
 
 Reading this reference
-----------------------
+------------------------
 
 Parameter annotations describe the values stored in the node rather than the
 pointer types passed to ``umfCtlGet``/``umfCtlSet``/``umfCtlExec``. The
@@ -186,7 +189,7 @@ Logger nodes
 
    :param path: Receives the currently selected sink on reads. On writes, pass
       ``"stdout"`` or ``"stderr"`` to redirect to standard streams, a
-      NUL-terminated file path to append to a file, or ``NULL`` to disable
+      NULL-terminated file path to append to a file, or ``NULL`` to disable
       logging altogether.
    :type path: ``char *`` when reading, ``const char *`` when writing
 
@@ -207,14 +210,14 @@ Provider entries are organized beneath ``umf.provider``. Use
 ``umf.provider.by_handle.{provider}`` with a
 :type:`umf_memory_provider_handle_t` argument to reach a specific provider.
 Providers can also be addressed by name through ``umf.provider.by_name.{provider}``;
-append ``.{index}`` to address specyfic provider when multiple providers share the same label.
-Defaults for future providers live under ``umf.provider.default.{provider_name}``,
-where ``{provider_name}`` matches the canonical provider identifier (``OS``,
-``FILE``, ``DEVDAX``, ``FIXED``, ``CUDA`` or ``LEVEL_ZERO``). Values written to
-the default tree are saved until a matching provider is created and applied
-during provider initialization. Defaults can be supplied programmatically or
-through configuration strings. The entries below list only the suffix of each
-node; prefix them with the appropriate ``umf.provider`` path.
+append ``.{index}`` to address specific provider when multiple providers share the same label.
+Defaults for future providers reside under ``umf.provider.default.{provider}`` and track the
+name returned by each provider's ``get_name`` implementation. Providers have their
+default names (``OS``, ``FILE``, ``DEVDAX``, ``FIXED``, ``CUDA`` or ``LEVEL_ZERO``),
+unless their name was changed during creation, those renamed providers must be addressed explicitly.
+Defaults can be written via ``umf.provider.default.<name>`` either programmatically or through
+configuration strings. The entries below list only the suffix of each node;
+prefix them with the appropriate ``umf.provider`` path.
 
 Common provider statistics
 --------------------------
@@ -316,11 +319,13 @@ Pool nodes
 Pool entries mirror the provider layout. ``umf.pool.by_handle.{pool}`` accepts a
 :type:`umf_memory_pool_handle_t`, while ``umf.pool.by_name.{pool}`` addresses
 pools by name with an optional ``.{index}`` suffix when names are reused.
-Defaults for future pools reside under ``umf.pool.default.{pool}``, where
-canonical names include ``disjoint``, ``scalable`` and ``jemalloc``. Defaults
-can be written via ``umf.pool.default.<pool>`` either programmatically or
-through configuration strings. The entries below list only the suffix of each
-node; prefix them with the appropriate ``umf.pool`` path.
+Defaults for future pools reside under ``umf.pool.default.{pool}`` and track the
+name returned by each pool's ``get_name`` implementation. Pools that keep their
+default names (``disjoint``, ``scalable`` and ``jemalloc``) continue to match
+those entries, while renamed pools must be addressed explicitly. Defaults can be
+written via ``umf.pool.default.<pool>`` either programmatically or through
+configuration strings. The entries below list only the suffix of each node;
+prefix them with the appropriate ``umf.pool`` path.
 
 Common pool statistics
 --------------------------
@@ -346,7 +351,7 @@ Disjoint pool (``disjoint``)
       provider.
    :type bytes: ``size_t``
 
-   **Access:** read-write. (write is only avaiable through defaults)
+   **Access:** read-write. (write is only available through defaults)
    **Defaults / Env:** supported.
 
    Governs how much memory the pool grabs in each slab. Lower values reduce
@@ -359,7 +364,7 @@ Disjoint pool (``disjoint``)
       cached by the pool.
    :type bytes: ``size_t``
 
-   **Access:** read-write. (write is only avaiable through defaults)
+   **Access:** read-write. (write is only available through defaults)
    **Defaults / Env:** supported.
 
    Sets the cut-off for pooling allocations. Requests larger than this value are
@@ -372,7 +377,7 @@ Disjoint pool (``disjoint``)
       may retain.
    :type count: ``size_t``
 
-   **Access:** read-write. (write is only avaiable through defaults)
+   **Access:** read-write. (write is only available through defaults)
    **Defaults / Env:** supported.
 
    Caps the pool's cached slabs per bucket to limit memory retention. Shrinking
@@ -385,7 +390,7 @@ Disjoint pool (``disjoint``)
       serve.
    :type bytes: ``size_t``
 
-   **Access:** read-write. (write is only avaiable through defaults)
+   **Access:** read-write. (write is only available through defaults)
    **Defaults / Env:** supported.
 
    Controls the smallest chunk size kept in the pool, which in turn affects the
@@ -397,7 +402,7 @@ Disjoint pool (``disjoint``)
    :param level: Receives or supplies the tracing level for the pool.
    :type level: ``int`` (``0`` disables tracing)
 
-   **Access:** read-write. (write is only avaiable through defaults)
+   **Access:** read-write. (write is only available through defaults)
    **Defaults / Env:** supported.
 
    Controls the disjoint pool's tracing features. ``0`` disables tracing.

docs/config/index.rst

@@ -1,4 +1,4 @@
-.. Copyright 2023 Intel Corporation
+.. Copyright 2023-2025 Intel Corporation
    Intel Unified Memory Framework documentation
 
 Intel Unified Memory Framework documentation
@@ -10,4 +10,6 @@ Intel Unified Memory Framework documentation
    introduction.rst
    examples.rst
    api.rst
+   ctl.rst
    glossary.rst
+

docs/config/spelling_exceptions.txt

@@ -50,11 +50,13 @@ partList
 pid
 poolable
 preallocated
+programmatically
 propertyId
 providential
 providerIpcData
 ptr
 realloc
+runnables
 Scalable
 scalable
 stdout
@@ -82,5 +84,6 @@ umfMemspaceUserFilter
 umfMemspaceMemtargetAdd
 unfreed
 usm
+wildcarded
 zA
 ze

examples/ctl/ctl_example.c

@@ -204,7 +204,7 @@ static umf_result_t ctl_ctl(void *provider, umf_ctl_query_source_t source,
         return UMF_RESULT_SUCCESS;
     }
     if (queryType == CTL_QUERY_RUNNABLE &&
-        strcmp(formatted, "substraction") == 0) {
+        strcmp(formatted, "subtraction") == 0) {
         if (p->m) {
             p->c = (p->a - p->b) % p->m;
         } else {
@@ -300,9 +300,9 @@ int main(void) {
 
     // Execute subtraction and fetch the result
     res =
-        umfCtlExec("umf.provider.by_handle.{}.substraction", NULL, 0, provider);
+        umfCtlExec("umf.provider.by_handle.{}.subtraction", NULL, 0, provider);
     if (res != UMF_RESULT_SUCCESS) {
-        fprintf(stderr, "Failed to execute substraction!\n");
+        fprintf(stderr, "Failed to execute subtraction!\n");
         goto out;
     }
     res = umfCtlGet("umf.provider.by_handle.{}.c", &result, sizeof(result),
@@ -311,7 +311,7 @@ int main(void) {
         fprintf(stderr, "Failed to get c!\n");
         goto out;
     }
-    printf("substraction result: %d\n", result);
+    printf("subtraction result: %d\n", result);
 
 out:
     umfMemoryProviderDestroy(provider);

examples/ctl/ctl_statistics_example.c

@@ -201,7 +201,7 @@ int main(void) {
         goto cleanup;
     }
 
-    /* set name of the pool so we can easly ref it by using name */
+    /* set name of the pool so we can easily ref it by using name */
     res = umfDisjointPoolParamsSetName(disjoint_params, pool_name);
     if (res != UMF_RESULT_SUCCESS) {
         fprintf(stderr, "Failed to name disjoint pool (error %d)\n", (int)res);

src/memory_pool.c

@@ -469,15 +469,14 @@ static umf_result_t umfPoolCreateInternal(const umf_memory_pool_ops_t *ops,
         goto err_pool_init;
     }
 
-    // Set default property "name" to pool if exists
     const char *pname = NULL;
-    ret = ops->get_name(NULL, &pname);
+    ret = ops->get_name(pool->pool_priv, &pname);
     if (ret != UMF_RESULT_SUCCESS) {
         LOG_ERR("Failed to get pool name");
         goto err_pool_init;
     }
     assert(pname != NULL);
-
+    utils_warn_invalid_name("Memory pool", pname);
     ctl_default_apply(pool_default_list, pname, ops->ext_ctl, pool->pool_priv);
 
     ret = umfPoolPostInitialize(&pool->ops, pool->pool_priv);
@@ -489,12 +488,6 @@ static umf_result_t umfPoolCreateInternal(const umf_memory_pool_ops_t *ops,
     *hPool = pool;
     pools_by_name_add(pool);
 
-    const char *pool_name = NULL;
-    if (ops->get_name(pool->pool_priv, &pool_name) == UMF_RESULT_SUCCESS &&
-        pool_name) {
-        utils_warn_invalid_name("Memory pool", pool_name);
-    }
-
     LOG_INFO("Memory pool created: %p", (void *)pool);
     return UMF_RESULT_SUCCESS;
 

src/memory_provider.c

@@ -345,10 +345,20 @@ umf_result_t umfMemoryProviderCreate(const umf_memory_provider_ops_t *ops,
 
     utils_init_once(&mem_provider_ctl_initialized, provider_ctl_init);
     const char *pname = NULL;
-    if (provider->ops.get_name(NULL, &pname) == UMF_RESULT_SUCCESS && pname) {
-        ctl_default_apply(provider_default_list, pname, provider->ops.ext_ctl,
-                          provider->provider_priv);
+
+    ret = provider->ops.get_name(provider->provider_priv, &pname);
+    if (ret != UMF_RESULT_SUCCESS) {
+        LOG_ERR("Failed to get pool name");
+        umf_ba_global_free(provider);
+        return ret;
     }
+
+    assert(pname != NULL);
+    utils_warn_invalid_name("Memory provider", pname);
+
+    ctl_default_apply(provider_default_list, pname, provider->ops.ext_ctl,
+                      provider->provider_priv);
+
     ret = umfProviderPostInitialize(&provider->ops, provider_priv);
     if (ret != UMF_RESULT_SUCCESS && ret != UMF_RESULT_ERROR_INVALID_CTL_PATH) {
         LOG_ERR("Failed to post-initialize provider");
@@ -358,13 +368,6 @@ umf_result_t umfMemoryProviderCreate(const umf_memory_provider_ops_t *ops,
 
     *hProvider = provider;
 
-    const char *provider_name = NULL;
-    if (provider->ops.get_name(provider->provider_priv, &provider_name) ==
-            UMF_RESULT_SUCCESS &&
-        provider_name) {
-        utils_warn_invalid_name("Memory provider", provider_name);
-    }
-
     return UMF_RESULT_SUCCESS;
 }