rename examples and mark ctl as experimental in those

Author: lplewa

README.md

@@ -21,6 +21,11 @@ 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 bespoke memory
+provider. These examples rely on experimental headers whose interfaces 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
 =============
 
@@ -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 drill
+into 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,7 +23,7 @@ endif()
 
 # build the example
 set(EXAMPLE_NAME umf_example_ctl)
-add_executable(${ EXAMPLE_NAME} ctl_example.c)
+add_executable(${ EXAMPLE_NAME} custom_ctl.c)
 target_include_directories(${ EXAMPLE_NAME} PRIVATE ${ LIBUMF_INCLUDE_DIRS})
 target_link_directories(
     ${
@@ -52,7 +52,7 @@ if(LINUX)
 endif()
 
 set(EXAMPLE_NAME umf_example_ctl_statistics)
-add_executable(${ EXAMPLE_NAME} ctl_statistics_example.c)
+add_executable(${ EXAMPLE_NAME} ctl.c)
 target_include_directories(${ EXAMPLE_NAME} PRIVATE ${ LIBUMF_INCLUDE_DIRS})
 target_link_directories(
     ${

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

@@ -12,6 +12,9 @@
 #include <stdio.h>
 
 #include <umf/experimental/ctl.h>
+
+// This example relies on the experimental CTL API, which may change without
+// notice.
 #include <umf/memory_pool.h>
 #include <umf/memory_provider.h>
 #include <umf/pools/pool_disjoint.h>

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

@@ -19,6 +19,9 @@
 #include <umf/memory_provider.h>
 #include <umf/memory_provider_ops.h>
 
+// This example relies on the experimental CTL API, which may change without
+// notice.
+
 // Minimal memory provider demonstrating CTL integration
 
 // Provider state exposed via CTL