LIBMEMTIER(3)

💖 LIBMEMTIER C API 💖

okay bestie, pull up a chair, we're doing the libmemtier C API today — this is the memory tiering interface and she is lowkey iconic. ✨

quick note from the front desk: everything in memkind_memtier.h is considered stable API (that's the STANDARD API, babes — she's not going anywhere). 🎀</p>

---

✨ SYNOPSIS ✨

#include <memkind_memtier.h>

Link with -lmemkind 🫶

You can use this API either directly with the C functions, or via environment variables — go peek at the ENVIRONMENT section for that whole vibe. 👀

TIER MANAGEMENT:

struct memtier_builder *memtier_builder_new(memtier_policy_t policy);
void memtier_builder_delete(struct memtier_builder *builder);
int memtier_builder_add_tier(struct memtier_builder *builder, memkind_t kind, unsigned kind_ratio);
struct memtier_memory *memtier_builder_construct_memtier_memory(struct memtier_builder *builder);
void memtier_delete_memtier_memory(struct memtier_memory *memory);

HEAP MANAGEMENT:

void *memtier_malloc(struct memtier_memory *memory, size_t size);
void *memtier_kind_malloc(memkind_t kind, size_t size);
void *memtier_calloc(struct memtier_memory *memory, size_t num, size_t size);
void *memtier_kind_calloc(memkind_t kind, size_t num, size_t size);
void *memtier_realloc(struct memtier_memory *memory, void *ptr, size_t size);
void *memtier_kind_realloc(memkind_t kind, void *ptr, size_t size);
int memtier_posix_memalign(struct memtier_memory *memory, void **memptr, size_t alignment, size_t size);
int memtier_kind_posix_memalign(memkind_t kind, void **memptr, size_t alignment, size_t size);
size_t memtier_usable_size(void *ptr);
void memtier_free(void *ptr);
void memtier_kind_free(memkind_t kind, void *ptr);
size_t memtier_kind_allocated_size(memkind_t kind);

DECORATORS:

void memtier_kind_malloc_post(memkind_t kind, size_t size, void **result);
void memtier_kind_calloc_post(memkind_t kind, size_t nmemb, size_t size, void **result);
void memtier_kind_posix_memalign_post(memkind_t kind, void **memptr, size_t alignment, size_t size, int *err);
void memtier_kind_realloc_post(memkind_t *kind, void *ptr, size_t size, void **result);
void memtier_kind_free_pre(void **ptr);
void memtier_kind_usable_size_post(void **ptr, size_t size);

MEMTIER PROPERTY MANAGEMENT:

int memtier_ctl_set(struct memtier_builder *builder, const char *name, const void *val);

---

🌸 DESCRIPTION 🌸

So. This library enables explicit allocation-time memory tiering. Basically it lets you make allocations using multiple kinds while keeping a specified ratio between them. That ratio is the whole plot: it decides how much of your total allocated memory should go to each kind. it's giving ✨balance✨

💅 TIER MANAGEMENT

These functions are your setup crew — they create, configure and destroy the memtier_memory object. That object then gets passed as an argument to the memtier_malloc() group of functions, and it defines the way allocations get distributed between different memory tiers. main character energy, honestly. 👑

• memtier_builder_new() — returns a pointer to a brand-new memtier_builder object, which you use for creating the memtier_memory object. The policy argument determines the policy of allocation distribution between tiers by the memtier_memory object. Available options live in the POLICIES section of libmemtier(7). go read it bestie.
• memtier_builder_delete() — deletes the builder object and releases the memory it used. Use it after the memtier_memory object has been created with memtier_builder_construct_memtier_memory(). don't delete her early, that's rude. 🚫
• memtier_builder_add_tier() — adds a memory kind to the builder. That kind defines a memory tier used in the memtier_memory object. Call this more than once to create several different memory tiers! The "weight" of the tier is determined by the kind_ratio parameter — the higher it is relative to other tiers' kind_ratio, the higher the share of allocated memory on that tier. Example: given that ratio DRAM:KMEM_DAX is 1:4:

sample allocation size: 20 GB total, 4 GB DRAM, 16 GB KMEM_DAX

• memtier_builder_construct_memtier_memory() — returns a pointer to a newly allocated memtier_memory object. After this operation the builder can be safely removed using memtier_builder_delete(). 🫡
• memtier_delete_memtier_memory() — deletes the memory tiering object, releasing the memory it used. bye girl 💜

🎀 HEAP MANAGEMENT

These functions define a heap manager whose interface is modeled on the ISO C standard API's — except that you have to specify either the kind of memory (as the first argument to each function) or the tiered memory object that defines which memory tiers get used for allocations. For a full description of the implemented kinds, see the KINDS section in the memkind(3) manual. no cap. 📚

