--- name: "memkind_arena" section: "3" platform: "linux" package: "libmemkind-dev" version: "1.14.0-2" release: "Debian 12 (Bookworm)" platforms: ["linux"] url: "https://new.carta.tech/memkind_arena" --- # memkind\_arena(3) jemalloc arena allocation memkind operations. Note: This is EXPERIMENTAL API. The functionality and the header file itself can be changed (including non-backward compatible changes) or removed. ## NAME memkind\_arena - jemalloc arena allocation memkind operations.\ **Note:** This is EXPERIMENTAL API. The functionality and the header file itself can be changed (including non-backward compatible changes) or removed. ## 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 This header file is a collection of functions can be used to populate the memkind operations structure for memory kinds that use jemalloc. **memkind\_arena\_create**() is an implementation of the memkind "create" operation for memory kinds that use jemalloc. This calls **memkind\_default\_create**() (see [**memkind\_default**(3)](/memkind_default/3.md)) followed by **memkind\_arena\_create\_map**() described below. **memkind\_arena\_create\_map**() creates the *arena\_map* array for the memkind structure pointed to by *kind* which can be indexed by the **ops.get\_arena**() function from the kind's operations. If get\_arena points **memkind\_thread\_get\_arena**() then there will be four arenas created for each processor, and if get\_arena points to **memkind\_bijective\_get\_arena**() then just one arena is created. **memkind\_arena\_destroy**() is an implementation of the memkind "destroy" operation for memory kinds that use jemalloc. This releases all of the resources allocated by **memkind\_arena\_create**(). **memkind\_arena\_malloc**() is an implementation of the memkind "malloc" operation for memory kinds that use jemalloc. This allocates memory using the arenas created by **memkind\_arena\_create**() through the jemalloc's **mallocx**() interface. It uses the memkind "get\_arena" operation to select the arena. **memkind\_arena\_calloc**() is an implementation of the memkind "calloc" operation for memory kinds that use jemalloc. This allocates memory using the arenas created by **memkind\_arena\_create**() through the jemalloc's **mallocx**() interface. It uses the memkind "get\_arena" operation to select the arena. **memkind\_arena\_posix\_memalign**() is an implementation of the memkind "posix\_memalign" operation for memory kinds that use jemalloc. This allocates memory using the arenas created by **memkind\_arena\_create**() through the jemalloc's **mallocx**() interface. It uses the memkind "get\_arena" operation to select the arena. The POSIX standard requires that [**posix\_memalign**(3)](/posix_memalign/3.md) may not set *errno* however the jemalloc's **mallocx**() routine may. In an attempt to abide by the standard *errno* is recorded before calling jemalloc's **mallocx**() and then reset after the call. **memkind\_arena\_realloc**() is an implementation of the memkind "realloc" operation for memory kinds that use jemalloc. This allocates memory using the arenas created by **memkind\_arena\_create**() through the jemalloc's **mallocx**() interface. It uses the memkind "get\_arena" operation to select the arena. **memkind\_arena\_realloc\_with\_kind\_detect**() function will look up for kind associated to the allocated memory referenced by *ptr* and call (depending on kind value) **memkind\_arena\_realloc**() or **memkind\_default\_realloc**(). **memkind\_thread\_get\_arena**() retrieves the *arena* index that is bound to to the calling thread based on a hash of its thread ID. The *arena* index can be used with the MALLOCX\_ARENA macro to set flags for jemalloc's **mallocx**(). **memkind\_bijective\_arena\_get\_arena**() retrieves the *arena* index to be used with the MALLOCX\_ARENA macro to set flags for jemalloc's **mallocx**(). Use of this operation implies that only one arena is used for the *kind*. **memkind\_arena\_free**() is 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. **memkind\_arena\_free\_with\_kind\_detect**() function will look up for kind associated to the allocated memory referenced by *ptr* and call **memkind\_arena\_free**(). **memkind\_arena\_detect\_kind**() returns pointer to memory kind structure associated with given allocated memory referenced by *ptr*. **get\_kind\_by\_arena**() returns pointer to memory kind structure associated with given arena. **memkind\_arena\_finalize**() is 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 **exit**() function. **memkind\_arena\_init**() creates arena map with proper hooks per specified kind. **memkind\_arena\_update\_memory\_usage\_policy**() function changes time, which determine how fast jemalloc returns unused pages back to the operating system, in other words how fast it deallocates file space. **memkind\_arena\_set\_max\_bg\_threads**() sets the maximum number of internal background worker threads in jemalloc. The *threads\_limit* specify 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 function **je\_malloc\_stats\_print**(). Uses *write\_cb* function to print the output. While providing custom writer function, use **[syscall(2)](/syscall/2.md)** rather than **[write(2)](/write/2.md)** Pass *NULL* in order to use the default write\_cb function which prints the output to the stderr. Use *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 failed to parse options string, MEMKIND\_SUCCESS on success. ## MEMORY STATISTICS PRINT OPTIONS The available options for printing statistics: - **MEMKIND\_STAT\_PRINT\_ALL** Print all statistics. - **MEMKIND\_STAT\_PRINT\_JSON\_FORMAT** Print statistics in JSON format. - **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/3.md), [**memkind\_default**(3)](/memkind_default/3.md), [**memkind\_hbw**(3)](/memkind_hbw/3.md), [**memkind\_hugetlb**(3)](/memkind_hugetlb/3.md), [**memkind\_pmem**(3)](/memkind_pmem/3.md), [**jemalloc**(3)](/jemalloc/3.md), [**mbind**(2)](/mbind/2.md), [**mmap**(2)](/mmap/2.md), **[syscall(2)](/syscall/2.md),** **[write(2)](/write/2.md)**