Skip to content

Commit f602262

Browse files
lplewalplewa
committed
Initial documentation
1 parent 8208bf9 commit f602262

10 files changed

Lines changed: 2111 additions & 6 deletions

File tree

‎docs/config/ctl.rst‎

Lines changed: 1345 additions & 0 deletions
Large diffs are not rendered by default.

‎docs/config/examples.rst‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -147,6 +147,35 @@ in the UMF repository.
147147

148148
TODO
149149

150+
CTL statistics example
151+
==============================================================================
152+
153+
You can find the full example code in the `examples/ctl/ctl_statistics_example.c`_ file
154+
in the UMF repository.
155+
156+
The sample configures an OS memory provider and a disjoint pool, reuses the
157+
provider's canonical ``OS`` selector obtained at runtime, assigns a custom pool
158+
name, and then mixes ``by_handle`` and ``by_name`` selectors to explore CTL
159+
statistics. Wildcard nodes are used to choose provider counters, build a
160+
four-segment ``{}.{}`` chain for the named pool, reset the peak tracker, and
161+
drill into per-bucket disjoint pool telemetry. The program prints hints on ``stderr``
162+
explaining which tracing level is necessary when a statistic is unavailable.
163+
164+
Build and run the example with::
165+
166+
cmake -B build
167+
cmake --build build
168+
./build/examples/umf_example_ctl_statistics
169+
170+
Detailed disjoint pool counters are disabled unless tracing is configured
171+
before pool creation. Enable them through the environment::
172+
173+
UMF_CONF="umf.pool.default.disjoint.params.pool_trace=2" ./build/examples/umf_example_ctl_statistics
174+
175+
Tracing level ``1`` enables slab usage counters, level ``2`` adds allocation
176+
and free statistics, and level ``3`` additionally emits verbose log messages
177+
from the pool implementation.
178+
150179
IPC example with Level Zero Memory Provider
151180
==============================================================================
152181
The full code of the example is in the `examples/ipc_level_zero/ipc_level_zero.c`_ file in the UMF repository.
@@ -231,6 +260,7 @@ the :any:`umfCloseIPCHandle` function is called.
231260
.. _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
232261
.. _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
233262
.. _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
263+
.. _examples/ctl/ctl_statistics_example.c: https://github.com/oneapi-src/unified-memory-framework/blob/main/examples/ctl/ctl_statistics_example.c
234264
.. _examples/memspace: https://github.com/oneapi-src/unified-memory-framework/blob/main/examples/memspace/
235265
.. _README: https://github.com/oneapi-src/unified-memory-framework/blob/main/README.md#memory-pool-managers
236266
.. _umf/ipc.h: https://github.com/oneapi-src/unified-memory-framework/blob/main/include/umf/ipc.h

‎examples/CMakeLists.txt‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -273,6 +273,42 @@ if(LINUX)
273273
WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR})
274274
endif()
275275

276+
set(EXAMPLE_NAME umf_example_ctl)
277+
278+
add_umf_executable(
279+
NAME ${EXAMPLE_NAME}
280+
SRCS ctl/ctl_example.c
281+
LIBS umf ${UMF_HWLOC_NAME})
282+
283+
target_include_directories(
284+
${EXAMPLE_NAME} PRIVATE ${UMF_CMAKE_SOURCE_DIR}/src/utils
285+
${UMF_CMAKE_SOURCE_DIR}/include)
286+
287+
target_link_directories(${EXAMPLE_NAME} PRIVATE ${LIBHWLOC_LIBRARY_DIRS})
288+
289+
add_test(
290+
NAME ${EXAMPLE_NAME}
291+
COMMAND ${EXAMPLE_NAME}
292+
WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR})
293+
294+
set(EXAMPLE_NAME umf_example_ctl_statistics)
295+
296+
add_umf_executable(
297+
NAME ${EXAMPLE_NAME}
298+
SRCS ctl/ctl_statistics_example.c
299+
LIBS umf ${UMF_HWLOC_NAME})
300+
301+
target_include_directories(
302+
${EXAMPLE_NAME} PRIVATE ${UMF_CMAKE_SOURCE_DIR}/src/utils
303+
${UMF_CMAKE_SOURCE_DIR}/include)
304+
305+
target_link_directories(${EXAMPLE_NAME} PRIVATE ${LIBHWLOC_LIBRARY_DIRS})
306+
307+
add_test(
308+
NAME ${EXAMPLE_NAME}
309+
COMMAND ${EXAMPLE_NAME}
310+
WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR})
311+
276312
if(UMF_POOL_JEMALLOC_ENABLED)
277313
set(EXAMPLE_NAME umf_example_dram_and_fsdax)
278314