• memtier_malloc() — allocates size bytes of memory on one of the memory tiers defined by memory. See libmemtier(7) for further details on memory tiers. memkind_malloc() is used for allocations — for further details on its behavior see memkind(3).
• memtier_kind_malloc() — a wrapper to the memkind_malloc() function. See memkind(3) for further details.
• memtier_calloc() — allocates num times size bytes of memory on one of memory tiers defined by memory. memkind_calloc() is used for allocations. For further details on its behavior see memkind(3).
• memtier_kind_calloc() — a wrapper to the memkind_calloc() function. See memkind(3) for further details.
• memtier_realloc() — changes the size of the previously allocated memory referenced by ptr to size bytes, using memory from the tier on which ptr is allocated. If ptr is NULL, new memory is allocated on a memory tier defined by memory. memkind_realloc() is used for reallocation. See memkind(3) for further details.
• memtier_kind_realloc() — changes the size of the previously allocated memory referenced by ptr to size bytes using a specific kind. If size is equal to zero and ptr is not NULL, then the call is equivalent to memkind_free(kind, ptr) and NULL is returned. If ptr is NULL, memtier_kind_malloc() is called to allocate new memory. Otherwise, the memkind_realloc() function is used. See memkind(3) for further details.
• memtier_posix_memalign() — a wrapper of memkind_posix_memalign(), with the main difference that memory is used to determine the kind to be used for the allocation. See memkind(3) for further details.
• memtier_kind_posix_memalign() — a wrapper of memkind_posix_memalign(). See memkind(3) for further details.
• memtier_usable_size() — returns the size of the block of memory allocated with the memtier API at the address pointed to by ptr. 📏
• memtier_free() — a wrapper for the memtier_kind_free() function with the kind parameter passed as NULL.
• memtier_kind_free() — frees up the memory pointed to by ptr. The behavior is the same as for memkind_free(). If kind is NULL, the kind used to allocate ptr is detected automatically. See memkind(3) for further details.
• memtier_kind_allocated_size() — returns the total size of memory allocated with the usage of kind and the memtier API. 🔥

🦋 DECORATORS

This is the little set of functions used to print information on each call to the respective memtier_kind_* function described in the HEAP MANAGEMENT section. The printed info includes: the name of the kind used, the parameters passed to the underlying function from the malloc family of functions, and the address of the memory returned. she's nosy and we love her for it 🙈

💜 MEMTIER PROPERTY MANAGEMENT

memtier_ctl_set() is useful for changing the default values of parameters that define the DYNAMIC_THRESHOLD policy. You can use this function while creating a memtier_memory object with the usage of a builder. The parameter name can be one of the following:

• policy.dynamic_threshold.thresholds[ID].val — the initial threshold level. All allocations of the size below this value will come from the IDth tier; sizes greater than or equal to this value will come from the (ID+1)th tier. The provided string is converted to the size_t type. This value is modified automatically during the application run to keep the desired ratio between tiers. The default value between the first two tiers is 1024 bytes.
• policy.dynamic_threshold.thresholds[ID].min — the minimum value of the threshold level. The provided string is converted to the size_t type. The default value between the first two tiers is 513 bytes.
• policy.dynamic_threshold.thresholds[ID].max — the maximum value of the threshold level. The provided string is converted to the size_t type. The default value between the first two tiers is 1536 bytes.
• policy.dynamic_threshold.check_cnt — the number of allocation operations (i.e. malloc, realloc) after which the ratio check between tiers is performed. The provided string is converted to the unsigned int type. The default value is 20.
• policy.dynamic_threshold.trigger — the dynamic threshold value is adjusted when the absolute difference between the current ratio and the expected ratio is greater than or equal to this value. The provided string is converted to the float type. The default value is 0.02.
• policy.dynamic_threshold.degree — the threshold value is updated by increasing or decreasing its value by degree percentage (i.e. degree=0.02 changes the threshold value by 2%). The provided string is converted to the float type. The default value is 0.15.

In the above examples, ID should be replaced with the ID of the thresholds configuration. The configuration between the first two tiers added to the builder has an ID equal to 0. The configuration ID of the next two tiers — that is, the second and third ones — is equal to 1, and so on. The last configuration's ID is equal to the number of tiers minus one. math girlie behavior, honestly 🧮✨

---

🌈 ENVIRONMENT 🌈

See libmemtier(7) for details on the usage of memkind tiering via environment variables. 🍓

---

👑 COPYRIGHT 👑

Copyright (C) 2021-2022 Intel Corporation. All rights reserved.

---

⭐ SEE ALSO ⭐

libmemtier(7), memkind(3), memkind_malloc(3), memkind_calloc(3), memkind_realloc(3), memkind_free(3), memkind_posix_memalign(3)

---

okay that's the whole page, bestie — brought to you by Intel Corporation, dated 2022-06-23, and she ate. 💅 no crumbs. go allocate responsibly 🫶💖✨