rename examples and mark ctl as experimental in those

Author: lplewa

README.md

@@ -21,6 +21,9 @@ documentation, which includes the code of the
 [basic example](https://github.com/oneapi-src/unified-memory-framework/blob/main/examples/basic/basic.c).
 There are also more advanced examples that allocate USM memory from the [Level Zero device](examples/level_zero_shared_memory/level_zero_shared_memory.c) using the Level Zero API and UMF Level Zero memory provider and [CUDA device](examples/cuda_shared_memory/cuda_shared_memory.c) using the CUDA API and UMF CUDA memory provider.
 
+UMF's experimental CTL API is showcased in the [CTL example](examples/ctl/ctl.c),
+which explores provider and pool statistics, and in the [custom CTL example](examples/ctl/custom_ctl.c), which wires CTL support into a custom memory provider. These examples rely on experimental headers which may change in future releases.
+
 ## Build
 
 ### Requirements

docs/config/ctl.rst

@@ -8,6 +8,9 @@ configuration options, statistics and auxiliary APIs. CTL entries can also be
 set through environment variables or a configuration file, allowing adjustment
 of UMF behavior without modifying the program.
 
+.. note::
+   The CTL API is experimental and may change in future releases.
+
 Main concepts
 =============
 
@@ -84,7 +87,7 @@ to providers or pools created after the defaults are set. For example::
             sizeof(capacity));
 
 Every subsequently created disjoint pool will use ``16`` as its starting
-capacity overriding it's creation parameters. Defaults are keyed by the
+capacity overriding its 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
@@ -99,7 +102,7 @@ Multiple entries are separated with semicolons, e.g.::
 
   UMF_CONF="umf.logger.output=stdout;umf.logger.level=0"
 
-CTL options available through environment variables are limited—you can only
+CTL options available through environment variables are limited — you can only
 target default nodes when addressing pools. This means that configuration
 strings can influence values consumed during pool creation but cannot alter
 runtime-only parameters.
@@ -118,7 +121,7 @@ major subsystems:
 Within each subsystem the path continues with an addressing scheme followed by
 the module or leaf of interest.
 
-Reading this reference
+Reading below sections
 =======================
 
 Parameter annotations describe the values stored in the node rather than the
@@ -211,8 +214,8 @@ Provider entries are organized beneath ``umf.provider``. Use
 :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 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
