1LIBMEMTIER C API(3) LIBMEMTIER C API LIBMEMTIER C API(3)
2
6 libmemtier - memory tiering interface
7 Note: memkind_memtier.h functionality is considered as stable API
8 (STANDARD API).
9
11 #include <memkind_memtier.h>
12 Link with -lmemkind
14 The API can be used either directly with the usage of C-functions or
16 via environment variables. See also ENVIRONMENT section.
17 TIER MANAGEMENT:
19 struct memtier_builder *memtier_builder_new(memtier_policy_t policy);
21 void memtier_builder_delete(struct memtier_builder *builder);
22 int memtier_builder_add_tier(struct memtier_builder *builder, memkind_t
23 kind, unsigned kind_ratio);
24 struct memtier_memory *memtier_builder_construct_memtier_memory(struct
25 memtier_builder *builder);
26 void memtier_delete_memtier_memory(struct memtier_memory *memory);
27 HEAP MANAGEMENT:
29 void *memtier_malloc(struct memtier_memory *memory, size_t size);
30 void *memtier_kind_malloc(memkind_t kind, size_t size);
31 void *memtier_calloc(struct memtier_memory *memory, size_t num, size_t
32 size);
33 void *memtier_kind_calloc(memkind_t kind, size_t num, size_t size);
34 void *memtier_realloc(struct memtier_memory *memory, void *ptr, size_t
35 size);
36 void *memtier_kind_realloc(memkind_t kind, void *ptr, size_t size);
37 int memtier_posix_memalign(struct memtier_memory *memory, void
38 **memptr, size_t alignment, size_t size);
39 int memtier_kind_posix_memalign(memkind_t kind, void **memptr, size_t
40 alignment, size_t size);
41 size_t memtier_usable_size(void *ptr);
42 void memtier_free(void *ptr);
43 void memtier_kind_free(memkind_t kind, void *ptr);
44 size_t memtier_kind_allocated_size(memkind_t kind);
45 DECORATORS:
47 void memtier_kind_malloc_post(memkind_t kind, size_t size, void **re‐
48 sult);
49 void memtier_kind_calloc_post(memkind_t kind, size_t nmemb, size_t
50 size, void **result);
51 void memtier_kind_posix_memalign_post(memkind_t kind, void **memptr,
52 size_t alignment, size_t size, int *err);
53 void memtier_kind_realloc_post(memkind_t *kind, void *ptr, size_t size,
54 void **result);
55 void memtier_kind_free_pre(void **ptr);
56 void memtier_kind_usable_size_post(void **ptr, size_t size);
57 MEMTIER PROPERTY MANAGEMENT:
59 int memtier_ctl_set(struct memtier_builder *builder, const char *name,
60 const void *val);
61
63 This library enables explicit allocation-time memory tiering. It al‐
64 lows to make allocations with the usage of multiple kinds keeping a
65 specified ratio between them. This ratio determines how much of total
66 allocated memory should be allocated with the usage of each kind.
67 TIER MANAGEMENT:
69 The functions in this section are used to set up, create and destroy
70 the memtier_memory object. This object is passed as an argument to the
71 memtier_malloc() group of functions. It defines the way the alloca‐
72 tions are distributed between different memory tiers.
73 memtier_builder_new() returns a pointer to a new memtier_builder object
75 which is used for creating the memtier_memory object, policy determines
76 the policy of allocations distribution between tiers by the
77 memtier_memory object. See the POLICIES section in libmemtier(7) for
78 available options.
79 memtier_builder_delete() deletes the builder object releasing the mem‐
81 ory it used. Use after the memtier_memory object is created with the
82 function memtier_builder_construct_memtier_memory().
83 memtier_builder_add_tier() adds memory kind to the builder. This kind
85 defines a memory tier used in the memtier_memory object. This function
86 can be called more than once to create several different memory tiers.
87 The "weight" of the tier is determined by the kind_ratio parameter.
88 The higher it is relative to other tiers' kind_ratio, the higher the
89 share of allocated memory on that tier, e.g. given that ratio
90 DRAM:KMEM_DAX is 1:4:
91 sample allocation size: 20 GB total, 4 GB DRAM, 16 GB KMEM_DAX
93 memtier_builder_construct_memtier_memory() returns a pointer to a newly
95 allocated memtier_memory object. The builder can be safely removed af‐
96 ter this operation using the memtier_builder_delete() function.
97 memtier_delete_memtier_memory() deletes the memory tiering object re‐
99 leasing the memory it used.
100 HEAP MANAGEMENT:
102 The functions described in this section define a heap manager with an
103 interface modeled on the ISO C standard API's, except that the user
104 must specify either the kind of memory with the first argument to each
105 function or the tiered memory object which defines memory tiers used
106 for allocations. See the KINDS section in the memkind(3) manual for a
107 full description of the implemented kinds.
108 memtier_malloc() allocates size bytes of memory on one of memory tiers
110 defined by the memory. See libmemtier(7) for further details on memory
111 tiers. memkind_malloc() is used for allocations. For further details
112 on it's behavior see memkind(3).
113 memtier_kind_malloc() is a wrapper to the memkind_malloc() function.
115 See memkind(3) for further details.
116 memtier_calloc() allocates num times size bytes of memory on one of
118 memory tiers defined by the memory. memkind_calloc() is used for allo‐
119 cations. For further details on it's behavior see memkind(3).
120 memtier_kind_calloc() is a wrapper to the memkind_calloc() function.
122 See memkind(3) for further details.
123 memtier_realloc() changes the size of the previously allocated memory
125 referenced by ptr to size bytes using memory from the tier on which ptr
126 is allocated. If ptr is NULL, new memory is allocated on a memory tier
127 defined by memory. memkind_realloc() is used for reallocation. See
128 memkind(3) for further details.
129 memtier_kind_realloc() changes the size of the previously allocated
131 memory referenced by ptr to size bytes using specific kind. If size is
132 equal to zero and ptr is not NULL, then the call is equivalent to
133 memkind_free(kind, ptr) and NULL is returned. If ptr is NULL,
134 memtier_kind_malloc() is called to allocate new memory. Otherwise, the
135 memkind_realloc() function is used. See memkind(3) for further de‐
136 tails.
137 memtier_posix_memalign() is a wrapper of memkind_posix_memalign() with
139 the main difference that the memory is used to determine the kind to be
140 used for the allocation. See memkind(3) for further details.
141 memtier_kind_posix_memalign() is a wrapper of memkind_posix_memalign().
143 See memkind(3) for further details.
144 memtier_usable_size() returns the size of the block of memory allocated
146 with the memtier API at the address pointed by ptr.
147 memtier_free() is a wrapper for the memtier_kind_free() function with
149 the kind parameter passed as NULL.
150 memtier_kind_free() frees up the memory pointed to by ptr. The behav‐
152 ior is the same as for the memkind_free(). If kind is NULL, the kind
153 used to allocate ptr is detected automatically. See memkind(3) for
154 further details.
155 memtier_kind_allocated_size() returns the total size of memory allo‐
157 cated with the usage of kind and the memtier API.
158 DECORATORS:
160 This is the set of functions used to print information on each call to
161 the respective memtier_kind_* function described in the HEAP MANAGEMENT
162 section. Printed information include the name of the kind used, param‐
163 eters passed to the underlying function from the malloc family of func‐
164 tions and the address of the memory returned.
165 MEMTIER PROPERTY MANAGEMENT:
167 memtier_ctl_set() is useful for changing the default values of parame‐
168 ters that define the DYNAMIC_THRESHOLD policy. This function can be
169 used in the process of creating a memtier_memory object with the usage
170 of builder. The parameter name can be one of the following:
171 policy.dynamic_threshold.thresholds[ID].val
173 initial threshold level, all alocations of the size below this
174 value will come from the IDth tier, greater than or equal to
175 this value will come from the (ID+1)th tier. Provided string is
176 converted to the size_t type. This value is modified automati‐
177 cally during the application run to keep the desired ratio be‐
178 tween tiers. The default value between first two tiers is 1024
179 bytes
180 policy.dynamic_threshold.thresholds[ID].min
182 minimum value of the threshold level. Provided string is con‐
183 verted to the size_t type. The default value between first two
184 tiers is 513 bytes.
185 policy.dynamic_threshold.thresholds[ID].max
187 maximum value of the threshold level. Provided string is con‐
188 verted to the size_t type. The default value between first two
189 tiers is 1536 bytes.
190 policy.dynamic_threshold.check_cnt
192 number of allocation operations (i.e. malloc, realloc) after
193 which the ratio check between tiers is performed. Provided
194 string is converted to the unsigned int type. The default value
195 is 20.
196 policy.dynamic_threshold.trigger
198 the dynamic threshold value is adjusted when the absolute dif‐
199 ference between current ratio and expected ratio is greater than
200 or equal to this value. Provided string is converted to the
201 float type. The default value is 0.02.
202 policy.dynamic_threshold.degree
204 the threshold value is updated by increasing or decreasing it's
205 value by degree percentage (i.e. degree=0.02 changes threshold
206 value by 2%). Provided string is converted to the float type.
207 The default value is 0.15.
208 In the above examples, ID should be replaced with the ID of thresholds
210 configuration. The configuration between first two tiers added to
211 builder has an ID equal to 0. The configuration ID of the next two
212 tiers, that is, the second and third ones, is equal to 1, and so on.
213 The last configuration's ID is equal to the number of tiers minus one.
214
217 See libmemtier(7) for details on the usage of memkind tiering via envi‐
218 ronment variables.
219
222 Copyright (C) 2021-2022 Intel Corporation. All rights reserved.
223
225 libmemtier(7), memkind(3), memkind_malloc(3), memkind_calloc(3),
226 memkind_realloc(3), memkind_free(3), memkind_posix_memalign(3)
227Intel Corporation 2022-06-23 LIBMEMTIER C API(3)