Skip to content

Commit a3ba79b

Browse files
PatKaminPatKamin
committed
Add a basic example
Add an example with allocating memory with the usage of OS memory provider and Scalable pool.
1 parent 82bb9fc commit a3ba79b

File tree

14 files changed

+334
-1
lines changed

14 files changed

+334
-1
lines changed

‎.github/workflows/basic.yml

Lines changed: 10 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -55,6 +55,7 @@ jobs:
5555
-DUSE_ASAN=${{matrix.sanitizers.asan}}
5656
-DUSE_UBSAN=${{matrix.sanitizers.ubsan}}
5757
-DUSE_TSAN=${{matrix.sanitizers.tsan}}
58+
-DUMF_BUILD_EXAMPLES=ON
5859
5960
- name: Build UMF
6061
run: |
@@ -63,14 +64,18 @@ jobs:
6364
- name: Run tests
6465
working-directory: ${{github.workspace}}/build
6566
run: |
66-
ctest --output-on-failure
67+
ctest --output-on-failure --test-dir test
6768
6869
- name: Test make install
70+
# Run only when the example is built
71+
if: matrix.os_provider == 'ON' && matrix.pool_tracking == 'ON'
6972
working-directory: ${{env.BUILD_DIR}}
7073
run: ${{github.workspace}}/test/test_make_install.sh \
7174
${{github.workspace}} ${{env.BUILD_DIR}} ${{env.INSTL_DIR}} ${{matrix.build_type}} ${{matrix.shared_library}}
7275

7376
- name: Test make uninstall
77+
# Run only when the example is built
78+
if: matrix.os_provider == 'ON' && matrix.pool_tracking == 'ON'
7479
working-directory: ${{env.BUILD_DIR}}
7580
run: ${{github.workspace}}/test/test_make_uninstall.sh ${{github.workspace}} ${{env.BUILD_DIR}} ${{env.INSTL_DIR}}
7681

@@ -189,11 +194,15 @@ jobs:
189194
ctest --output-on-failure
190195
191196
- name: Test make install
197+
# Run only when the example is built
198+
if: matrix.os_provider == 'ON' && matrix.pool_tracking == 'ON'
192199
working-directory: ${{env.BUILD_DIR}}
193200
run: ${{github.workspace}}/test/test_make_install.sh \
194201
${{github.workspace}} ${{env.BUILD_DIR}} ${{env.INSTL_DIR}} ${{matrix.build_type}} ${{matrix.shared_library}}
195202

196203
- name: Test make uninstall
204+
# Run only when the example is built
205+
if: matrix.os_provider == 'ON' && matrix.pool_tracking == 'ON'
197206
working-directory: ${{env.BUILD_DIR}}
198207
run: ${{github.workspace}}/test/test_make_uninstall.sh ${{github.workspace}} ${{env.BUILD_DIR}} ${{env.INSTL_DIR}}
199208

‎.github/workflows/pr_push.yml

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -49,11 +49,17 @@ jobs:
4949
-DUMF_BUILD_LIBUMF_POOL_DISJOINT=${{matrix.disjoint}}
5050
-DUMF_BUILD_LIBUMF_POOL_JEMALLOC=${{matrix.jemalloc}}
5151
-DUMF_BUILD_TESTS=OFF
52+
-DUMF_BUILD_EXAMPLES=ON
5253
5354
- name: Build
5455
run: >
5556
cmake --build ${{github.workspace}}/build --config Release -j ${{matrix.nproc}}
5657
58+
- name: Run examples
59+
working-directory: ${{github.workspace}}/build
60+
run: |
61+
ctest --output-on-failure --test-dir examples
62+
5763
CodeStyle:
5864
name: Coding style
5965
runs-on: ubuntu-latest

