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
103
@@ -20,13 +107,13 @@ UMF comes with predefined pool allocators (see include/pool) and providers (see
20
107
21
108
More detailed documentation is available here: https://oneapi-src.github.io/unified-memory-framework/
22
109
23
-
## Memory providers
110
+
###Memory providers
24
111
25
-
### OS memory provider (Linux-only yet)
112
+
####OS memory provider (Linux-only yet)
26
113
27
114
A memory provider that provides memory from an operating system.
28
115
29
-
#### Requirements
116
+
#####Requirements
30
117
31
118
1) Linux OS
32
119
2) The `UMF_BUILD_OS_MEMORY_PROVIDER` option turned `ON` (by default)
@@ -35,103 +122,44 @@ A memory provider that provides memory from an operating system.
35
122
4) Required packages for tests:
36
123
- libnuma-dev
37
124
38
-
## Memory pool managers
125
+
###Memory pool managers
39
126
40
-
### proxy_pool (part of libumf)
127
+
####proxy_pool (part of libumf)
41
128
42
129
This memory pool is distributed as part of libumf. It forwards all requests to the underlying
43
130
memory provider. Currently umfPoolRealloc, umfPoolCalloc and umfPoolMallocUsableSize functions
44
131
are not supported by the proxy pool.
45
132
46
-
### libumf_pool_disjoint
133
+
####libumf_pool_disjoint
47
134
48
135
TODO: Add a description
49
136
50
-
#### Requirements
137
+
#####Requirements
51
138
52
139
To enable this feature, the `UMF_BUILD_LIBUMF_POOL_DISJOINT` option needs to be turned `ON`.
53
140
54
-
### libumf_pool_jemalloc (Linux-only)
141
+
####libumf_pool_jemalloc (Linux-only)
55
142
56
143
libumf_pool_jemalloc is a [jemalloc](https://github.com/jemalloc/jemalloc)-based memory pool manager built as a separate static library.
57
144
The `UMF_BUILD_LIBUMF_POOL_JEMALLOC` option has to be turned `ON` to build this library.
58
145
59
-
#### Requirements
146
+
#####Requirements
60
147
61
148
1) The `UMF_BUILD_LIBUMF_POOL_JEMALLOC` option turned `ON`
62
149
2) Required packages:
63
150
- libjemalloc-dev
64
151
65
-
### libumf_pool_scalable (Linux-only)
152
+
####libumf_pool_scalable (Linux-only)
66
153
67
154
libumf_pool_scalable is a [oneTBB](https://github.com/oneapi-src/oneTBB)-based memory pool manager built as a separate static library.
68
155
The `UMF_BUILD_LIBUMF_POOL_SCALABLE` option has to be turned `ON` to build this library.
69
156
70
-
#### Requirements
157
+
#####Requirements
71
158
72
159
1) The `UMF_BUILD_LIBUMF_POOL_SCALABLE` option turned `ON`
73
160
2) Required packages:
74
161
- libtbb-dev (libraries: libtbbmalloc.so.2)
75
162
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
163
## Contributions
136
164
137
165
All code has to be formatted using clang-format. To check the formatting do:
@@ -148,24 +176,3 @@ Additionally, to apply code formatting do:
148
176
```bash
149
177
$ make clang-format-apply
150
178
```
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 |
0 commit comments