MEMKIND_ARENA(3)

💅 MEMKIND_ARENA — bestie edition 💅

okay so you're in the memkind_arena(3) manual page, which is a whole thing about jemalloc arena allocation memkind operations ✨

⚠️ REAL TALK FIRST: this is EXPERIMENTAL API. The functionality and the header file itself can be changed (yes, even in ways that break backwards compatibility 😭) or straight up removed. Don't build your whole personality on it, okay? 🫶

---

✨ SYNOPSIS ✨

int memkind_arena_create(struct memkind *kind, struct memkind_ops *ops,
const char *name);
int memkind_arena_create_map(struct memkind *kind, extent_hooks_t
*hooks);
int memkind_arena_destroy(struct memkind *kind);
void *memkind_arena_malloc(struct memkind *kind, size_t size);
void *memkind_arena_calloc(struct memkind *kind, size_t num, size_t
size);
int memkind_arena_posix_memalign(struct memkind *kind, void **memptr,
size_t alignment, size_t size);
void *memkind_arena_realloc(struct memkind *kind, void *ptr, size_t
size);
void *memkind_arena_realloc_with_kind_detect(void *ptr, size_t size);
int memkind_thread_get_arena(struct memkind *kind, unsigned int *arena,
size_t size);
int memkind_bijective_get_arena(struct memkind *kind, unsigned int
*arena, size_t size);
struct memkind *get_kind_by_arena(unsigned arena_ind);
struct memkind *memkind_arena_detect_kind(void *ptr);
int memkind_arena_finalize(struct memkind *kind);
void memkind_arena_init(struct memkind *kind);
void memkind_arena_free(struct memkind *kind, void *ptr);
void memkind_arena_free_with_kind_detect(void *ptr);
int memkind_arena_update_memory_usage_policy(struct memkind *kind,
memkind_mem_usage_policy policy);
int memkind_arena_set_max_bg_threads(size_t threads_limit);
int memkind_arena_set_bg_threads(bool state);
int memkind_arena_stats_print(void (*write_cb) (void *, const char *),
void *cbopaque, memkind_stat_print_opt opts);

---

🌸 DESCRIPTION 🌸

so this header file is literally just a collection of functions you can use to populate the memkind operations structure for memory kinds that use jemalloc. that's the vibe. 🧚

memkind_arena_create() — this is an implementation of the memkind "create" operation for memory kinds that use jemalloc. it calls memkind_default_create() (peep memkind_default(3) for that one 👀) and then memkind_arena_create_map() which is described right below. slay.

memkind_arena_create_map() — creates the arena_map array for the memkind structure pointed to by kind, and that array can be indexed by the ops.get_arena() function from the kind's operations. here's the tea 🍓: if get_arena points to memkind_thread_get_arena() then four arenas get created for each processor, and if get_arena points to memkind_bijective_get_arena() then it's just one arena. that's it, that's the whole deal.

memkind_arena_destroy() — an implementation of the memkind "destroy" operation for memory kinds that use jemalloc. it releases all of the resources allocated by memkind_arena_create(). bye bestie 👋

memkind_arena_malloc() — an implementation of the memkind "malloc" operation for memory kinds that use jemalloc. it allocates memory using the arenas created by memkind_arena_create() through jemalloc's mallocx() interface. it uses the memkind "get_arena" operation to select the arena. iconic.

memkind_arena_calloc() — an implementation of the memkind "calloc" operation for memory kinds that use jemalloc. allocates memory using the arenas created by memkind_arena_create() through jemalloc's mallocx() interface. uses the memkind "get_arena" operation to select the arena. same energy, different letter 🎀

memkind_arena_posix_memalign() — an implementation of the memkind "posix_memalign" operation for memory kinds that use jemalloc. allocates memory using the arenas created by memkind_arena_create() through jemalloc's mallocx() interface, and uses the memkind "get_arena" operation to select the arena. now here's the ✨drama✨: the POSIX standard requires that posix_memalign(3) may not set errno, but jemalloc's mallocx() routine may. so in an attempt to abide by the standard, errno is recorded before calling jemalloc's mallocx() and then reset after the call. crisis averted 💅

memkind_arena_realloc() — an implementation of the memkind "realloc" operation for memory kinds that use jemalloc. allocates memory using the arenas created by memkind_arena_create() through jemalloc's mallocx() interface. uses the memkind "get_arena" operation to select the arena.

memkind_arena_realloc_with_kind_detect() — this function will look up the kind associated to the allocated memory referenced by ptr and call (depending on the kind value) memkind_arena_realloc() or memkind_default_realloc(). detective behavior, lowkey 🔍

