1MEMKIND_ARENA(3) MEMKIND_ARENA MEMKIND_ARENA(3)
2
6 memkind_arena - jemalloc arena allocation memkind operations.
7 Note: This is EXPERIMENTAL API. The functionality and the header file
8 itself can be changed (including non-backward compatible changes) or
9 removed.
10
12 int memkind_arena_create(struct memkind *kind, struct memkind_ops *ops,
13 const char *name);
14 int memkind_arena_create_map(struct memkind *kind, extent_hooks_t
15 *hooks);
16 int memkind_arena_destroy(struct memkind *kind);
17 void *memkind_arena_malloc(struct memkind *kind, size_t size);
18 void *memkind_arena_calloc(struct memkind *kind, size_t num, size_t
19 size);
20 int memkind_arena_posix_memalign(struct memkind *kind, void **memptr,
21 size_t alignment, size_t size);
22 void *memkind_arena_realloc(struct memkind *kind, void *ptr, size_t
23 size);
24 void *memkind_arena_realloc_with_kind_detect(void *ptr, size_t size);
25 int memkind_thread_get_arena(struct memkind *kind, unsigned int *arena,
26 size_t size);
27 int memkind_bijective_get_arena(struct memkind *kind, unsigned int
28 *arena, size_t size);
29 struct memkind *get_kind_by_arena(unsigned arena_ind);
30 struct memkind *memkind_arena_detect_kind(void *ptr);
31 int memkind_arena_finalize(struct memkind *kind);
32 void memkind_arena_init(struct memkind *kind);
33 void memkind_arena_free(struct memkind *kind, void *ptr);
34 void memkind_arena_free_with_kind_detect(void *ptr);
35 size_t memkind_arena_malloc_usable_size(void *ptr);
36 int memkind_arena_update_memory_usage_policy(struct memkind *kind,
37 memkind_mem_usage_policy policy);
38 int memkind_arena_set_max_bg_threads(size_t threads_limit);
39 int memkind_arena_set_bg_threads(bool state);
40 int memkind_arena_stats_print(void (*write_cb) (void *, const char *),
41 void *cbopaque, memkind_stat_print_opt opts);
42
44 This header file is a collection of functions can be used to populate
45 the memkind operations structure for memory kinds that use jemalloc.
46 memkind_arena_create() is an implementation of the memkind "create" op‐
48 eration for memory kinds that use jemalloc. This calls memkind_de‐
49 fault_create() (see memkind_default(3)) followed by memkind_arena_cre‐
50 ate_map() described below.
51 memkind_arena_create_map() creates the arena_map array for the memkind
53 structure pointed to by kind which can be indexed by the
54 ops.get_arena() function from the kind's operations. If get_arena
55 points memkind_thread_get_arena() then there will be four arenas cre‐
56 ated for each processor, and if get_arena points to memkind_bijec‐
57 tive_get_arena() then just one arena is created.
58 memkind_arena_destroy() is an implementation of the memkind "destroy"
60 operation for memory kinds that use jemalloc. This releases all of the
61 resources allocated by memkind_arena_create().
62 memkind_arena_malloc() is an implementation of the memkind "malloc" op‐
64 eration for memory kinds that use jemalloc. This allocates memory us‐
65 ing the arenas created by memkind_arena_create() through the jemalloc's
66 mallocx() interface. It uses the memkind "get_arena" operation to se‐
67 lect the arena.
68 memkind_arena_calloc() is an implementation of the memkind "calloc" op‐
70 eration for memory kinds that use jemalloc. This allocates memory us‐
71 ing the arenas created by memkind_arena_create() through the jemalloc's
72 mallocx() interface. It uses the memkind "get_arena" operation to se‐
73 lect the arena.
74 memkind_arena_posix_memalign() is an implementation of the memkind
76 "posix_memalign" operation for memory kinds that use jemalloc. This
77 allocates memory using the arenas created by memkind_arena_create()
78 through the jemalloc's mallocx() interface. It uses the memkind
79 "get_arena" operation to select the arena. The POSIX standard requires
80 that posix_memalign(3) may not set errno however the jemalloc's mal‐
81 locx() routine may. In an attempt to abide by the standard errno is
82 recorded before calling jemalloc's mallocx() and then reset after the
83 call.
84 memkind_arena_realloc() is an implementation of the memkind "realloc"
86 operation for memory kinds that use jemalloc. This allocates memory
87 using the arenas created by memkind_arena_create() through the jemal‐
88 loc's mallocx() interface. It uses the memkind "get_arena" operation
89 to select the arena.
90 memkind_arena_realloc_with_kind_detect() function will look up for kind
92 associated to the allocated memory referenced by ptr and call (depend‐
93 ing on kind value) memkind_arena_realloc() or memkind_default_real‐
94 loc().
95 memkind_thread_get_arena() retrieves the arena index that is bound to
97 to the calling thread based on a hash of its thread ID. The arena in‐
98 dex can be used with the MALLOCX_ARENA macro to set flags for jemal‐
99 loc's mallocx().
100 memkind_bijective_arena_get_arena() retrieves the arena index to be
102 used with the MALLOCX_ARENA macro to set flags for jemalloc's mal‐
103 locx(). Use of this operation implies that only one arena is used for
104 the kind.
105 memkind_arena_free() is an implementation of the memkind "free" opera‐
107 tion for memory kinds that use jemalloc. It causes the allocated mem‐
108 ory referenced by ptr, which must have been returned by a previous call
109 to memkind_arena_malloc(), memkind_arena_calloc() or memkind_arena_re‐
110 alloc() to be made available for future allocations. It uses the
111 memkind "get_arena" operation to select the arena.
112 memkind_arena_free_with_kind_detect() function will look up for kind
114 associated to the allocated memory referenced by ptr and call
115 memkind_arena_free().
116 memkind_arena_detect_kind() returns pointer to memory kind structure
118 associated with given allocated memory referenced by ptr.
119 get_kind_by_arena() returns pointer to memory kind structure associated
121 with given arena.
122 memkind_arena_malloc_usable_size() is an implementation of the memkind
124 "usable_size" operation for memory kinds that use jemalloc.
125 memkind_arena_finalize() is an implementation of the memkind "finalize"
127 operation for memory kinds that use jemalloc. This function releases
128 all resources allocated by memkind_arena_create() and it's called when
129 main() finishes or after calling exit() function.
130 memkind_arena_init() creates arena map with proper hooks per specified
132 kind.
133 memkind_arena_update_memory_usage_policy() function changes time, which
135 determine how fast jemalloc returns unused pages back to the operating
136 system, in other words how fast it deallocates file space.
137 memkind_arena_set_max_bg_threads() sets the maximum number of internal
139 background worker threads in jemalloc. The threads_limit specify limit
140 of background threads which can be enabled ( 0 means no limit).
141 memkind_arena_set_bg_threads() enables/disables internal background
143 worker threads in jemalloc.
144 memkind_arena_stats_print() prints summary statistics. This function
146 wraps jemalloc's function je_malloc_stats_print(). Uses write_cb func‐
147 tion to print the output. While providing custom writer function, use
148 syscall(2) rather than write(2) Pass NULL in order to use the default
149 write_cb function which prints the output to the stderr. Use cbopaque
150 parameter in order to pass some data to your write_cb function. Pass
151 additional options using opts. For more details on opts see the MEMORY
152 STATISTICS PRINT OPTIONS section below. Returns MEMKIND_ERROR_INVALID
153 when failed to parse options string, MEMKIND_SUCCESS on success.
154
156 The available options for printing statistics:
157 MEMKIND_STAT_PRINT_ALL
159 Print all statistics.
160 MEMKIND_STAT_PRINT_JSON_FORMAT
162 Print statistics in JSON format.
163 MEMKIND_STAT_PRINT_OMIT_GENERAL
165 Omit general information that never changes during execution.
166 MEMKIND_STAT_PRINT_OMIT_MERGED_ARENA
168 Omit merged arena statistics.
169 MEMKIND_STAT_PRINT_OMIT_DESTROYED_MERGED_ARENA
171 Omit destroyed merged arena statistics.
172 MEMKIND_STAT_PRINT_OMIT_PER_ARENA
174 Omit per arena statistics.
175 MEMKIND_STAT_PRINT_OMIT_PER_SIZE_CLASS_BINS
177 Omit per size class statistics for bins.
178 MEMKIND_STAT_PRINT_OMIT_PER_SIZE_CLASS_LARGE
180 Omit per size class statistics for large objects.
181 MEMKIND_STAT_PRINT_OMIT_MUTEX
183 Omit all mutex statistics.
184 MEMKIND_STAT_PRINT_OMIT_EXTENT
186 Omit extent statistics.
187
189 Copyright (C) 2014 - 2021 Intel Corporation. All rights reserved.
190
192 memkind(3), memkind_default(3), memkind_hbw(3), memkind_hugetlb(3),
193 memkind_pmem(3), jemalloc(3), mbind(2), mmap(2), syscall(2), write(2)
194Intel Corporation 2015-04-21 MEMKIND_ARENA(3)