Skip to content

Commit 9bdd9cd

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 4d63cd9 commit 9bdd9cd

File tree

9 files changed

+266
-0
lines changed

9 files changed

+266
-0
lines changed

‎CMakeLists.txt

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -121,6 +121,10 @@ if(UMF_BUILD_BENCHMARKS)
121121
endif()
122122
endif()
123123

124+
if(UMF_BUILD_EXAMPLES)
125+
add_subdirectory(examples)
126+
endif()
127+
124128
# Check if clang-format (in correct version) is available for code formatting.
125129
if(UMF_FORMAT_CODE_STYLE)
126130
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
@@ -80,6 +80,7 @@ List of options provided by CMake:
8080
| UMF_BUILD_LIBUMF_POOL_SCALABLE | Build the libumf_pool_scalable static library | ON/OFF | OFF |
8181
| UMF_BUILD_TESTS | Build UMF tests | ON/OFF | ON |
8282
| UMF_BUILD_BENCHMARKS | Build UMF benchmarks | ON/OFF | OFF |
83+
| UMF_BUILD_EXAMPLES | Build UMF examples | ON/OFF | ON |
8384
| UMF_ENABLE_POOL_TRACKING | Build UMF with pool tracking | ON/OFF | ON |
8485
| UMF_DEVELOPER_MODE | Treat warnings as errors and enables additional checks | ON/OFF | OFF |
8586
| UMF_FORMAT_CODE_STYLE | Add clang-format-check and clang-format-apply targets to make | ON/OFF | OFF |

‎examples/CMakeLists.txt

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
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+
add_umf_executable(NAME basic
9+
SRCS basic/basic.c
10+
LIBS umf
11+
scalable_pool
12+
pthread)
13+
target_include_directories(basic PRIVATE
14+
${UMF_CMAKE_SOURCE_DIR}/include)
15+
else()
16+
message(STATUS "Basic example requires UMF_BUILD_OS_MEMORY_PROVIDER,
17+
UMF_BUILD_LIBUMF_POOL_SCALABLE and UMF_ENABLE_POOL_TRACKING
18+
to be turned ON - skipping")
19+
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 memory provider
8+
and pool allocator creation. OS memory provider and Scalable Pool are used for this purpose.
9+
10+
### Required CMake configuration flags
11+
* UMF_BUILD_OS_MEMORY_PROVIDER=ON
12+
* UMF_BUILD_LIBUMF_POOL_SCALABLE=ON

‎examples/basic/basic.c

Lines changed: 118 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,118 @@
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+
// Freeing a pointer can be also done with simpler umfFree(ptr) call.
106+
// Keep in mind that such a call requires the memory tracker to be enabled
107+
// with the UMF_ENABLE_POOL_TRACKING CMake configuration option.
108+
umfPoolFree(pool, ptr);
109+
umfPoolDestroy(pool);
110+
umfMemoryProviderDestroy(provider);
111+
return 0;
112+
113+
memory_pool_destroy:
114+
umfPoolDestroy(pool);
115+
memory_provider_destroy:
116+
umfMemoryProviderDestroy(provider);
117+
return -1;
118+
}

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

‎scripts/docs_config/index.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,5 +8,6 @@ Intel Unified Memory Framework documentation
88
:maxdepth: 3
99

1010
introduction.rst
11+
example-usage.rst
1112
api.rst
1213
glossary.rst

‎third_party/requirements.txt

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@
22
# Formatting the source code
33
clang-format==15.0.7
44
# Generating HTML documentation
5+
pygments==2.5.2
56
sphinxcontrib_applehelp==1.0.4
67
sphinxcontrib_devhelp==1.0.2
78
sphinxcontrib_htmlhelp==2.0.1

0 commit comments

Comments
 (0)