‎CMakeLists.txt

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,7 @@ option(UMF_BUILD_LIBUMF_POOL_JEMALLOC "Build the libumf_pool_jemalloc static lib
1313
option(UMF_BUILD_LIBUMF_POOL_SCALABLE "Build the libumf_pool_scalable static library" OFF)
1414
option(UMF_BUILD_TESTS "Build UMF tests" ON)
1515
option(UMF_BUILD_BENCHMARKS "Build UMF benchmarks" OFF)
16+
option(UMF_BUILD_EXAMPLES "Build UMF examples" ON)
1617
option(UMF_ENABLE_POOL_TRACKING "Build UMF with pool tracking" ON)
1718
option(UMF_DEVELOPER_MODE "Enable developer checks, treats warnings as errors" OFF)
1819
option(UMF_FORMAT_CODE_STYLE "Format UMF code with clang-format" OFF)
@@ -121,6 +122,10 @@ if(UMF_BUILD_BENCHMARKS)
121122
endif()
122123
endif()
123124

125+
if(UMF_BUILD_EXAMPLES)
126+
add_subdirectory(examples)
127+
endif()
128+
124129
# Check if clang-format (in correct version) is available for code formatting.
125130
if(UMF_FORMAT_CODE_STYLE)
126131
find_program(CLANG_FORMAT NAMES clang-format-15 clang-format-15.0 clang-format)

‎README.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -87,6 +87,7 @@ List of options provided by CMake:
8787
| UMF_BUILD_LIBUMF_POOL_SCALABLE | Build the libumf_pool_scalable static library | ON/OFF | OFF |
8888
| UMF_BUILD_TESTS | Build UMF tests | ON/OFF | ON |
8989
| UMF_BUILD_BENCHMARKS | Build UMF benchmarks | ON/OFF | OFF |
90+
| UMF_BUILD_EXAMPLES | Build UMF examples | ON/OFF | ON |
9091
| UMF_ENABLE_POOL_TRACKING | Build UMF with pool tracking | ON/OFF | ON |
9192
| UMF_DEVELOPER_MODE | Treat warnings as errors and enables additional checks | ON/OFF | OFF |
9293
| UMF_FORMAT_CODE_STYLE | Add clang-format-check and clang-format-apply targets to make | ON/OFF | OFF |

‎examples/CMakeLists.txt

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
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+
if(UMF_BUILD_OS_MEMORY_PROVIDER
6+
AND UMF_BUILD_LIBUMF_POOL_SCALABLE
7+
AND UMF_ENABLE_POOL_TRACKING)
8+
set(EXAMPLE_NAME umf_example_basic)
9+
add_umf_executable(NAME ${EXAMPLE_NAME}
10+
SRCS basic/basic.c
11+
LIBS umf
12+
scalable_pool
13+
pthread)
14+
target_include_directories(${EXAMPLE_NAME} PRIVATE
15+
${UMF_CMAKE_SOURCE_DIR}/include)
16+
17+
add_test(NAME ${EXAMPLE_NAME}
18+
COMMAND ${EXAMPLE_NAME}
19+
WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR})
20+
21+
set_tests_properties(${EXAMPLE_NAME} PROPERTIES LABELS "example")
22+
23+
install(TARGETS ${EXAMPLE_NAME}
24+
EXPORT ${PROJECT_NAME}-targets
25+
RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR}
26+
)
27+
28+
else()
29+
message(STATUS "Basic example requires UMF_BUILD_OS_MEMORY_PROVIDER,
30+
UMF_BUILD_LIBUMF_POOL_SCALABLE and UMF_ENABLE_POOL_TRACKING
31+
to be turned ON - skipping")
32+
endif()

‎examples/README.md

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
# Examples
2+
3+
This directory contains examples of UMF usage. Each example has a brief description below.
4+
5+
## Basic
6+
7+
This example covers the basics of UMF API. It walks you through a basic usage of a memory provider and a pool allocator. OS memory provider and Scalable pool are used for this purpose.
8+
9+
### Required CMake configuration flags
10+
* UMF_BUILD_OS_MEMORY_PROVIDER=ON
11+
* UMF_BUILD_LIBUMF_POOL_SCALABLE=ON
12+
* UMF_ENABLE_POOL_TRACKING=ON

‎examples/basic/basic.c

Lines changed: 119 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,119 @@
1+
/*
2+
*
3+
* Copyright (C) 2024 Intel Corporation
4+
*
5+
* Under the Apache License v2.0 with LLVM Exceptions. See LICENSE.TXT.
6+
* SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
7+
*
8+
*/
9+
10+
#include "umf/pools/pool_scalable.h"
11+
#include "umf/providers/provider_os_memory.h"
12+
13+
#include <stdio.h>
14+
#include <string.h>
15+
16+
int main(void) {
17+
// A result object for storing UMF API result status
18+
umf_result_t res;
19+
20+
// Create an OS memory provider. It is used for allocating memory from
21+
// NUMA nodes visible to the operating system.
22+
// Allocations are made with mmap. The default values of params result
23+
// in an mmap call like this:
24+
// mmap(NULL, size, PROT_READ | PROT_WRITE, MAP_ANONYMOUS | MAP_PRIVATE, -1, 0)
25+
umf_memory_provider_ops_t *provider_ops = umfOsMemoryProviderOps();
26+
umf_os_memory_provider_params_t params = umfOsMemoryProviderParamsDefault();
27+
umf_memory_provider_handle_t provider;
28+
29+
res = umfMemoryProviderCreate(provider_ops, &params, &provider);
30+
if (res != UMF_RESULT_SUCCESS) {
31+
printf("Failed to create a memory provider!");
32+
return -1;
33+
}
34+
printf("OS memory provider created at %p\n", (void *)provider);
35+
36+
// Allocate memory from memory provider
37+
size_t alloc_size = 5000;
38+
size_t alignment = 0;
39+
void *ptr_provider = NULL;
40+
41+
/// Allocate memory
42+
res =
43+
umfMemoryProviderAlloc(provider, alloc_size, alignment, &ptr_provider);
44+
if (res != UMF_RESULT_SUCCESS) {
45+
printf("Failed to allocate memory from the memory provider!");
46+
goto memory_provider_destroy;
47+
}
48+
49+
/// Write to the allocated memory
50+
memset(ptr_provider, '\0', alloc_size);
51+
strcpy(ptr_provider, "Allocated memory at");
52+
printf("%s %p\n", (char *)ptr_provider, (void *)ptr_provider);
53+
54+
/// Free allocated memory
55+
res = umfMemoryProviderFree(provider, ptr_provider, alloc_size);
56+
if (res != UMF_RESULT_SUCCESS) {
57+
printf("Failed to free memory to the provider!");
58+
goto memory_provider_destroy;
59+
}
60+
printf("Freed memory at %p\n", ptr_provider);
61+
62+
// Create a memory pool
63+
umf_memory_pool_ops_t *pool_ops = umfScalablePoolOps();
64+
void *pool_params = NULL;
65+
umf_pool_create_flags_t flags = 0;
66+
umf_memory_pool_handle_t pool;
67+
68+
res = umfPoolCreate(pool_ops, provider, pool_params, flags, &pool);
69+
if (res != UMF_RESULT_SUCCESS) {
70+
printf("\nFailed to create a pool!");
71+
goto memory_provider_destroy;
72+
}
73+
printf("\nScalable memory pool created at %p\n", (void *)pool);
74+
75+
// Allocate some memory
76+
size_t num = 1;
77+
alloc_size = 128;
78+
79+
char *ptr = umfPoolCalloc(pool, num, alloc_size);
80+
if (!ptr) {
81+
printf("Failed to allocate memory!");
82+
goto memory_pool_destroy;
83+
}
84+
85+
// Write a string to allocated memory
86+
strcpy(ptr, "Allocated memory at");
87+
printf("%s %p\n", ptr, (void *)ptr);
88+
89+
// Retrieve a memory pool from a pointer, available with memory tracking
90+
umf_memory_pool_handle_t check_pool = umfPoolByPtr(ptr);
91+
printf("Memory at %p has been allocated from the pool at %p\n", (void *)ptr,
92+
(void *)check_pool);
93+
94+
// Retrieve a memory provider from a pool
95+
umf_memory_provider_handle_t check_provider;
96+
res = umfPoolGetMemoryProvider(pool, &check_provider);
97+
if (res != UMF_RESULT_SUCCESS) {
98+
printf("Failed to retrieve a memory provider for the pool!");
99+
goto memory_pool_destroy;
100+
}
101+
printf("Pool at %p has been allocated from the provider at %p\n",
102+
(void *)pool, (void *)check_provider);
103+
104+
// Clean up.
105+
// To free a pointer using the umfFree(ptr) function, ensure that memory tracking is enabled
106+
// by setting the UMF_ENABLE_POOL_TRACKING option in the CMake configuration.
107+
// If the memory tracking is disabled, you can call a different function:
108+
// umfPoolFree(pool, ptr);
109+
umfFree(ptr);
110+
umfPoolDestroy(pool);
111+
umfMemoryProviderDestroy(provider);
112+
return 0;
113+
114+
memory_pool_destroy:
115+
umfPoolDestroy(pool);
116+
memory_provider_destroy:
117+
umfMemoryProviderDestroy(provider);
118+
return -1;
119+
}

‎scripts/docs_config/conf.py

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -37,6 +37,7 @@
3737
# This pattern also affects html_static_path and html_extra_path.
3838
exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
3939

40+
primary_domain = "c"
4041

4142
# -- Options for HTML output -------------------------------------------------
4243

@@ -45,10 +46,15 @@
4546
#
4647
html_theme = "sphinx_book_theme"
4748

49+
# -- Options for the C++ domain ----------------------------------------------
50+
51+
c_id_attributes = ["UMF_EXPORT"]
52+
4853
# -- Extension configuration -------------------------------------------------
4954

5055
# -- Options for breathe extension -------------------------------------------
5156
breathe_projects = {project: "../../docs/xml"}
5257
breathe_default_project = project
5358
breathe_show_include = False
5459
breathe_default_members = ("members", "undoc-members")
60+
breathe_domain_by_extension = {"h": "c"}

‎scripts/docs_config/example-usage.rst

Lines changed: 106 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,106 @@
1+
.. highlight:: c
2+
:linenothreshold: 10
3+
4+
==============================================================================
5+
Example usage
6+
==============================================================================
7+
8+
This section will walk you through a basic usage
9+
of :ref:`memory provider <glossary-memory-provider>`
10+
and :ref:`pool allocator <glossary-pool-allocator>`. OS Memory Provider
11+
and Scalable Pool will be used for this purpose.
12+
13+
There are also other memory pools available in the UMF. See `README`_ for
14+
more information.
15+
16+
You can find the full example code in the `examples/basic/basic.c`_ file
17+
in the UMF repository.
18+
19+
Memory provider usage
20+
------------------------------------------------------------------------------
21+
22+
First, let's create a memory provider object for coarse-grained allocations.
23+
You have to include the `provider_os_memory.h`_ header with
24+
the OS Memory Provider API::
25+
26+
#include "umf/providers/provider_os_memory.h"
27+
28+
Get a pointer to the OS memory provider operations struct and
29+
a copy of default parameters::
30+
31+
umf_memory_provider_ops_t *provider_ops = umfOsMemoryProviderOps();
32+
umf_os_memory_provider_params_t params = umfOsMemoryProviderParamsDefault();
33+
34+
The handle to created memory ``provider`` object is returned as the last argument
35+
of :any:`umfMemoryProviderCreate`::
36+
37+
umf_memory_provider_handle_t provider;
38+
umfMemoryProviderCreate(provider_ops, &params, &provider);
39+
40+
With this handle we can allocate a chunk of memory, call :any:`umfMemoryProviderAlloc`::
41+
42+
size_t alloc_size = 5000;
43+
size_t alignment = 0;
44+
void *ptr_provider = NULL;
45+
umfMemoryProviderAlloc(provider, alloc_size, alignment, &ptr_provider);
46+
47+
To free the memory allocated with a ``provider``, you have to pass the allocated
48+
size as the last parameter of :any:`umfMemoryProviderFree`::
49+
50+
umfMemoryProviderFree(provider, ptr_provider, alloc_size);
51+
52+
Memory pool usage
53+
------------------------------------------------------------------------------
54+
55+
Having created a memory ``provider``, you can create a Scalable Memory ``pool``
56+
to be used for fine-grained allocations. You have to include
57+
the `pool_scalable.h`_ header with the Scalable Memory Pool API::
58+
59+
#include "umf/pools/pool_scalable.h"
60+
61+
Use the default set of operations for the Scalable memory pool
62+
by retrieving an address of the default ops struct::
63+
64+
umf_memory_pool_ops_t *pool_ops = umfScalablePoolOps();
65+
66+
Argument ``pool_params`` is not used by the Scalable Pool, set it to ``NULL``::
67+
68+
void *pool_params = NULL;
69+
70+
Here we don't make use of additional flags. See the :any:`documentation <umf_pool_create_flags_t>`
71+
for available flags::
72+
73+
umf_pool_create_flags_t flags = 0;
74+
75+
The ``pool`` handle is retrieved as the last argument of the :any:`umfPoolCreate` function::
76+
77+
umf_memory_pool_handle_t pool;
78+
umfPoolCreate(pool_ops, provider, pool_params, flags, &pool);
79+
80+
The ``pool`` has been created, we can allocate some memory now with ie. :any:`umfPoolCalloc`::
81+
82+
size_t num = 1;
83+
alloc_size = 128;
84+
char *ptr = umfPoolCalloc(pool, num, alloc_size);
85+
86+
..
87+
RFC: Describe umfPoolByPtr()? Now that the tracker is required to build an example I can add this call.
88+
89+
For any pool, you can retrieve the memory provider's handle
90+
that was used to create the ``pool`` with :any:`umfPoolGetMemoryProvider`::
91+
92+
umf_memory_provider_handle_t check_provider;
93+
umfPoolGetMemoryProvider(pool, &check_provider);
94+
95+
Freeing a memory is as easy as can be::
96+
97+
umfPoolFree(pool, ptr);
98+
umfPoolDestroy(pool);
99+
umfMemoryProviderDestroy(provider);
100+
101+
..
102+
TODO: Update the links to upstream
103+
.. _examples/basic/basic.c: https://github.com/patkamin/unified-memory-framework/blob/main/examples/basic/basic.c
104+
.. _README: https://github.com/patkamin/unified-memory-framework/blob/main/README.md#memory-pool-managers
105+
.. _provider_os_memory.h: https://github.com/patkamin/unified-memory-framework/blob/main/include/umf/providers/provider_os_memory.h
106+
.. _pool_scalable.h: https://github.com/patkamin/unified-memory-framework/blob/main/include/umf/pools/pool_scalable.h

0 commit comments

Comments
 (0)