1MEMKIND(3) MEMKIND MEMKIND(3)
2
6 memkind - Heap manager that enables allocations to memory with differ‐
7 ent properties.
8 This header expose STANDARD and EXPERIMENTAL API. API Standards are de‐
9 scribed below in this man page.
10
12 #include <memkind.h>
13 Link with -lmemkind
15 EXPERIMENTAL API:
17 HEAP MANAGEMENT:
18 int memkind_posix_memalign(memkind_t kind, void **memptr, size_t align‐
19 ment, size_t size);
20 KIND MANAGEMENT:
22 int memkind_create_kind(memkind_memtype_t memtype_flags, memkind_pol‐
23 icy_t policy, memkind_bits_t flags, memkind_t *kind);
24 STANDARD API:
27 ERROR HANDLING:
28 void memkind_error_message(int err, char *msg, size_t size);
29 LIBRARY VERSION:
31 int memkind_get_version();
32 HEAP MANAGEMENT:
34 void *memkind_malloc(memkind_t kind, size_t size);
35 void *memkind_calloc(memkind_t kind, size_t num, size_t size);
36 void *memkind_realloc(memkind_t kind, void *ptr, size_t size);
37 void memkind_free(memkind_t kind, void *ptr);
38 size_t memkind_malloc_usable_size(memkind_t kind, void *ptr);
39 void *memkind_defrag_reallocate(memkind_t kind, void *ptr);
40 memkind_t memkind_detect_kind(void *ptr);
41 KIND CONFIGURATION MANAGEMENT:
43 struct memkind_config *memkind_config_new();
44 void memkind_config_delete(struct memkind_config *cfg);
45 void memkind_config_set_path(struct memkind_config *cfg, const char
46 *pmem_dir);
47 void memkind_config_set_size(struct memkind_config *cfg, size_t
48 pmem_size);
49 void memkind_config_set_memory_usage_policy(struct memkind_config *cfg,
50 memkind_mem_usage_policy policy);
51 KIND MANAGEMENT:
53 int memkind_create_pmem(const char *dir, size_t max_size, memkind_t
54 *kind);
55 int memkind_create_pmem_with_config(struct memkind_config *cfg,
56 memkind_t *kind);
57 int memkind_destroy_kind(memkind_t kind);
58 int memkind_check_available(memkind_t kind);
59 STATISTICS:
61 int memkind_update_cached_stats(void);
62 int memkind_get_stat(memkind_t kind, memkind_stat stat, size_t *value);
63 DECORATORS:
65 void memkind_malloc_pre(memkind_t *kind, size_t *size);
66 void memkind_malloc_post(memkind_t kind, size_t size, void **result);
67 void memkind_calloc_pre(memkind_t *kind, size_t *nmemb, size_t *size);
68 void memkind_calloc_post(memkind_t kind, size_t nmemb, size_t size,
69 void **result);
70 void memkind_posix_memalign_pre(memkind_t *kind, void **memptr, size_t
71 *alignment, size_t *size);
72 void memkind_posix_memalign_post(memkind_t kind, void **memptr, size_t
73 alignment, size_t size, int *err);
74 void memkind_realloc_pre(memkind_t *kind, void **ptr, size_t *size);
75 void memkind_realloc_post(memkind_t *kind, void *ptr, size_t size, void
76 **result);
77 void memkind_free_pre(memkind_t *kind, void **ptr);
78 void memkind_free_post(memkind_t kind, void *ptr);
79
83 memkind_error_message() converts an error number err returned by a mem‐
84 ber of the memkind interface to an error message msg where the maximum
85 size of the message is passed by the size parameter.
86 HEAP MANAGEMENT:
88 The functions described in this section define a heap manager with an
89 interface modeled on the ISO C standard API's, except that the user
90 must specify the kind of memory with the first argument to each func‐
91 tion. See the KINDS section below for a full description of the imple‐
92 mented kinds. For file-backed kind of memory see memkind_create_pmem()
93 or memkind_create_pmem_with_config().
94 memkind_malloc() allocates size bytes of uninitialized memory of the
96 specified kind. The allocated space is suitably aligned (after possi‐
97 ble pointer coercion) for storage of any type of object. If size is 0,
98 then memkind_malloc() returns NULL.
99 memkind_calloc() allocates space for num objects each size bytes in
101 length in memory of the specified kind. The result is identical to
102 calling memkind_malloc() with an argument of num * size, with the ex‐
103 ception that the allocated memory is explicitly initialized to zero
104 bytes. If num or size is 0, then memkind_calloc() returns NULL.
105 memkind_realloc() changes the size of the previously allocated memory
107 referenced by ptr to size bytes of the specified kind. The contents of
108 the memory remain unchanged up to the lesser of the new and old sizes.
109 If the new size is larger, the contents of the newly allocated portion
110 of the memory are undefined. Upon success, the memory referenced by ptr
111 is freed and a pointer to the newly allocated memory is returned.
112 Note: memkind_realloc() may move the memory allocation, resulting in a
114 different return value than ptr.
115 If ptr is NULL, the memkind_realloc() function behaves identically to
117 memkind_malloc() for the specified size. If size is equal to zero, and
118 ptr is not NULL, then the call is equivalent to memkind_free(kind, ptr)
119 and NULL is returned. The address ptr, if not NULL, must have been re‐
120 turned by a previous call to memkind_malloc(), memkind_calloc(),
121 memkind_realloc(), memkind_defrag_reallocate() or memkind_posix_mema‐
122 lign() with the same kind as specified to the call to memkind_real‐
123 loc(). Otherwise, if memkind_free(kind, ptr) was called before, unde‐
124 fined behavior occurs. In cases where the kind is unknown in the con‐
125 text of the call to memkind_realloc() NULL can be given as the kind
126 specified to memkind_realloc(), but this will require an internal look
127 up for correct kind. Note: The look up for kind could result in seri‐
128 ous performance penalty, which can be avoided by specifying a correct
129 kind. If kind is NULL and ptr is NULL, then memkind_realloc() returns
130 NULL and sets errno to EINVAL.
131 memkind_posix_memalign() allocates size bytes of memory of a specified
133 kind such that the allocation's base address is an even multiple of
134 alignment, and returns the allocation in the value pointed to by
135 memptr. The requested alignment must be a power of 2 at least as large
136 as sizeof(void*). If size is 0, then memkind_posix_memalign() returns
137 0, with a NULL returned in memptr.
138 memkind_malloc_usable_size() function provides the same semantics as
140 malloc_usable_size(3), but operates on specified kind.
141 Note: In cases where the kind is unknown in the context of the call to
142 memkind_malloc_usable_size() NULL can be given as the kind specified to
143 memkind_malloc_usable_size(), but this could require a internal look up
144 for correct kind. memkind_malloc_usable_size() is supported by TBB
145 heap manager described in ENVIRONMENT section since Intel TBB 2019 Up‐
146 date 4.
147 memkind_defrag_reallocate() reallocates the object conditionally inside
149 specific kind. Function determines if it's worthwhile to move alloca‐
150 tion to reduce degree of external fragmentation of the heap. In case
151 of failure function returns NULL, otherwise function returns a pointer
152 to reallocated memory and memory referenced by ptr was released and
153 should not be accessed. If ptr is NULL, then memkind_defrag_reallo‐
154 cate() returns NULL. In cases where the kind is unknown in the context
155 of the call to memkind_defrag_reallocate() NULL can be given as the
156 kind specified to memkind_defrag_reallocate(), but this will require an
157 internal look up for correct kind. Note: The look up for kind could
158 result in serious performance penalty, which can be avoided by specify‐
159 ing a correct kind.
160 memkind_detect_kind() returns the kind associated with allocated memory
162 referenced by ptr. This pointer must have been returned by a previous
163 call to memkind_malloc(), memkind_calloc(), memkind_realloc(),
164 memkind_defrag_reallocate() or memkind_posix_memalign(). If ptr is
165 NULL, then memkind_detect_kind() returns NULL. Note: This function has
166 non-trivial performance overhead.
167 memkind_free() causes the allocated memory referenced by ptr to be made
169 available for future allocations. This pointer must have been returned
170 by a previous call to memkind_malloc(), memkind_calloc(), memkind_real‐
171 loc(), memkind_defrag_reallocate() or memkind_posix_memalign(). Other‐
172 wise, if memkind_free(kind, ptr) was already called before, undefined
173 behavior occurs. If ptr is NULL, no operation is performed. In cases
174 where the kind is unknown in the context of the call to memkind_free()
175 NULL can be given as the kind specified to memkind_free(), but this
176 will require an internal look up for correct kind. Note: The look up
177 for kind could result in serious performance penalty, which can be
178 avoided by specifying a correct kind.
179 KIND CONFIGURATION MANAGEMENT:
181 The functions described in this section define a way to create, delete
182 and update kind specific configuration. Except of memkind_con‐
183 fig_new(), user must specify the memkind configuration with the first
184 argument to each function. API described here is most useful with
185 file-backed kind of memory, e.g. memkind_create_pmem_with_config()
186 method.
187 memkind_config_new() creates the memkind configuration.
189 memkind_config_delete() deletes previously created memkind configura‐
191 tion, which must have been returned by a previous call to memkind_con‐
192 fig_new().
193 memkind_config_set_path() updates the memkind pmem_dir configuration
195 parameter, which specifies directory path, where file-backed kind of
196 memory will be created. Note: This function does not validate that
197 pmem_dir specifies a valid path.
198 memkind_config_set_size() updates the memkind pmem_size configuration
200 parameter, which allows to limit the file-backed kind memory partition.
201 Note: This function does not validate that pmem_size is in valid range.
202 memkind_config_set_memory_usage_policy() updates the memkind policy
204 configuration parameter, which allows to tune up memory utilization.
205 The user should set the value based on the characteristics of applica‐
206 tion that is using the library (e.g. prioritize memory usage, CPU uti‐
207 lization), for more details about policy see the MEMORY USAGE POLICY
208 section below. Note: This function does not validate that policy is in
209 valid range.
210 KIND MANAGEMENT:
212 There are built-in kinds that are always available and these are enu‐
213 merated in the KINDS section. The user can also create their own kinds
214 of memory. This section describes the API's that enable the tracking of
215 the different kinds of memory and determining their properties.
216 memkind_create_pmem() is a convenient function used to create a file-
218 backed kind of memory. It allocates a temporary file in the given di‐
219 rectory dir. The file is created in a fashion similar to tmpfile(3),
220 so that the file name does not appear when the directory is listed and
221 the space is automatically freed when the program terminates. The file
222 is truncated to a size of max_size bytes and the resulting space is
223 memory-mapped.
224 Note that the actual file system space is not allocated immediately,
225 but only on a call to memkind_pmem_mmap() (see memkind_pmem(3)). This
226 allows to create a pmem memkind of a pretty large size without the need
227 to reserve in advance the corresponding file system space for the en‐
228 tire heap. If the value of max_size equals 0, pmem memkind is only lim‐
229 ited by the capacity of the file system mounted under dir argument.
230 The minimum max_size value which allows to limit the size of kind by
231 the library is defined as MEMKIND_PMEM_MIN_SIZE. Calling memkind_cre‐
232 ate_pmem() with a size smaller than that and different than 0 will re‐
233 turn an error. The maximum allowed size is not limited by memkind, but
234 by the file system specified by the dir argument. The max_size passed
235 in is the raw size of the memory pool and jemalloc will use some of
236 that space for its own metadata. Returns zero if the pmem memkind is
237 created successfully or an error code from the ERRORS section if not.
238 memkind_create_pmem_with_config() is a second function used to create a
240 file-backed kind of memory. Function behaves simillar to memkind_cre‐
241 ate_pmem() but instead of passing dir and max_size arguments, it uses
242 config param to specify characteristics of created file-backed kind of
243 memory (see KIND CONFIGURATION MANAGEMENT section).
244 memkind_create_kind() creates kind that allocates memory with specific
246 memory type, memory binding policy and flags (see MEMORY FLAGS sec‐
247 tion). The memtype_flags (see MEMORY TYPES section) determine memory
248 types to allocate, policy argument is policy for specifying page bind‐
249 ing to memory types selected by memtype_flags. Returns zero if the
250 specified kind is created successfully or an error code from the ERRORS
251 section if not.
252 memkind_destroy_kind() destroys previously created kind object, which
254 must have been returned by a previous call to memkind_create_pmem(),
255 memkind_create_pmem_with_config() or memkind_create_kind(). Otherwise,
256 or if memkind_destroy_kind(kind) was already called before, undefined
257 behavior occurs. Note that, when the kind was returned by memkind_cre‐
258 ate_kind() all allocated memory must be freed before kind is destroyed,
259 otherwise this will cause memory leak. When the kind was returned by
260 memkind_create_pmem() or memkind_create_pmem_with_config() all allo‐
261 cated memory will be freed after kind will be destroyed.
262 memkind_check_available() returns zero if the specified kind is avail‐
264 able or an error code from the ERRORS section if it is not.
265 MEMKIND_PMEM_MIN_SIZE The minimum size which allows to limit the file-
267 backed memory partition.
268 STATISTICS:
270 The functions described in this section define a way to get specific
271 memory allocation statistics.
272 memkind_update_cached_stats() is used to force an update of cached dy‐
274 namic allocator statistics. Statistics are not updated real-time by
275 memkind library and this method allows to force its update.
276 memkind_get_stat() retrieves statistic of the specified type and re‐
278 turns it in value. For more details about stat see the MEMORY STATIS‐
279 TICS TYPE section below. Measured statistic applies to specific kind,
280 when NULL is given as kind then statistic applies to memory used by the
281 whole memkind library. Note: You need to call memkind_up‐
282 date_cached_stats() before calling memkind_get_stat() because statis‐
283 tics are cached by memkind library.
284 DECORATORS:
286 The memkind library enables the user to define decorator functions that
287 can be called before and after each memkind heap management API. The
288 decorators that are called at the beginning of the function end are
289 named after that function with _pre appended to the name and those that
290 are called at the end of the function are named after that function
291 with _post appended to the name. These are weak symbols and if they are
292 not present at link time they are not called. The memkind library does
293 not define these symbols which are reserved for user definition. These
294 decorators can be used to track calls to the heap management interface
295 or to modify parameters. The decorators that are called at the begin‐
296 ning of the allocator pass all inputs by reference and the decorators
297 that are called at the end of the allocator pass the output by refer‐
298 ence. This enables the modification of the input and output of each
299 heap management function by the decorators.
300 LIBRARY VERSION:
302 The memkind library version scheme consist major, minor and patch num‐
303 bers separated by dot. Combining those numbers, we got the following
304 representation:
305 major.minor.patch, where:
306 -major number is incremented whenever API is changed (loss of
307 backward compatibility),
308 -minor number is incremented whenever additional extensions are
309 introduced or behavior has been changed,
310 -patch number is incremented whenever small bug fixes are added.
311 memkind library provide numeric representation of the version by expos‐
313 ing the following API:
314 memkind_get_version() returns version number represented by a single
316 integer number, obtained from the formula:
317 major * 1000000 + minor * 1000 + patch
318 Note: major < 1 means unstable API.
320 API standards:
322 -STANDARD API, API is considered as stable
323 -NON-STANDARD API, API is considered as stable, however this is not a
324 standard way to use memkind
325 -EXPERIMENTAL API, API is considered as unstable and the subject to
326 change
327
330 memkind_calloc(), memkind_malloc(), memkind_realloc() and memkind_de‐
331 frag_reallocate() returns the pointer to the allocated memory or NULL
332 if the request fails. memkind_malloc_usable_size() returns the number
333 of usable bytes in the block of allocated memory pointed to by ptr, a
334 pointer to a block of memory allocated by memkind_malloc() or a related
335 function. If ptr is NULL, 0 is returned. memkind_free() and
336 memkind_error_message() do not have return values. All other memkind
337 API's return 0 upon success and an error code defined in the ERRORS
338 section upon failure. The memkind library avoids setting errno di‐
339 rectly, but calls to underlying libraries and system calls may set er‐
340 rno (e.g. memkind_create_pmem()).
341
343 The available kinds of memory:
344 MEMKIND_DEFAULT
346 Default allocation using standard memory and default page size.
347 MEMKIND_HUGETLB
349 Allocate from standard memory using huge pages. Note: This kind
350 requires huge pages configuration described in SYSTEM CONFIGURA‐
351 TION section.
352 MEMKIND_GBTLB (DEPRECATED)
354 Allocate from standard memory using 1GB chunks backed by huge
355 pages. Note: This kind requires huge pages configuration de‐
356 scribed in SYSTEM CONFIGURATION section.
357 MEMKIND_INTERLEAVE
359 Allocate pages interleaved across all NUMA nodes with transpar‐
360 ent huge pages disabled.
361 MEMKIND_HBW
363 Allocate from the closest high bandwidth memory NUMA node at the
364 time of allocation. If there is not enough high bandwidth memory
365 to satisfy the request errno is set to ENOMEM and the allocated
366 pointer is set to NULL.
367 MEMKIND_HBW_ALL
369 Same as MEMKIND_HBW except decision regarding closest NUMA node
370 is postponed until the time of first write.
371 MEMKIND_HBW_HUGETLB
373 Same as MEMKIND_HBW except the allocation is backed by huge
374 pages. Note: This kind requires huge pages configuration de‐
375 scribed in SYSTEM CONFIGURATION section.
376 MEMKIND_HBW_ALL_HUGETLB
378 Combination of MEMKIND_HBW_ALL and MEMKIND_HBW_HUGETLB proper‐
379 ties. Note: This kind requires huge pages configuration de‐
380 scribed in SYSTEM CONFIGURATION section.
381 MEMKIND_HBW_PREFERRED
383 Same as MEMKIND_HBW except that if there is not enough high
384 bandwidth memory to satisfy the request, the allocation will
385 fall back on standard memory.
386 MEMKIND_HBW_PREFERRED_HUGETLB
388 Same as MEMKIND_HBW_PREFERRED except the allocation is backed by
389 huge pages. Note: This kind requires huge pages configuration
390 described in SYSTEM CONFIGURATION section.
391 MEMKIND_HBW_GBTLB (DEPRECATED)
393 Same as MEMKIND_HBW except the allocation is backed by 1GB
394 chunks of huge pages. Note that size can take on any value, but
395 full gigabyte pages will allocated for each request, so remain‐
396 der of the last page will be wasted. This kind requires huge
397 pages configuration described in SYSTEM CONFIGURATION section.
398 MEMKIND_HBW_PREFERRED_GBTLB (DEPRECATED)
400 Same as MEMKIND_HBW_GBTLB except that if there is not enough
401 high bandwidth memory to satisfy the request, the allocation
402 will fall back on standard memory. Note: This kind requires
403 huge pages configuration described in SYSTEM CONFIGURATION sec‐
404 tion.
405 MEMKIND_HBW_INTERLEAVE
407 Same as MEMKIND_HBW except that the pages that support the allo‐
408 cation are interleaved across all high bandwidth nodes and
409 transparent huge pages are disabled.
410 MEMKIND_DAX_KMEM
412 Allocate from the closest persistent memory NUMA node at the
413 time of allocation. If there is not enough memory in the closest
414 persistent memory NUMA node to satisfy the request errno is set
415 to ENOMEM and the allocated pointer is set to NULL.
416 MEMKIND_DAX_KMEM_ALL
418 Allocate from the closest persistent memory NUMA node available
419 at the time of allocation. If there is not enough memory on any
420 of persistent memory NUMA nodes to satisfy the request errno is
421 set to ENOMEM and the allocated pointer is set to NULL.
422 MEMKIND_DAX_KMEM_PREFERRED
424 Same as MEMKIND_DAX_KMEM except that if there is not enough mem‐
425 ory in the closest persistent memory NUMA node to satisfy the
426 request, the allocation will fall back on other memory NUMA
427 nodes. Note: For this kind, the allocation will not succeed if
428 two or more persistent memory NUMA nodes are in the same short‐
429 est distance to the same CPU on which process is eligible to
430 run. Check on that eligibility is done upon starting the appli‐
431 cation.
432 MEMKIND_REGULAR
434 Allocate from regular memory using the default page size. Regu‐
435 lar means general purpose memory from the NUMA nodes containing
436 CPUs.
437
439 The available types of memory:
440 MEMKIND_MEMTYPE_DEFAULT
442 Standard memory, the same as process uses.
443 MEMKIND_MEMTYPE_HIGH_BANDWIDTH
445 High bandwidth memory (HBM). There must be at least two memory
446 types with different bandwidth to determine which is the HBM.
447
449 The available types of memory binding policy:
450 MEMKIND_POLICY_BIND_LOCAL
452 Allocate local memory. If there is not enough memory to satisfy
453 the request errno is set to ENOMEM and the allocated pointer is
454 set to NULL.
455 MEMKIND_POLICY_BIND_ALL
457 Memory locality is ignored. If there is not enough memory to
458 satisfy the request errno is set to ENOMEM and the allocated
459 pointer is set to NULL.
460 MEMKIND_POLICY_PREFERRED_LOCAL
462 Allocate preferred memory that is local. If there is not enough
463 preferred memory to satisfy the request or preferred memory is
464 not available, the allocation will fall back on any other mem‐
465 ory.
466 MEMKIND_POLICY_INTERLEAVE_LOCAL
468 Interleave allocation across local memory. For n memory types
469 the allocation will be interleaved across all of them.
470 MEMKIND_POLICY_INTERLEAVE_ALL
472 Interleave allocation. Locality is ignored. For n memory types
473 the allocation will be interleaved across all of them.
474 MEMKIND_POLICY_MAX_VALUE
476 Max policy value.
477
479 The available types of memory flags:
480 MEMKIND_MASK_PAGE_SIZE_2MB
482 Allocation backed by 2MB page size.
483
485 The available types of memory usage policy:
486 MEMKIND_MEM_USAGE_POLICY_DEFAULT
488 Default memory usage policy.
489 MEMKIND_MEM_USAGE_POLICY_CONSERVATIVE
491 Conservative memory usage policy - prioritize memory usage at
492 cost of performance. Note: Memory usage policies have no effect
493 for TBB heap manager described in ENVIRONMENT section.
494
496 The available types of memory statistics:
497 MEMKIND_STAT_TYPE_RESIDENT
499 Maximum number of bytes in physically resident data pages
500 mapped.
501 MEMKIND_STAT_TYPE_ACTIVE
503 Total number of bytes in active pages.
504 MEMKIND_STAT_TYPE_ALLOCATED
506 Total number of allocated bytes.
507
509 memkind_posix_memalign()
510 returns the one of the POSIX standard error codes EINVAL or
511 ENOMEM as defined in <errno.h> if an error occurs (these have
512 positive values). If the alignment parameter is not a power of
513 two or is not a multiple of sizeof(void*), then EINVAL is re‐
514 turned. If there is insufficient memory to satisfy the request
515 then ENOMEM is returned.
516 All functions other than memkind_posix_memalign() which have an integer
518 return type return one of the negative error codes as defined in
519 <memkind.h> and described below.
520 MEMKIND_ERROR_UNAVAILABLE
522 Requested memory kind is not available
523 MEMKIND_ERROR_MBIND
525 Call to mbind(2) failed
526 MEMKIND_ERROR_MMAP
528 Call to mmap(2) failed
529 MEMKIND_ERROR_MALLOC
531 Call to jemalloc's malloc() failed
532 MEMKIND_ERROR_ENVIRON
534 Error parsing environment variable MEMKIND_*
535 MEMKIND_ERROR_INVALID
537 Invalid input arguments to memkind routine
538 MEMKIND_ERROR_TOOMANY
540 Error trying to initialize more than maximum MEMKIND_MAX_KIND
541 number of kinds
542 MEMKIND_ERROR_BADOPS
544 Error memkind operation structure is missing or invalid
545 MEMKIND_ERROR_HUGETLB
547 Unable to allocate huge pages
548 MEMKIND_ERROR_MEMTYPE_NOT_AVAILABLE
550 Error requested memory type is not available
551 MEMKIND_ERROR_OPERATION_FAILED
553 Error memkind operation failed
554 MEMKIND_ERROR_ARENAS_CREATE
556 Call to jemalloc's arenas.create() failed
557 MEMKIND_ERROR_RUNTIME
559 Unspecified run-time error
560
562 /usr/bin/memkind-hbw-nodes
563 Prints a comma-separated list of high bandwidth nodes.
564 /usr/bin/memkind-auto-dax-kmem-nodes
566 Prints a comma-separated list of persistent memory NUMA nodes,
567 which are automatically detected.
568
570 MEMKIND_HBW_NODES
571 This environment variable is a comma-separated list of NUMA
572 nodes that are treated as high bandwidth. Uses the libnuma rou‐
573 tine numa_parse_nodestring() for parsing, so the syntax de‐
574 scribed in the numa(3) man page for this routine applies: e.g.
575 1-3,5 is a valid setting.
576 MEMKIND_DAX_KMEM_NODES
578 This environment variable is a comma-separated list of NUMA
579 nodes that are treated as PMEM memory. Uses the libnuma routine
580 numa_parse_nodestring() for parsing, so the syntax described in
581 the numa(3) man page for this routine applies: e.g. 1-3,5 is a
582 valid setting.
583 MEMKIND_ARENA_NUM_PER_KIND
585 This environment variable allows leveraging internal mechanism
586 of the library for setting number of arenas per kind. Value
587 should be a positive integer (not greater than INT_MAX defined
588 in <limits.h>). The user should set the value based on the
589 characteristics of application that is using the library. Higher
590 value can provide better performance in extremely multithreaded
591 applications at the cost of memory overhead. See section IMPLE‐
592 MENTATION NOTES of jemalloc(3) for more details about arenas.
593 MEMKIND_HOG_MEMORY
595 Controls behavior of memkind with regards to returning memory to
596 underlying OS. Setting MEMKIND_HOG_MEMORY to 1 causes memkind to
597 not release memory to OS in anticipation of memory reuse soon.
598 This will improve latency of 'free' operations but increase mem‐
599 ory usage. Note: For file-backed kind memory will be released
600 to OS only after calling memkind_destroy_kind(), not after
601 'free' operations. In context of MEMKIND_MEM_USAGE_POLICY_CON‐
602 SERVATIVE memory usage policy - it will also impact memory coa‐
603 lescing and results that blocks pages will be often reused (bet‐
604 ter memory usage at cost of performance).
605 MEMKIND_DEBUG
607 Controls logging mechanism in memkind. Setting MEMKIND_DEBUG to
608 1 enables printing messages like errors and general information
609 about environment to stderr.
610 MEMKIND_BACKGROUND_THREAD_LIMIT
612 Enable background worker threads. Value should be from range 0
613 to maximum number of cpus. Setting MEMKIND_BACK‐
614 GROUND_THREAD_LIMIT to specific value will limit maximum number
615 of background worker threads to this value. 0 means maximum
616 number of background worker threads will be limited to maximum
617 number of cpus.
618 MEMKIND_HEAP_MANAGER
620 Controls heap management behavior in memkind library by switch‐
621 ing to one of the available heap managers.
622 Values:
623 JEMALLOC - sets the jemalloc heap manager
624 TBB - sets the Intel Threading Building Blocks heap manager.
625 This option requires installed
626 Intel Threading Building Blocks library.
627 If the MEMKIND_HEAP_MANAGER is not set then the jemalloc heap manager
629 will be used by default.
630
632 Interfaces for obtaining 2MB (HUGETLB) memory need allocated huge pages
633 in the kernel's huge page pool.
634 HUGETLB (huge pages)
636 Current number of "persistent" huge pages can be read from
637 /proc/sys/vm/nr_hugepages file. Proposed way of setting
638 hugepages is: sudo sysctl vm.nr_hugepages=<number_of_hugepages>.
639 More information can be found here:
640 ⟨https://www.kernel.org/doc/Documentation/vm/hugetlbpage.txt⟩
641
643 When linking statically against memkind, libmemkind.a should be used
644 together with its dependencies libnuma and pthread. Pthread can be
645 linked by adding /usr/lib64/libpthread.a as a dependency (exact path
646 may vary). Typically libnuma will need to be compiled from sources to
647 use it as a static dependency. libnuma can be reached on GitHub:
648 ⟨https://github.com/numactl/numactl⟩
649
651 HUGETLB (huge pages)
652 There might be some overhead in huge pages consumption caused by
653 heap management. If your allocation fails because of OOM,
654 please try to allocate extra huge pages (e.g. 8 huge pages).
655
657 Copyright (C) 2014 - 2020 Intel Corporation. All rights reserved.
658
660 malloc(3), malloc_usable_size(3), numa(3), numactl(8), mbind(2),
661 mmap(2), move_pages(2), jemalloc(3), memkind_dax_kmem(3), memkind_de‐
662 fault(3), memkind_arena(3), memkind_hbw(3), memkind_hugetlb(3),
663 memkind_pmem(3)
664Intel Corporation 2015-03-31 MEMKIND(3)