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
9 described 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
103 exception 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
120 returned 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
146 Update 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
219 directory 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
228 entire heap. If the value of max_size equals 0, pmem memkind is only
229 limited 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
233 return an error. The maximum allowed size is not limited by memkind,
234 but by the file system specified by the dir argument. The max_size
235 passed in is the raw size of the memory pool and jemalloc will use some
236 of that space for its own metadata. Returns zero if the pmem memkind
237 is created successfully or an error code from the ERRORS section if
238 not.
239 memkind_create_pmem_with_config() is a second function used to create a
241 file-backed kind of memory. Function behaves simillar to memkind_cre‐
242 ate_pmem() but instead of passing dir and max_size arguments, it uses
243 config param to specify characteristics of created file-backed kind of
244 memory (see KIND CONFIGURATION MANAGEMENT section).
245 memkind_create_kind() creates kind that allocates memory with specific
247 memory type, memory binding policy and flags (see MEMORY FLAGS sec‐
248 tion). The memtype_flags (see MEMORY TYPES section) determine memory
249 types to allocate, policy argument is policy for specifying page bind‐
250 ing to memory types selected by memtype_flags. Returns zero if the
251 specified kind is created successfully or an error code from the ERRORS
252 section if not.
253 memkind_destroy_kind() destroys previously created kind object, which
255 must have been returned by a previous call to memkind_create_pmem(),
256 memkind_create_pmem_with_config() or memkind_create_kind(). Otherwise,
257 or if memkind_destroy_kind(kind) was already called before, undefined
258 behavior occurs. Note that, when the kind was returned by memkind_cre‐
259 ate_kind() all allocated memory must be freed before kind is destroyed,
260 otherwise this will cause memory leak. When the kind was returned by
261 memkind_create_pmem() or memkind_create_pmem_with_config() all allo‐
262 cated memory will be freed after kind will be destroyed.
263 memkind_check_available() returns zero if the specified kind is avail‐
265 able or an error code from the ERRORS section if it is not.
266 MEMKIND_PMEM_MIN_SIZE The minimum size which allows to limit the file-
268 backed memory partition.
269 STATISTICS:
271 The functions described in this section define a way to get specific
272 memory allocation statistics.
273 memkind_update_cached_stats() is used to force an update of cached
275 dynamic allocator statistics. Statistics are not updated real-time by
276 memkind library and this method allows to force its update.
277 memkind_get_stat() retrieves statistic of the specified type and
279 returns it in value. For more details about stat see the MEMORY STA‐
280 TISTICS TYPE section below. Measured statistic applies to specific
281 kind, when NULL is given as kind then statistic applies to memory used
282 by the whole memkind library. Note: You need to call
283 memkind_update_cached_stats() before calling memkind_get_stat() because
284 statistics are cached by memkind library.
285 DECORATORS:
287 The memkind library enables the user to define decorator functions that
288 can be called before and after each memkind heap management API. The
289 decorators that are called at the beginning of the function end are
290 named after that function with _pre appended to the name and those that
291 are called at the end of the function are named after that function
292 with _post appended to the name. These are weak symbols and if they are
293 not present at link time they are not called. The memkind library does
294 not define these symbols which are reserved for user definition. These
295 decorators can be used to track calls to the heap management interface
296 or to modify parameters. The decorators that are called at the begin‐
297 ning of the allocator pass all inputs by reference and the decorators
298 that are called at the end of the allocator pass the output by refer‐
299 ence. This enables the modification of the input and output of each
300 heap management function by the decorators.
301 LIBRARY VERSION:
303 The memkind library version scheme consist major, minor and patch num‐
304 bers separated by dot. Combining those numbers, we got the following
305 representation:
306 major.minor.patch, where:
307 -major number is incremented whenever API is changed (loss of
308 backward compatibility),
309 -minor number is incremented whenever additional extensions are
310 introduced or behavior has been changed,
311 -patch number is incremented whenever small bug fixes are added.
312 memkind library provide numeric representation of the version by expos‐
314 ing the following API:
315 memkind_get_version() returns version number represented by a single
317 integer number, obtained from the formula:
318 major * 1000000 + minor * 1000 + patch
319 Note: major < 1 means unstable API.
321 API standards:
323 -STANDARD API, API is considered as stable
324 -NON-STANDARD API, API is considered as stable, however this is not a
325 standard way to use memkind
326 -EXPERIMENTAL API, API is considered as unstable and the subject to
327 change
328
331 memkind_calloc(), memkind_malloc(), memkind_realloc() and
332 memkind_defrag_reallocate() returns the pointer to the allocated memory
333 or NULL if the request fails. memkind_malloc_usable_size() returns the
334 number of usable bytes in the block of allocated memory pointed to by
335 ptr, a pointer to a block of memory allocated by memkind_malloc() or a
336 related function. If ptr is NULL, 0 is returned. memkind_free() and
337 memkind_error_message() do not have return values. All other memkind
338 API's return 0 upon success and an error code defined in the ERRORS
339 section upon failure. The memkind library avoids setting errno
340 directly, but calls to underlying libraries and system calls may set
341 errno (e.g. memkind_create_pmem()).
342
344 The available kinds of memory:
345 MEMKIND_DEFAULT
347 Default allocation using standard memory and default page size.
348 MEMKIND_HUGETLB
350 Allocate from standard memory using huge pages. Note: This kind
351 requires huge pages configuration described in SYSTEM CONFIGURA‐
352 TION section.
353 MEMKIND_GBTLB (DEPRECATED)
355 Allocate from standard memory using 1GB chunks backed by huge
356 pages. Note: This kind requires huge pages configuration
357 described in SYSTEM CONFIGURATION section.
358 MEMKIND_INTERLEAVE
360 Allocate pages interleaved across all NUMA nodes with transpar‐
361 ent huge pages disabled.
362 MEMKIND_HBW
364 Allocate from the closest high bandwidth memory NUMA node at the
365 time of allocation. If there is not enough high bandwidth memory
366 to satisfy the request errno is set to ENOMEM and the allocated
367 pointer is set to NULL.
368 MEMKIND_HBW_ALL
370 Same as MEMKIND_HBW except decision regarding closest NUMA node
371 is postponed until the time of first write.
372 MEMKIND_HBW_HUGETLB
374 Same as MEMKIND_HBW except the allocation is backed by huge
375 pages. Note: This kind requires huge pages configuration
376 described in SYSTEM CONFIGURATION section.
377 MEMKIND_HBW_ALL_HUGETLB
379 Combination of MEMKIND_HBW_ALL and MEMKIND_HBW_HUGETLB proper‐
380 ties. Note: This kind requires huge pages configuration
381 described in SYSTEM CONFIGURATION section.
382 MEMKIND_HBW_PREFERRED
384 Same as MEMKIND_HBW except that if there is not enough high
385 bandwidth memory to satisfy the request, the allocation will
386 fall back on standard memory.
387 MEMKIND_HBW_PREFERRED_HUGETLB
389 Same as MEMKIND_HBW_PREFERRED except the allocation is backed by
390 huge pages. Note: This kind requires huge pages configuration
391 described in SYSTEM CONFIGURATION section.
392 MEMKIND_HBW_GBTLB (DEPRECATED)
394 Same as MEMKIND_HBW except the allocation is backed by 1GB
395 chunks of huge pages. Note that size can take on any value, but
396 full gigabyte pages will allocated for each request, so remain‐
397 der of the last page will be wasted. This kind requires huge
398 pages configuration described in SYSTEM CONFIGURATION section.
399 MEMKIND_HBW_PREFERRED_GBTLB (DEPRECATED)
401 Same as MEMKIND_HBW_GBTLB except that if there is not enough
402 high bandwidth memory to satisfy the request, the allocation
403 will fall back on standard memory. Note: This kind requires
404 huge pages configuration described in SYSTEM CONFIGURATION sec‐
405 tion.
406 MEMKIND_HBW_INTERLEAVE
408 Same as MEMKIND_HBW except that the pages that support the allo‐
409 cation are interleaved across all high bandwidth nodes and
410 transparent huge pages are disabled.
411 MEMKIND_DAX_KMEM
413 Allocate from the closest persistent memory NUMA node at the
414 time of allocation. If there is not enough memory in the closest
415 persistent memory NUMA node to satisfy the request errno is set
416 to ENOMEM and the allocated pointer is set to NULL.
417 MEMKIND_DAX_KMEM_ALL
419 Allocate from the closest persistent memory NUMA node available
420 at the time of allocation. If there is not enough memory on any
421 of persistent memory NUMA nodes to satisfy the request errno is
422 set to ENOMEM and the allocated pointer is set to NULL.
423 MEMKIND_DAX_KMEM_PREFERRED
425 Same as MEMKIND_DAX_KMEM except that if there is not enough mem‐
426 ory in the closest persistent memory NUMA node to satisfy the
427 request, the allocation will fall back on other memory NUMA
428 nodes. Note: For this kind, the allocation will not succeed if
429 two or more persistent memory NUMA nodes are in the same short‐
430 est distance to the same CPU on which process is eligible to
431 run. Check on that eligibility is done upon starting the appli‐
432 cation.
433 MEMKIND_REGULAR
435 Allocate from regular memory using the default page size. Regu‐
436 lar means general purpose memory from the NUMA nodes containing
437 CPUs.
438
440 The available types of memory:
441 MEMKIND_MEMTYPE_DEFAULT
443 Standard memory, the same as process uses.
444 MEMKIND_MEMTYPE_HIGH_BANDWIDTH
446 High bandwidth memory (HBM). There must be at least two memory
447 types with different bandwidth to determine which is the HBM.
448
450 The available types of memory binding policy:
451 MEMKIND_POLICY_BIND_LOCAL
453 Allocate local memory. If there is not enough memory to satisfy
454 the request errno is set to ENOMEM and the allocated pointer is
455 set to NULL.
456 MEMKIND_POLICY_BIND_ALL
458 Memory locality is ignored. If there is not enough memory to
459 satisfy the request errno is set to ENOMEM and the allocated
460 pointer is set to NULL.
461 MEMKIND_POLICY_PREFERRED_LOCAL
463 Allocate preferred memory that is local. If there is not enough
464 preferred memory to satisfy the request or preferred memory is
465 not available, the allocation will fall back on any other mem‐
466 ory.
467 MEMKIND_POLICY_INTERLEAVE_LOCAL
469 Interleave allocation across local memory. For n memory types
470 the allocation will be interleaved across all of them.
471 MEMKIND_POLICY_INTERLEAVE_ALL
473 Interleave allocation. Locality is ignored. For n memory types
474 the allocation will be interleaved across all of them.
475 MEMKIND_POLICY_MAX_VALUE
477 Max policy value.
478
480 The available types of memory flags:
481 MEMKIND_MASK_PAGE_SIZE_2MB
483 Allocation backed by 2MB page size.
484
486 The available types of memory usage policy:
487 MEMKIND_MEM_USAGE_POLICY_DEFAULT
489 Default memory usage policy.
490 MEMKIND_MEM_USAGE_POLICY_CONSERVATIVE
492 Conservative memory usage policy - prioritize memory usage at
493 cost of performance. Note: Memory usage policies have no effect
494 for TBB heap manager described in ENVIRONMENT section.
495
497 The available types of memory statistics:
498 MEMKIND_STAT_TYPE_RESIDENT
500 Maximum number of bytes in physically resident data pages
501 mapped.
502 MEMKIND_STAT_TYPE_ACTIVE
504 Total number of bytes in active pages.
505 MEMKIND_STAT_TYPE_ALLOCATED
507 Total number of allocated bytes.
508
510 memkind_posix_memalign()
511 returns the one of the POSIX standard error codes EINVAL or
512 ENOMEM as defined in <errno.h> if an error occurs (these have
513 positive values). If the alignment parameter is not a power of
514 two or is not a multiple of sizeof(void*), then EINVAL is
515 returned. If there is insufficient memory to satisfy the request
516 then ENOMEM is returned.
517 All functions other than memkind_posix_memalign() which have an integer
519 return type return one of the negative error codes as defined in
520 <memkind.h> and described below.
521 MEMKIND_ERROR_UNAVAILABLE
523 Requested memory kind is not available
524 MEMKIND_ERROR_MBIND
526 Call to mbind(2) failed
527 MEMKIND_ERROR_MMAP
529 Call to mmap(2) failed
530 MEMKIND_ERROR_MALLOC
532 Call to jemalloc's malloc() failed
533 MEMKIND_ERROR_ENVIRON
535 Error parsing environment variable MEMKIND_*
536 MEMKIND_ERROR_INVALID
538 Invalid input arguments to memkind routine
539 MEMKIND_ERROR_TOOMANY
541 Error trying to initialize more than maximum MEMKIND_MAX_KIND
542 number of kinds
543 MEMKIND_ERROR_BADOPS
545 Error memkind operation structure is missing or invalid
546 MEMKIND_ERROR_HUGETLB
548 Unable to allocate huge pages
549 MEMKIND_ERROR_MEMTYPE_NOT_AVAILABLE
551 Error requested memory type is not available
552 MEMKIND_ERROR_OPERATION_FAILED
554 Error memkind operation failed
555 MEMKIND_ERROR_ARENAS_CREATE
557 Call to jemalloc's arenas.create() failed
558 MEMKIND_ERROR_RUNTIME
560 Unspecified run-time error
561
563 /usr/bin/memkind-hbw-nodes
564 Prints a comma-separated list of high bandwidth nodes.
565 /usr/bin/memkind-auto-dax-kmem-nodes
567 Prints a comma-separated list of persistent memory NUMA nodes,
568 which are automatically detected.
569
571 MEMKIND_HBW_NODES
572 This environment variable is a comma-separated list of NUMA
573 nodes that are treated as high bandwidth. Uses the libnuma rou‐
574 tine numa_parse_nodestring() for parsing, so the syntax
575 described in the numa(3) man page for this routine applies: e.g.
576 1-3,5 is a valid setting.
577 MEMKIND_DAX_KMEM_NODES
579 This environment variable is a comma-separated list of NUMA
580 nodes that are treated as PMEM memory. Uses the libnuma routine
581 numa_parse_nodestring() for parsing, so the syntax described in
582 the numa(3) man page for this routine applies: e.g. 1-3,5 is a
583 valid setting.
584 MEMKIND_ARENA_NUM_PER_KIND
586 This environment variable allows leveraging internal mechanism
587 of the library for setting number of arenas per kind. Value
588 should be a positive integer (not greater than INT_MAX defined
589 in <limits.h>). The user should set the value based on the
590 characteristics of application that is using the library. Higher
591 value can provide better performance in extremely multithreaded
592 applications at the cost of memory overhead. See section IMPLE‐
593 MENTATION NOTES of jemalloc(3) for more details about arenas.
594 MEMKIND_HOG_MEMORY
596 Controls behavior of memkind with regards to returning memory to
597 underlying OS. Setting MEMKIND_HOG_MEMORY to 1 causes memkind to
598 not release memory to OS in anticipation of memory reuse soon.
599 This will improve latency of 'free' operations but increase mem‐
600 ory usage.
601 MEMKIND_DEBUG
603 Controls logging mechanism in memkind. Setting MEMKIND_DEBUG to
604 1 enables printing messages like errors and general information
605 about environment to stderr.
606 MEMKIND_BACKGROUND_THREAD_LIMIT
608 Enable background worker threads. Value should be from range 0
609 to maximum number of cpus. Setting MEMKIND_BACK‐
610 GROUND_THREAD_LIMIT to specific value will limit maximum number
611 of background worker threads to this value. 0 means maximum
612 number of background worker threads will be limited to maximum
613 number of cpus.
614 MEMKIND_HEAP_MANAGER
616 Controls heap management behavior in memkind library by switch‐
617 ing to one of the available heap managers.
618 Values:
619 JEMALLOC - sets the jemalloc heap manager
620 TBB - sets the Intel Threading Building Blocks heap manager.
621 This option requires installed
622 Intel Threading Building Blocks library.
623 If the MEMKIND_HEAP_MANAGER is not set then the jemalloc heap manager
625 will be used by default.
626
628 Interfaces for obtaining 2MB (HUGETLB) memory need allocated huge pages
629 in the kernel's huge page pool.
630 HUGETLB (huge pages)
632 Current number of "persistent" huge pages can be read from
633 /proc/sys/vm/nr_hugepages file. Proposed way of setting
634 hugepages is: sudo sysctl vm.nr_hugepages=<number_of_hugepages>.
635 More information can be found here:
636 ⟨https://www.kernel.org/doc/Documentation/vm/hugetlbpage.txt⟩
637
639 When linking statically against memkind, libmemkind.a should be used
640 together with its dependencies libnuma and pthread. Pthread can be
641 linked by adding /usr/lib64/libpthread.a as a dependency (exact path
642 may vary). Typically libnuma will need to be compiled from sources to
643 use it as a static dependency. libnuma can be reached on GitHub:
644 ⟨https://github.com/numactl/numactl⟩
645
647 HUGETLB (huge pages)
648 There might be some overhead in huge pages consumption caused by
649 heap management. If your allocation fails because of OOM,
650 please try to allocate extra huge pages (e.g. 8 huge pages).
651
653 Copyright (C) 2014 - 2019 Intel Corporation. All rights reserved.
654
656 malloc(3), malloc_usable_size(3), numa(3), numactl(8), mbind(2),
657 mmap(2), move_pages(2), jemalloc(3), memkind_dax_kmem(3),
658 memkind_default(3), memkind_arena(3), memkind_hbw(3),
659 memkind_hugetlb(3), memkind_pmem(3)
660Intel Corporation 2015-03-31 MEMKIND(3)