Skip to content

Commit c49413c

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 c49413c

File tree

7 files changed

+260
-0
lines changed

7 files changed

+260
-0
lines changed

‎CMakeLists.txt

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -108,6 +108,7 @@ install(
108108
EXPORT ${PROJECT_NAME}-targets)
109109

110110
add_subdirectory(src)
111+
add_subdirectory(examples)
111112

112113
if(UMF_BUILD_TESTS)
113114
add_subdirectory(test)

‎examples/CMakeLists.txt

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
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 AND UMF_BUILD_LIBUMF_POOL_SCALABLE)
6+
add_umf_executable(NAME basic
7+
SRCS basic/basic.c
8+
LIBS umf
9+
scalable_pool
10+
pthread)
11+
target_include_directories(basic PRIVATE
12+
${UMF_CMAKE_SOURCE_DIR}/include)
13+
else()
14+
message(STATUS "Basic example requires UMF_BUILD_OS_MEMORY_PROVIDER and
15+
UMF_BUILD_LIBUMF_POOL_SCALABLE to be turned ON - skipping")
16+
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: 117 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,117 @@
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 a memory provider
21+
umf_memory_provider_ops_t *provider_ops = umfOsMemoryProviderOps();
22+
umf_os_memory_provider_params_t params = umfOsMemoryProviderParamsDefault();
23+
umf_memory_provider_handle_t provider;
24+
25+
res = umfMemoryProviderCreate(provider_ops, &params, &provider);
26+
if (res != UMF_RESULT_SUCCESS) {
27+
printf("Failed to create provider!");
28+
return -1;
29+
}
30+
printf("OS Memory Provider created at %p\n", (void *)provider);
31+
32+
// Allocate memory from memory provider
33+
size_t alloc_size = 5000;
34+
size_t alignment = 0;
35+
void *ptr_provider = NULL;
36+
37+
/// Get recommended page size for a proper alignment value
38+
res = umfMemoryProviderGetRecommendedPageSize(provider, alloc_size,
39+
&alignment);
40+
if (res != UMF_RESULT_SUCCESS || alignment == 0) {
41+
printf("Failed to get recommended page size!");
42+
goto memory_provider_destroy;
43+
}
44+
printf("Recommended page size is %zu bytes\n", alignment);
45+
46+
/// Allocate memory
47+
res =
48+
umfMemoryProviderAlloc(provider, alloc_size, alignment, &ptr_provider);
49+
if (res != UMF_RESULT_SUCCESS) {
50+
printf("Failed to allocate memory from the provider!");
51+
goto memory_provider_destroy;
52+
}
53+
printf("Allocated memory at %p\n", ptr_provider);
54+
55+
/// Free allocated memory
56+
res = umfMemoryProviderFree(provider, ptr_provider, alloc_size);
57+
if (res != UMF_RESULT_SUCCESS) {
58+
printf("Failed to free memory to the provider!");
59+
goto memory_provider_destroy;
60+
}
61+
printf("Freed memory at %p\n", ptr_provider);
62+
63+
// Create a memory pool
64+
umf_memory_pool_ops_t *pool_ops = umfScalablePoolOps();
65+
void *pool_params = NULL;
66+
umf_pool_create_flags_t flags = 0;
67+
umf_memory_pool_handle_t pool;
68+
69+
res = umfPoolCreate(pool_ops, provider, pool_params, flags, &pool);
70+
if (res != UMF_RESULT_SUCCESS) {
71+
printf("\nFailed to create pool!");
72+
goto memory_provider_destroy;
73+
}
74+
printf("\nScalable Memory Pool created at %p\n", (void *)pool);
75+
76+
// Allocate some memory
77+
size_t num = 1;
78+
alloc_size = 128;
79+
80+
char *ptr = umfPoolCalloc(pool, num, alloc_size);
81+
if (!ptr) {
82+
printf("Failed to allocate memory!");
83+
goto memory_pool_destroy;
84+
}
85+
86+
// Write a string to allocated memory
87+
strcpy(ptr, "Allocated memory at");
88+
printf("%s %p\n", ptr, (void *)ptr);
89+
90+
// Retrieve a memory pool from a pointer, available with memory tracking
91+
// RFC: Remove this? With memory tracker disabled, NULL returned may be misleading
92+
umf_memory_pool_handle_t check_pool = umfPoolByPtr(ptr);
93+
printf("Memory at %p has been allocated from pool at %p\n", (void *)ptr,
94+
(void *)check_pool);
95+
96+
// Retrieve a memory provider from a pool
97+
umf_memory_provider_handle_t check_provider;
98+
res = umfPoolGetMemoryProvider(pool, &check_provider);
99+
if (res != UMF_RESULT_SUCCESS) {
100+
printf("Failed to retrieve a memory provider for pool!");
101+
goto memory_pool_destroy;
102+
}
103+
printf("Pool at %p has been allocated from provider at %p\n", (void *)pool,
104+
(void *)check_provider);
105+
106+
// Clean up
107+
umfPoolFree(pool, ptr);
108+
umfPoolDestroy(pool);
109+
umfMemoryProviderDestroy(provider);
110+
return 0;
111+
112+
memory_pool_destroy:
113+
umfPoolDestroy(pool);
114+
memory_provider_destroy:
115+
umfMemoryProviderDestroy(provider);
116+
return -1;
117+
}

