--- name: "libmemtier" section: "3" platform: "linux" package: "libmemkind-dev" version: "1.14.0-2" release: "Debian 12 (Bookworm)" platforms: ["linux"] url: "https://new.carta.tech/libmemtier" --- # libmemtier(3) memory tiering interface Note: memkind\_memtier.h functionality is considered as stable API (STANDARD API). ## NAME libmemtier - memory tiering interface\ **Note:** *memkind\_memtier.h* functionality is considered as stable API (STANDARD API). ## SYNOPSIS **#include \** **Link with -lmemkind** The API can be used either directly with the usage of C-functions or via environment variables. See also **ENVIRONMENT** section. **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 This library enables explicit allocation-time memory tiering. It allows to make allocations with the usage of multiple kinds keeping a specified ratio between them. This ratio determines how much of total allocated memory should be allocated with the usage of each kind. **TIER MANAGEMENT:**\ The functions in this section are used to set up, create and destroy the *memtier\_memory* object. This object is passed as an argument to the **memtier\_malloc**() group of functions. It defines the way the allocations are distributed between different memory tiers. **memtier\_builder\_new**() returns a pointer to a new *memtier\_builder* object which is used for creating the *memtier\_memory* object, *policy* determines the policy of allocations distribution between tiers by the *memtier\_memory* object. See the **POLICIES** section in [**libmemtier**(7)](/libmemtier/7.md) for available options. **memtier\_builder\_delete**() deletes the *builder* object releasing the memory it used. Use after the *memtier\_memory* object is created with the function *memtier\_builder\_construct\_memtier\_memory*(). **memtier\_builder\_add\_tier**() adds memory *kind* to the *builder*. This *kind* defines a memory tier used in the **memtier\_memory** object. This function can be called 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, e.g. 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. The *builder* can be safely removed after this operation using the **memtier\_builder\_delete**() function. **memtier\_delete\_memtier\_memory**() deletes the *memory* tiering object releasing the memory it used. **HEAP MANAGEMENT:**\ The functions described in this section define a heap manager with an interface modeled on the ISO C standard API's, except that the user must specify either the *kind* of memory with the first argument to each function or the tiered *memory* object which defines memory tiers used for allocations. See the **KINDS** section in the [**memkind**(3)](/memkind/3.md) manual for a full description of the implemented kinds. **memtier\_malloc**() allocates *size* bytes of memory on one of memory tiers defined by the *memory*. See [**libmemtier**(7)](/libmemtier/7.md) for further details on memory tiers. **memkind\_malloc**() is used for allocations. For further details on it's behavior see [**memkind**(3)](/memkind/3.md). **memtier\_kind\_malloc**() is a wrapper to the **memkind\_malloc**() function. See [**memkind**(3)](/memkind/3.md) for further details. **memtier\_calloc**() allocates *num* times *size* bytes of memory on one of memory tiers defined by the *memory*. **memkind\_calloc**() is used for allocations. For further details on it's behavior see [**memkind**(3)](/memkind/3.md). **memtier\_kind\_calloc**() is a wrapper to the **memkind\_calloc**() function. See [**memkind**(3)](/memkind/3.md) 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)](/memkind/3.md) for further details. **memtier\_kind\_realloc**() changes the size of the previously allocated memory referenced by *ptr* to *size* bytes using 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)](/memkind/3.md) for further details. **memtier\_posix\_memalign**() is a wrapper of **memkind\_posix\_memalign**() with the main difference that the *memory* is used to determine the kind to be used for the allocation. See [**memkind**(3)](/memkind/3.md) for further details. **memtier\_kind\_posix\_memalign**() is a wrapper of **memkind\_posix\_memalign**(). See [**memkind**(3)](/memkind/3.md) for further details. **memtier\_usable\_size**() returns the size of the block of memory allocated with the memtier API at the address pointed by *ptr*. **memtier\_free**() is 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 the **memkind\_free**(). If *kind* is *NULL*, the kind used to allocate *ptr* is detected automatically. See [**memkind**(3)](/memkind/3.md) 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 set of functions used to print information on each call to the respective *memtier\_kind\_\** function described in the **HEAP MANAGEMENT** section. Printed information include the name of the **kind** used, parameters passed to the underlying function from the malloc family of functions and the address of the memory returned. **MEMTIER PROPERTY MANAGEMENT:**\ **memtier\_ctl\_set**() is useful for changing the default values of parameters that define the *DYNAMIC\_THRESHOLD* policy. This function can be used in the process of creating a **memtier\_memory** object with the usage of *builder*. The parameter *name* can be one of the following: - policy.dynamic\_threshold.thresholds\[ID\].val initial threshold level, all alocations of the size below this value will come from the *IDth* tier, greater than or equal to this value will come from the *(ID+1)th* tier. 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 first two tiers is 1024 bytes - policy.dynamic\_threshold.thresholds\[ID\].min minimum value of the threshold level. Provided string is converted to the *size\_t* type. The default value between first two tiers is 513 bytes. - policy.dynamic\_threshold.thresholds\[ID\].max maximum value of the threshold level. Provided string is converted to the *size\_t* type. The default value between first two tiers is 1536 bytes. - policy.dynamic\_threshold.check\_cnt number of allocation operations (i.e. malloc, realloc) after which the ratio check between tiers is performed. 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 current ratio and expected ratio is greater than or equal to this value. 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 it's value by *degree* percentage (i.e. *degree*=0.02 changes threshold value by 2%). 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 thresholds configuration. The configuration between first two tiers added to **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. ## ENVIRONMENT See [**libmemtier**(7)](/libmemtier/7.md) 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)](/libmemtier/7.md), [**memkind**(3)](/memkind/3.md), **memkind\_malloc**(3), **memkind\_calloc**(3), **memkind\_realloc**(3), **memkind\_free**(3), **memkind\_posix\_memalign**(3)