You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
The Unified Memory Framework (UMF) is a library for constructing allocators and memory pools. It also contains broadly useful abstractions and utilities for memory management. UMF allows users to manage multiple memory pools characterized by different attributes, allowing certain allocation types to be isolated from others and allocated using different hardware resources as required.
12
14
13
-
# Architecture: memory pools and providers
15
+
## Usage
16
+
17
+
For a quick introduction to UMF usage, see [Example usage](https://oneapi-src.github.io/unified-memory-framework/example-usage.html),
18
+
which includes the code of the basic [example](https://github.com/oneapi-src/unified-memory-framework/blob/main/examples/basic/basic.c).
19
+
20
+
## Build
21
+
22
+
### Requirements
23
+
24
+
Required packages:
25
+
- C compiler
26
+
-[CMake](https://cmake.org/) >= 3.14.0
27
+
28
+
For development and contributions:
29
+
- clang-format-15.0 (can be installed with `python -m pip install clang-format==15.0.7`)
30
+
31
+
For building tests, multithreaded benchmarks and Disjoint Pool:
32
+
- C++ compiler with C++17 support
33
+
34
+
### Linux
35
+
36
+
Executable and binaries will be in **build/bin**
37
+
38
+
```bash
39
+
$ mkdir build
40
+
$ cd build
41
+
$ cmake {path_to_source_dir}
42
+
$ make
43
+
```
44
+
45
+
### Windows
46
+
47
+
Generating Visual Studio Project. EXE and binaries will be in **build/bin/{build_config}**
48
+
49
+
```bash
50
+
$ mkdir build
51
+
$ cd build
52
+
$ cmake {path_to_source_dir} -G "Visual Studio 15 2017 Win64"
53
+
```
54
+
55
+
### Benchmark
56
+
57
+
UMF comes with a single-threaded micro benchmark based on [ubench](https://github.com/sheredom/ubench.h).
58
+
In order to build the benchmark, the `UMF_BUILD_BENCHMARKS` CMake configuration flag has to be turned `ON`.
59
+
60
+
UMF also provides multithreaded benchmarks that can be enabled by setting both
61
+
`UMF_BUILD_BENCHMARKS` and `UMF_BUILD_BENCHMARKS_MT` CMake
62
+
configuration flags to `ON`. Multithreaded benchmarks require a C++ support.
63
+
64
+
### Sanitizers
65
+
66
+
List of sanitizers available on Linux:
67
+
- AddressSanitizer
68
+
- UndefinedBehaviorSanitizer
69
+
- ThreadSanitizer
70
+
- Is mutually exclusive with other sanitizers.
71
+
- MemorySanitizer
72
+
- Requires linking against MSan-instrumented libraries to prevent false positive reports. More information [here](https://github.com/google/sanitizers/wiki/MemorySanitizerLibcxxHowTo).
73
+
74
+
List of sanitizers available on Windows:
75
+
- AddressSanitizer
76
+
77
+
Listed sanitizers can be enabled with appropriate [CMake options](#cmake-standard-options).
78
+
79
+
### CMake standard options
80
+
81
+
List of options provided by CMake:
82
+
83
+
| Name | Description | Values | Default |
84
+
| - | - | - | - |
85
+
| UMF_BUILD_SHARED_LIBRARY | Build UMF as shared library | ON/OFF | OFF |
86
+
| UMF_BUILD_OS_MEMORY_PROVIDER | Build OS memory provider | ON/OFF | ON |
87
+
| UMF_BUILD_LIBUMF_POOL_DISJOINT | Build the libumf_pool_disjoint static library | ON/OFF | OFF |
88
+
| UMF_BUILD_LIBUMF_POOL_JEMALLOC | Build the libumf_pool_jemalloc static library | ON/OFF | OFF |
89
+
| UMF_BUILD_LIBUMF_POOL_SCALABLE | Build the libumf_pool_scalable static library | ON/OFF | OFF |
A UMF memory pool is a combination of a pool allocator and a memory provider. A memory provider is responsible for coarse-grained memory allocations and management of memory pages, while the pool allocator controls memory pooling and handles fine-grained memory allocations.
16
104
@@ -20,13 +108,13 @@ UMF comes with predefined pool allocators (see include/pool) and providers (see
20
108
21
109
More detailed documentation is available here: https://oneapi-src.github.io/unified-memory-framework/
22
110
23
-
## Memory providers
111
+
###Memory providers
24
112
25
-
### OS memory provider (Linux-only yet)
113
+
####OS memory provider (Linux-only yet)
26
114
27
115
A memory provider that provides memory from an operating system.
28
116
29
-
#### Requirements
117
+
#####Requirements
30
118
31
119
1) Linux OS
32
120
2) The `UMF_BUILD_OS_MEMORY_PROVIDER` option turned `ON` (by default)
@@ -35,103 +123,44 @@ A memory provider that provides memory from an operating system.
35
123
4) Required packages for tests:
36
124
- libnuma-dev
37
125
38
-
## Memory pool managers
126
+
###Memory pool managers
39
127
40
-
### proxy_pool (part of libumf)
128
+
####proxy_pool (part of libumf)
41
129
42
130
This memory pool is distributed as part of libumf. It forwards all requests to the underlying
43
131
memory provider. Currently umfPoolRealloc, umfPoolCalloc and umfPoolMallocUsableSize functions
44
132
are not supported by the proxy pool.
45
133
46
-
### libumf_pool_disjoint
134
+
####libumf_pool_disjoint
47
135
48
136
TODO: Add a description
49
137
50
-
#### Requirements
138
+
#####Requirements
51
139
52
140
To enable this feature, the `UMF_BUILD_LIBUMF_POOL_DISJOINT` option needs to be turned `ON`.
53
141
54
-
### libumf_pool_jemalloc (Linux-only)
142
+
####libumf_pool_jemalloc (Linux-only)
55
143
56
144
libumf_pool_jemalloc is a [jemalloc](https://github.com/jemalloc/jemalloc)-based memory pool manager built as a separate static library.
57
145
The `UMF_BUILD_LIBUMF_POOL_JEMALLOC` option has to be turned `ON` to build this library.
58
146
59
-
#### Requirements
147
+
#####Requirements
60
148
61
149
1) The `UMF_BUILD_LIBUMF_POOL_JEMALLOC` option turned `ON`
62
150
2) Required packages:
63
151
- libjemalloc-dev
64
152
65
-
### libumf_pool_scalable (Linux-only)
153
+
####libumf_pool_scalable (Linux-only)
66
154
67
155
libumf_pool_scalable is a [oneTBB](https://github.com/oneapi-src/oneTBB)-based memory pool manager built as a separate static library.
68
156
The `UMF_BUILD_LIBUMF_POOL_SCALABLE` option has to be turned `ON` to build this library.
69
157
70
-
#### Requirements
158
+
#####Requirements
71
159
72
160
1) The `UMF_BUILD_LIBUMF_POOL_SCALABLE` option turned `ON`
73
161
2) Required packages:
74
162
- libtbb-dev (libraries: libtbbmalloc.so.2)
75
163
76
-
## Building
77
-
78
-
### Requirements
79
-
80
-
Required packages:
81
-
- C compiler
82
-
-[CMake](https://cmake.org/) >= 3.14.0
83
-
84
-
For development and contributions:
85
-
- clang-format-15.0 (can be installed with `python -m pip install clang-format==15.0.7`)
86
-
87
-
For building tests, multithreaded benchmarks and Disjoint Pool:
88
-
- C++ compiler with C++17 support
89
-
90
-
### Benchmark
91
-
92
-
UMF comes with a single-threaded micro benchmark based on [ubench](https://github.com/sheredom/ubench.h).
93
-
In order to build the benchmark, the `UMF_BUILD_BENCHMARKS` CMake configuration flag has to be turned `ON`.
94
-
95
-
UMF also provides multithreaded benchmarks that can be enabled by setting both
96
-
`UMF_BUILD_BENCHMARKS` and `UMF_BUILD_BENCHMARKS_MT` CMake
97
-
configuration flags to `ON`. Multithreaded benchmarks require a C++ support.
98
-
99
-
### Windows
100
-
101
-
Generating Visual Studio Project. EXE and binaries will be in **build/bin/{build_config}**
102
-
103
-
```bash
104
-
$ mkdir build
105
-
$ cd build
106
-
$ cmake {path_to_source_dir} -G "Visual Studio 15 2017 Win64"
107
-
```
108
-
109
-
### Linux
110
-
111
-
Executable and binaries will be in **build/bin**
112
-
113
-
```bash
114
-
$ mkdir build
115
-
$ cd build
116
-
$ cmake {path_to_source_dir}
117
-
$ make
118
-
```
119
-
120
-
### Sanitizers
121
-
122
-
List of sanitizers available on Linux:
123
-
- AddressSanitizer
124
-
- UndefinedBehaviorSanitizer
125
-
- ThreadSanitizer
126
-
- Is mutually exclusive with other sanitizers.
127
-
- MemorySanitizer
128
-
- Requires linking against MSan-instrumented libraries to prevent false positive reports. More information [here](https://github.com/google/sanitizers/wiki/MemorySanitizerLibcxxHowTo).
129
-
130
-
List of sanitizers available on Windows:
131
-
- AddressSanitizer
132
-
133
-
Listed sanitizers can be enabled with appropriate [CMake options](#cmake-standard-options).
134
-
135
164
## Contributions
136
165
137
166
All code has to be formatted using clang-format. To check the formatting do:
@@ -148,24 +177,3 @@ Additionally, to apply code formatting do:
148
177
```bash
149
178
$ make clang-format-apply
150
179
```
151
-
152
-
### CMake standard options
153
-
154
-
List of options provided by CMake:
155
-
156
-
| Name | Description | Values | Default |
157
-
| - | - | - | - |
158
-
| UMF_BUILD_SHARED_LIBRARY | Build UMF as shared library | ON/OFF | OFF |
159
-
| UMF_BUILD_OS_MEMORY_PROVIDER | Build OS memory provider | ON/OFF | ON |
160
-
| UMF_BUILD_LIBUMF_POOL_DISJOINT | Build the libumf_pool_disjoint static library | ON/OFF | OFF |
161
-
| UMF_BUILD_LIBUMF_POOL_JEMALLOC | Build the libumf_pool_jemalloc static library | ON/OFF | OFF |
162
-
| UMF_BUILD_LIBUMF_POOL_SCALABLE | Build the libumf_pool_scalable static library | ON/OFF | OFF |
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.
0 commit comments