+Defaults for future providers reside under ``umf.provider.default.{provider}`` where ``{provider`` is
+a 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
@@ -663,17 +666,16 @@ The jemalloc-backed pool currently exposes only the common statistics nodes.
 Adding CTL support to custom providers and pools
 ================================================
 
-The :file:`examples/ctl/ctl_example.c` source demonstrates how a minimal
+The :file:`examples/ctl/custom_ctl.c` source demonstrates how a minimal
 provider can expose configuration entries, statistics and runnables through the
 CTL API. To add similar support to your own provider or pool you must implement
 an ``ext_ctl`` callback – parse incoming CTL paths and handle
-`CTL_QUERY_READ``, ``CTL_QUERY_WRITE`` and ``CTL_QUERY_RUNNABLE`` requests.
+``CTL_QUERY_READ``, ``CTL_QUERY_WRITE`` and ``CTL_QUERY_RUNNABLE`` requests.
 The callback receives a ``umf_ctl_query_source_t`` indicating whether the
 query came from the application or a configuration source.  Programmatic
 calls pass typed binary data, while configuration sources deliver strings
 that must be parsed.  Wildcards (``{}``) may appear in paths and are supplied
 as additional arguments.
-new entries.
 
 During initialization UMF will execute ``post_initialize`` on the callback after
 applying any queued defaults, allowing the provider or pool to finalize its

docs/config/examples.rst

@@ -147,19 +147,23 @@ in the UMF repository.
 
 TODO
 
-CTL statistics example
+CTL example
 ==============================================================================
 
-You can find the full example code in the `examples/ctl/ctl_statistics_example.c`_ file
-in the UMF repository.
+.. note::
+   The CTL API is experimental and may change in future releases.
+
+You can find the full example code in the `examples/ctl/ctl.c`_ file in the
+UMF repository.
 
 The sample configures an OS memory provider and a disjoint pool, reuses the
 provider's canonical ``OS`` selector obtained at runtime, assigns a custom pool
 name, and then mixes ``by_handle`` and ``by_name`` selectors to explore CTL
 statistics. Wildcard nodes are used to choose provider counters, build a
 four-segment ``{}.{}`` chain for the named pool, reset the peak tracker, and
-drill into per-bucket disjoint pool telemetry. The program prints hints on ``stderr``
-explaining which tracing level is necessary when a statistic is unavailable.
+drill into per-bucket disjoint pool telemetry. The program prints hints on
+``stderr`` explaining which tracing level is necessary when a statistic is
+unavailable.
 
 Build and run the example with::
 
@@ -176,6 +180,26 @@ Tracing level ``1`` enables slab usage counters, level ``2`` adds allocation
 and free statistics, and level ``3`` additionally emits verbose log messages
 from the pool implementation.
 
+Custom CTL example
+==============================================================================
+
+You can find the full example code in the `examples/ctl/custom_ctl.c`_ file in
+the UMF repository. The program implements a minimal memory provider with CTL
+hooks that accept configuration values, execute runnables, and expose provider
+state through the experimental API. It highlights converting wildcard segments
+to ``printf``-style format strings and reading integers supplied via
+configuration defaults.
+
+Build and run the example with::
+
+   cmake -B build
+   cmake --build build
+   ./build/examples/umf_example_ctl
+
+Optionally supply a modulus via configuration defaults::
+
+   UMF_CONF="umf.provider.default.ctl.m=10" ./build/examples/umf_example_ctl
+
 IPC example with Level Zero Memory Provider
 ==============================================================================
 The full code of the example is in the `examples/ipc_level_zero/ipc_level_zero.c`_ file in the UMF repository.
@@ -260,7 +284,8 @@ the :any:`umfCloseIPCHandle` function is called.
 .. _examples/cuda_shared_memory/cuda_shared_memory.c: https://github.com/oneapi-src/unified-memory-framework/blob/main/examples/cuda_shared_memory/cuda_shared_memory.c
 .. _examples/ipc_level_zero/ipc_level_zero.c: https://github.com/oneapi-src/unified-memory-framework/blob/main/examples/ipc_level_zero/ipc_level_zero.c
 .. _examples/custom_file_provider/custom_file_provider.c: https://github.com/oneapi-src/unified-memory-framework/blob/main/examples/custom_file_provider/custom_file_provider.c
-.. _examples/ctl/ctl_statistics_example.c: https://github.com/oneapi-src/unified-memory-framework/blob/main/examples/ctl/ctl_statistics_example.c
+.. _examples/ctl/ctl.c: https://github.com/oneapi-src/unified-memory-framework/blob/main/examples/ctl/ctl.c
+.. _examples/ctl/custom_ctl.c: https://github.com/oneapi-src/unified-memory-framework/blob/main/examples/ctl/custom_ctl.c
 .. _examples/memspace: https://github.com/oneapi-src/unified-memory-framework/blob/main/examples/memspace/
 .. _README: https://github.com/oneapi-src/unified-memory-framework/blob/main/README.md#memory-pool-managers
 .. _umf/ipc.h: https://github.com/oneapi-src/unified-memory-framework/blob/main/include/umf/ipc.h

examples/CMakeLists.txt

@@ -277,7 +277,7 @@ if(LINUX)
 
     add_umf_executable(
         NAME ${EXAMPLE_NAME}
-        SRCS ctl/ctl_example.c
+        SRCS ctl/custom_ctl.c
         LIBS umf ${UMF_HWLOC_NAME})
 
     target_include_directories(
@@ -295,7 +295,7 @@ if(LINUX)
 
     add_umf_executable(
         NAME ${EXAMPLE_NAME}
-        SRCS ctl/ctl_statistics_example.c
+        SRCS ctl/ctl.c
         LIBS umf ${UMF_HWLOC_NAME})
 
     target_include_directories(

examples/README.md

@@ -69,11 +69,28 @@ processes: a producer and a consumer that communicate in the following way
 
 ## CTL example
 
+> **Note**: The CTL API is experimental and may change in future releases.
+
+This example configures an OS memory provider and disjoint pool, then queries
+statistics through CTL using both ``by_handle`` and ``by_name`` selectors. It
+demonstrates wildcard nodes to mix selectors, reset peak counters, and read
+disjoint-pool bucket telemetry. Run it with:
+
+  ./umf_example_ctl_statistics
+
+Tracing for detailed disjoint pool counters can be enabled through:
+
+  UMF_CONF="umf.pool.default.disjoint.params.pool_trace=2" ./umf_example_ctl_statistics
+
+## Custom CTL example
+
+> **Note**: The CTL API is experimental and may change in future releases.
+
 This example demonstrates how to add CTL support to a custom memory
 provider. It sets variables ``a`` and ``b`` through CTL, plus it allows
-for the modulus ``m`` loaded from the environment or a configuration file.
+for the modulus ``m`` to be loaded from the environment or a configuration file.
 Addition and subtraction operations return results modulo ``m`` and the
 result ``c`` can be retrieved using the CTL API. For example, to set the
-modulus through an environment variable run::
+modulus through an environment variable run:
 
   UMF_CONF="umf.provider.default.ctl.m=10" ./umf_example_ctl

examples/ctl/CMakeLists.txt

@@ -23,59 +23,59 @@ endif()
 
 # build the example
 set(EXAMPLE_NAME umf_example_ctl)
-add_executable(${ EXAMPLE_NAME} ctl_example.c)
-target_include_directories(${ EXAMPLE_NAME} PRIVATE ${ LIBUMF_INCLUDE_DIRS})
+add_executable(${EXAMPLE_NAME} custom_ctl.c)
+target_include_directories(${EXAMPLE_NAME} PRIVATE ${LIBUMF_INCLUDE_DIRS})
 target_link_directories(
     ${
     EXAMPLE_NAME}
     PRIVATE
     ${
     LIBHWLOC_LIBRARY_DIRS})
-target_link_libraries(${ EXAMPLE_NAME} PRIVATE ${LIBUMF_LIBRARIES} hwloc)
+target_link_libraries(${EXAMPLE_NAME} PRIVATE ${LIBUMF_LIBRARIES} hwloc)
 
 add_test(
     NAME ${EXAMPLE_NAME}
-    COMMAND ${ EXAMPLE_NAME}
-    WORKING_DIRECTORY ${ CMAKE_CURRENT_BINARY_DIR})
+    COMMAND ${EXAMPLE_NAME}
+    WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR})
 
 set_tests_properties(${EXAMPLE_NAME} PROPERTIES LABELS "example-standalone")
 
 if(LINUX)
     # set LD_LIBRARY_PATH
     set_property(
-        TEST ${ EXAMPLE_NAME}
+        TEST ${EXAMPLE_NAME}
         PROPERTY ENVIRONMENT_MODIFICATION
                  "LD_LIBRARY_PATH=path_list_append:"
-                 "${LIBUMF_LIBRARY_DIRS};LD_"
-                 "LIBRARY_PATH=path_list_append:${"
+                 "${LIBUMF_LIBRARY_DIRS};"
+                 "LD_LIBRARY_PATH=path_list_append:${"
                  "LIBHWLOC_LIBRARY_DIRS}")
 endif()
 
 set(EXAMPLE_NAME umf_example_ctl_statistics)
-add_executable(${ EXAMPLE_NAME} ctl_statistics_example.c)
-target_include_directories(${ EXAMPLE_NAME} PRIVATE ${ LIBUMF_INCLUDE_DIRS})
+add_executable(${EXAMPLE_NAME} ctl.c)
+target_include_directories(${EXAMPLE_NAME} PRIVATE ${LIBUMF_INCLUDE_DIRS})
 target_link_directories(
     ${
     EXAMPLE_NAME}
     PRIVATE
     ${
     LIBHWLOC_LIBRARY_DIRS})
-target_link_libraries(${ EXAMPLE_NAME} PRIVATE ${LIBUMF_LIBRARIES} hwloc)
+target_link_libraries(${EXAMPLE_NAME} PRIVATE ${LIBUMF_LIBRARIES} hwloc)
 
 add_test(
     NAME ${EXAMPLE_NAME}
-    COMMAND ${ EXAMPLE_NAME}
-    WORKING_DIRECTORY ${ CMAKE_CURRENT_BINARY_DIR})
+    COMMAND ${EXAMPLE_NAME}
+    WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR})
 
 set_tests_properties(${EXAMPLE_NAME} PROPERTIES LABELS "example-standalone")
 
 if(LINUX)
     # set LD_LIBRARY_PATH
     set_property(
-        TEST ${ EXAMPLE_NAME}
+        TEST ${EXAMPLE_NAME}
         PROPERTY ENVIRONMENT_MODIFICATION
                  "LD_LIBRARY_PATH=path_list_append:"
-                 "${LIBUMF_LIBRARY_DIRS};LD_"
-                 "LIBRARY_PATH=path_list_append:${"
+                 "${LIBUMF_LIBRARY_DIRS};"
+                 "LD_LIBRARY_PATH=path_list_append:${"
                  "LIBHWLOC_LIBRARY_DIRS}")
 endif()

examples/ctl/ctl_statistics_example.c renamed to examples/ctl/ctl.c

@@ -7,11 +7,14 @@
  *
  */
 
-#include "umf/base.h"
 #include <stdbool.h>
 #include <stdio.h>
 
+// This example relies on the experimental CTL API, which may change without
+// notice.
 #include <umf/experimental/ctl.h>
+
+#include <umf/base.h>
 #include <umf/memory_pool.h>
 #include <umf/memory_provider.h>
 #include <umf/pools/pool_disjoint.h>
@@ -153,10 +156,7 @@ int main(void) {
         return -1;
     }
 
-    res = umfMemoryProviderGetName(provider, &provider_name);
-    if (res != UMF_RESULT_SUCCESS || provider_name == NULL) {
-        provider_name = "OS";
-    }
+    umfMemoryProviderGetName(provider, &provider_name);
 
     print_provider_stats("Provider stats before allocation", provider,
                          provider_name);

examples/ctl/ctl_example.c renamed to examples/ctl/custom_ctl.c

@@ -13,20 +13,21 @@
 #include <stdlib.h>
 #include <string.h>
 
+// This example relies on the experimental CTL API, which may change without
+// notice.
+#include <umf/experimental/ctl.h>
+
 #include <umf.h>
 #include <umf/base.h>
-#include <umf/experimental/ctl.h>
+
 #include <umf/memory_provider.h>
 #include <umf/memory_provider_ops.h>
 
 // Minimal memory provider demonstrating CTL integration
 
 // Provider state exposed via CTL
 typedef struct ctl_provider_t {
-    int a;
-    int b;
-    int c;
-    int m; // modulus value, optional
+    int a, b, c, m;
 } ctl_provider_t;
 
 static umf_result_t ctl_init(const void *params, void **provider) {

src/ctl/ctl_defaults.c

@@ -6,11 +6,10 @@
  * SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
  */
 
-#include "ctl_defaults.h"
-
 #include <string.h>
 
 #include "base_alloc_global.h"
+#include "ctl_defaults.h"
 #include "utils_concurrency.h"
 #include "utils_log.h"
 #include "utlist.h"
@@ -33,7 +32,7 @@ umf_result_t ctl_default_subtree(ctl_default_entry_t **list, utils_mutex_t *mtx,
                                  umf_ctl_query_type_t queryType) {
     (void)source;
     if (strstr(extra_name, "{}") != NULL) {
-        LOG_ERR("%s, default setting do not support wildcard parameters {}",
+        LOG_ERR("%s, default setting does not support wildcard parameters {}",
                 extra_name);
         return UMF_RESULT_ERROR_NOT_SUPPORTED;
     }

src/pool/pool_disjoint.c

@@ -28,14 +28,6 @@
 
 static char *DEFAULT_NAME = "disjoint";
 
-enum {
-    DP_OVERRIDE_SLAB_MIN_SIZE = 1 << 0,
-    DP_OVERRIDE_MAX_POOLABLE_SIZE = 1 << 1,
-    DP_OVERRIDE_CAPACITY = 1 << 2,
-    DP_OVERRIDE_MIN_BUCKET_SIZE = 1 << 3,
-    DP_OVERRIDE_POOL_TRACE = 1 << 4,
-};
-
 /* Disjoint pool CTL implementation */
 struct ctl disjoint_ctl_root;
 static UTIL_ONCE_FLAG ctl_initialized = UTIL_ONCE_FLAG_INIT;
@@ -118,6 +110,15 @@ CTL_READ_HANDLER(slab_min_size)(void *ctx, umf_ctl_query_source_t source,
     return UMF_RESULT_SUCCESS;
 }
 
+// indicates that param was overriden by CTL
+enum {
+    DP_OVERRIDE_SLAB_MIN_SIZE = 1 << 0,
+    DP_OVERRIDE_MAX_POOLABLE_SIZE = 1 << 1,
+    DP_OVERRIDE_CAPACITY = 1 << 2,
+    DP_OVERRIDE_MIN_BUCKET_SIZE = 1 << 3,
+    DP_OVERRIDE_POOL_TRACE = 1 << 4,
+};
+
 static umf_result_t
 CTL_WRITE_HANDLER(slab_min_size)(void *ctx, umf_ctl_query_source_t source,
                                  void *arg, size_t size,