‎examples/README.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -66,3 +66,14 @@ processes: a producer and a consumer that communicate in the following way
6666
- Producer puts the IPC handle
6767
- Consumer shuts down
6868
- Producer shuts down
69+
70+
## CTL example
71+
72+
This example demonstrates how to add CTL support to a custom memory
73+
provider. It sets variables ``a`` and ``b`` through CTL, plus it allows
74+
for the modulus ``m`` loaded from the environment or a configuration file.
75+
Addition and subtraction operations return results modulo ``m`` and the
76+
result ``c`` can be retrieved using the CTL API. For example, to set the
77+
modulus through an environment variable run::
78+
79+
UMF_CONF="umf.provider.default.ctl.m=10" ./umf_example_ctl

‎examples/ctl/CMakeLists.txt‎

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
#Copyright(C) 2024 Intel Corporation
2+
#Under the Apache License v2.0 with LLVM Exceptions.See LICENSE.TXT.
3+
#SPDX - License - Identifier : Apache - 2.0 WITH LLVM - exception
4+
5+
cmake_minimum_required(VERSION 3.14.0 FATAL_ERROR)
6+
project(umf_example_ctl LANGUAGES C)
7+
enable_testing()
8+
9+
set(UMF_EXAMPLE_DIR "${CMAKE_SOURCE_DIR}/..")
10+
list(APPEND CMAKE_MODULE_PATH "${UMF_EXAMPLE_DIR}/cmake")
11+
message(STATUS "CMAKE_MODULE_PATH=${CMAKE_" "MODULE_PATH}")
12+
13+
find_package(PkgConfig)
14+
pkg_check_modules(LIBUMF libumf)
15+
if(NOT LIBUMF_FOUND)
16+
find_package(LIBUMF REQUIRED libumf)
17+
endif()
18+
19+
pkg_check_modules(LIBHWLOC hwloc >= 2.3.0)
20+
if(NOT LIBHWLOC_FOUND)
21+
find_package(LIBHWLOC 2.3.0 REQUIRED hwloc)
22+
endif()
23+
24+
# build the example
25+
set(EXAMPLE_NAME umf_example_ctl)
26+
add_executable(${ EXAMPLE_NAME} ctl_example.c)
27+
target_include_directories(${ EXAMPLE_NAME} PRIVATE ${ LIBUMF_INCLUDE_DIRS})
28+
target_link_directories(
29+
${
30+
EXAMPLE_NAME}
31+
PRIVATE
32+
${
33+
LIBHWLOC_LIBRARY_DIRS})
34+
target_link_libraries(${ EXAMPLE_NAME} PRIVATE ${LIBUMF_LIBRARIES} hwloc)
35+
36+
add_test(
37+
NAME ${EXAMPLE_NAME}
38+
COMMAND ${ EXAMPLE_NAME}
39+
WORKING_DIRECTORY ${ CMAKE_CURRENT_BINARY_DIR})
40+
41+
set_tests_properties(${EXAMPLE_NAME} PROPERTIES LABELS "example-standalone")
42+
43+
if(LINUX)
44+
# set LD_LIBRARY_PATH
45+
set_property(
46+
TEST ${ EXAMPLE_NAME}
47+
PROPERTY ENVIRONMENT_MODIFICATION
48+
"LD_LIBRARY_PATH=path_list_append:"
49+
"${LIBUMF_LIBRARY_DIRS};LD_"
50+
"LIBRARY_PATH=path_list_append:${"
51+
"LIBHWLOC_LIBRARY_DIRS}")
52+
endif()
53+
54+
set(EXAMPLE_NAME umf_example_ctl_statistics)
55+
add_executable(${ EXAMPLE_NAME} ctl_statistics_example.c)
56+
target_include_directories(${ EXAMPLE_NAME} PRIVATE ${ LIBUMF_INCLUDE_DIRS})
57+
target_link_directories(
58+
${
59+
EXAMPLE_NAME}
60+
PRIVATE
61+
${
62+
LIBHWLOC_LIBRARY_DIRS})
63+
target_link_libraries(${ EXAMPLE_NAME} PRIVATE ${LIBUMF_LIBRARIES} hwloc)
64+
65+
add_test(
66+
NAME ${EXAMPLE_NAME}
67+
COMMAND ${ EXAMPLE_NAME}
68+
WORKING_DIRECTORY ${ CMAKE_CURRENT_BINARY_DIR})
69+
70+
set_tests_properties(${EXAMPLE_NAME} PROPERTIES LABELS "example-standalone")
71+
72+
if(LINUX)
73+
# set LD_LIBRARY_PATH
74+
set_property(
75+
TEST ${ EXAMPLE_NAME}
76+
PROPERTY ENVIRONMENT_MODIFICATION
77+
"LD_LIBRARY_PATH=path_list_append:"
78+
"${LIBUMF_LIBRARY_DIRS};LD_"
79+
"LIBRARY_PATH=path_list_append:${"
80+
"LIBHWLOC_LIBRARY_DIRS}")
81+
endif()

0 commit comments

Comments
 (0)