‎scripts/docs_config/example-usage.rst

Lines changed: 112 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,112 @@
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+
..
21+
TODO: Add links wherever possible
22+
23+
First, let's create a memory provider object for coarse-grained allocations.
24+
You have to include the ``provider_os_memory.h`` header with
25+
the OS Memory Provider API::
26+
27+
#include "umf/providers/provider_os_memory.h"
28+
29+
Get a pointer to the OS Memory Provider operations struct and
30+
a copy of default parameters::
31+
32+
umf_memory_provider_ops_t *provider_ops = umfOsMemoryProviderOps();
33+
umf_os_memory_provider_params_t params = umfOsMemoryProviderParamsDefault();
34+
35+
The handle to created memory ``provider`` object is returned as the last argument
36+
of :any:`umfMemoryProviderCreate`::
37+
38+
umf_memory_provider_handle_t provider;
39+
umfMemoryProviderCreate(provider_ops, &params, &provider);
40+
41+
With this handle we can allocate a chunk of memory, call `umfMemoryProviderAlloc()`::
42+
43+
size_t alloc_size = 5000;
44+
size_t alignment = 0;
45+
void *ptr_provider = NULL;
46+
umfMemoryProviderAlloc(provider, alloc_size, alignment, &ptr_provider);
47+
48+
As an ``alignment`` value you can set ie. a page size value retrieved from
49+
the `umfMemoryProviderGetRecommendedPageSize` function::
50+
51+
umfMemoryProviderGetRecommendedPageSize(provider, alloc_size, &alignment);
52+
53+
To free the memory allocated with a provider, you have to pass the allocated
54+
size as the last parameter::
55+
56+
umfMemoryProviderFree(provider, ptr_provider, alloc_size);
57+
58+
Memory pool usage
59+
------------------------------------------------------------------------------
60+
61+
Having created a memory ``provider``, you can create a Scalable Memory ``pool``
62+
to be used for fine-grained allocations. You have to include
63+
the ``pool_scalable.h`` header with the Scalable Memory Pool API::
64+
65+
#include "umf/pools/pool_scalable.h"
66+
67+
Use the default set of operations for the Scalable Memory Pool
68+
by retrieving an address of the default ops struct with ``umfScalablePoolOps()``::
69+
70+
umf_memory_pool_ops_t *pool_ops = umfScalablePoolOps();
71+
72+
Argument `pool_params` is not used by the Scalable Pool::
73+
74+
void *pool_params = NULL;
75+
76+
..
77+
TODO: There is no documentation describing the flags yet. Add a link once it's available.
78+
79+
Here we don't make use of additional flags. See the `documentation` for available flags::
80+
81+
umf_pool_create_flags_t flags = 0;
82+
83+
The `pool` handle is retrieved as the last argument of the `umfPoolCreate` function::
84+
85+
umf_memory_pool_handle_t pool;
86+
umfPoolCreate(pool_ops, provider, pool_params, flags, &pool);
87+
88+
The `pool` is created, we can allocate some memory now::
89+
90+
size_t num = 1;
91+
alloc_size = 128;
92+
char *ptr = umfPoolCalloc(pool, num, alloc_size);
93+
94+
..
95+
TODO: Describe umfPoolByPtr()?
96+
97+
For any pool, you can retrieve the memory provider's handle
98+
that was used to create the pool::
99+
100+
umf_memory_provider_handle_t check_provider;
101+
umfPoolGetMemoryProvider(pool, &check_provider);
102+
103+
Freeing a memory is as easy as can be::
104+
105+
umfPoolFree(pool, ptr);
106+
umfPoolDestroy(pool);
107+
umfMemoryProviderDestroy(provider);
108+
109+
..
110+
TODO: Update the links to upstream
111+
.. _examples/basic/basic.c: https://github.com/patkamin/unified-memory-framework/blob/main/examples/basic/basic.c
112+
.. _README: https://github.com/patkamin/unified-memory-framework/blob/main/README.md#memory-pool-managers

‎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)