Skip to content

Commit 66d0504

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 66d0504

File tree

7 files changed

+252
-0
lines changed

7 files changed

+252
-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: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
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+
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: 107 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,107 @@
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+
.. TODO: Add links wherever possible
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 ``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 `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+
As an ``alignment`` value you can set ie. a page size value retrieved from
48+
the `umfMemoryProviderGetRecommendedPageSize` function::
49+
50+
umfMemoryProviderGetRecommendedPageSize(provider, alloc_size, &alignment);
51+
52+
To free the memory allocated with a provider, you have to pass the allocated
53+
size as the last parameter:
54+
55+
umfMemoryProviderFree(provider, ptr_provider, alloc_size);
56+
57+
Memory pool usage
58+
------------------------------------------------------------------------------
59+
60+
Having created a memory ``provider``, you can create a Scalable Memory ``pool``
61+
to be used for fine-grained allocations. You have to include
62+
the ``pool_scalable.h`` header with the Scalable Memory Pool API::
63+
64+
#include "umf/pools/pool_scalable.h"
65+
66+
Use the default set of operations for the Scalable Memory Pool
67+
by retrieving an address of the default ops struct with ``umfScalablePoolOps()``::
68+
69+
umf_memory_pool_ops_t *pool_ops = umfScalablePoolOps();
70+
71+
Argument `pool_params` is not used by the Scalable Pool::
72+
73+
void *pool_params = NULL;
74+
75+
.. TODO: There is no documentation describing the flags yet. Add a link once it's available.
76+
Here we don't make use of additional flags. See the `documentation` for available flags::
77+
78+
umf_pool_create_flags_t flags = 0;
79+
80+
The `pool` handle is retrieved as the last argument of the `umfPoolCreate` function::
81+
82+
umf_memory_pool_handle_t pool;
83+
umfPoolCreate(pool_ops, provider, pool_params, flags, &pool);
84+
85+
The `pool` is created, we can allocate some memory now::
86+
87+
size_t num = 1;
88+
alloc_size = 128;
89+
char *ptr = umfPoolCalloc(pool, num, alloc_size);
90+
91+
.. TODO: Describe umfPoolByPtr()?
92+
93+
For any pool, you can retrieve the memory provider's handle
94+
that was used to create the pool::
95+
96+
umf_memory_provider_handle_t check_provider;
97+
umfPoolGetMemoryProvider(pool, &check_provider);
98+
99+
Freeing a memory is as easy as can be::
100+
101+
umfPoolFree(pool, ptr);
102+
umfPoolDestroy(pool);
103+
umfMemoryProviderDestroy(provider);
104+
105+
.. TODO: Update the links to upstream
106+
.. _examples/basic/basic.c: https://github.com/patkamin/unified-memory-framework/blob/main/examples/basic/basic.c
107+
.. _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)