Skip to content

Commit 21c4d8e

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 21c4d8e

File tree

10 files changed

+300
-0
lines changed

10 files changed

+300
-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: 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)