memkind_thread_get_arena() — retrieves the arena index that is bound to the calling thread, based on a hash of its thread ID. that arena index can be used with the MALLOCX_ARENA macro to set flags for jemalloc's mallocx(). ur thread, ur arena 🦋

memkind_bijective_arena_get_arena() — retrieves the arena index to be used with the MALLOCX_ARENA macro to set flags for jemalloc's mallocx(). using this operation implies that only one arena is used for the kind. minimalism, but make it memory allocation.

memkind_arena_free() — an implementation of the memkind "free" operation for memory kinds that use jemalloc. it causes the allocated memory referenced by ptr — which must have been returned by a previous call to memkind_arena_malloc(), memkind_arena_calloc() or memkind_arena_realloc() — to be made available for future allocations. it uses the memkind "get_arena" operation to select the arena. no cap.

memkind_arena_free_with_kind_detect() — this function will look up the kind associated to the allocated memory referenced by ptr and call memkind_arena_free().

memkind_arena_detect_kind() — returns a pointer to the memory kind structure associated with the given allocated memory referenced by ptr.

get_kind_by_arena() — returns a pointer to the memory kind structure associated with the given arena. 🏟️

memkind_arena_finalize() — an implementation of the memkind "finalize" operation for memory kinds that use jemalloc. this function releases all resources allocated by memkind_arena_create() and it's called when main() finishes or after calling the exit() function. the end, periodt.

memkind_arena_init() — creates the arena map with proper hooks per specified kind.

memkind_arena_update_memory_usage_policy() — changes the time which determines how fast jemalloc returns unused pages back to the operating system — in other words, how fast it deallocates file space. speedrun any% 🏃♀️

memkind_arena_set_max_bg_threads() — sets the maximum number of internal background worker threads in jemalloc. the threads_limit specifies the limit of background threads which can be enabled (0 means no limit).

memkind_arena_set_bg_threads() — enables/disables internal background worker threads in jemalloc. 🫶

memkind_arena_stats_print() — prints summary statistics. this function wraps jemalloc's je_malloc_stats_print() function. it uses the write_cb function to print the output. while providing a custom writer function, use syscall(2) rather than write(2). pass NULL in order to use the default write_cb function, which prints the output to the stderr. use the cbopaque parameter in order to pass some data to your write_cb function. pass additional options using opts. for more details on opts see the MEMORY STATISTICS PRINT OPTIONS section below. returns MEMKIND_ERROR_INVALID when it fails to parse the options string, and MEMKIND_SUCCESS on success. ✨

---

🔥 MEMORY STATISTICS PRINT OPTIONS 🔥

the available options for printing statistics, bestie:

• MEMKIND_STAT_PRINT_ALL — print all statistics. everything. the whole buffet 🍓
• MEMKIND_STAT_PRINT_JSON_FORMAT — print statistics in JSON format. curly braces core 🎀
• MEMKIND_STAT_PRINT_OMIT_GENERAL — omit general information that never changes during execution.
• MEMKIND_STAT_PRINT_OMIT_MERGED_ARENA — omit merged arena statistics.
• MEMKIND_STAT_PRINT_OMIT_DESTROYED_MERGED_ARENA — omit destroyed merged arena statistics.
• MEMKIND_STAT_PRINT_OMIT_PER_ARENA — omit per arena statistics.
• MEMKIND_STAT_PRINT_OMIT_PER_SIZE_CLASS_BINS — omit per size class statistics for bins.
• MEMKIND_STAT_PRINT_OMIT_PER_SIZE_CLASS_LARGE — omit per size class statistics for large objects.
• MEMKIND_STAT_PRINT_OMIT_MUTEX — omit all mutex statistics.
• MEMKIND_STAT_PRINT_OMIT_EXTENT — omit extent statistics.

---

👑 COPYRIGHT 👑

copyright (C) 2014 - 2021 Intel Corporation. all rights reserved.

---

🌈 SEE ALSO 🌈

memkind(3), memkind_default(3), memkind_hbw(3), memkind_hugetlb(3), memkind_pmem(3), jemalloc(3), mbind(2), mmap(2), syscall(2), write(2)

---

okay that's the whole page bestie, u ate that read 💖 tysm for sticking around — this one's brought to you by Intel Corporation, dated 2015-04-21, and it's the MEMKIND_ARENA(3) page. mwah 💋 no cap, go forth and allocate responsibly ✨🎀🦋