API Documentation#

Globals#

Defines

UMF_MAKE_VERSION(_major, _minor)#: Generates generic ‘UMF’ API versions.

UMF_MAJOR_VERSION(_ver)#: Extracts ‘UMF’ API major version.

UMF_MINOR_VERSION(_ver)#: Extracts ‘UMF’ API minor version.

UMF_VERSION_CURRENT#: Current version of the UMF headers.

Enums

enum umf_result_t#

Operation results.

Values:

enumerator UMF_RESULT_SUCCESS#: Success.

enumerator UMF_RESULT_ERROR_OUT_OF_HOST_MEMORY#: Insufficient host memory to satisfy call.

enumerator UMF_RESULT_ERROR_MEMORY_PROVIDER_SPECIFIC#: A provider specific warning/error has been reported and can be Retrieved via the umfMemoryProviderGetLastNativeError entry point.

enumerator UMF_RESULT_ERROR_INVALID_ARGUMENT#: Generic error code for invalid arguments.

enumerator UMF_RESULT_ERROR_INVALID_ALIGNMENT#: Invalid alignment of an argument.

enumerator UMF_RESULT_ERROR_NOT_SUPPORTED#: Operation not supported.

enumerator UMF_RESULT_ERROR_USER_SPECIFIC#: Failure in user provider code (i.e in user provided callback)

enumerator UMF_RESULT_ERROR_UNKNOWN#: Unknown or internal error.

Pools#

The UMF memory pool is a combination of a pool allocator and a memory provider. The pool allocator controls the memory pool and handles fine-grained memory allocations memory allocations.

UMF includes predefined pool allocators. UMF can also work with user-defined pools which implement the memory pool API.

Memory Pool#

The memory pool API provides a malloc-like API for allocating and deallocating memory as well as functions that create, destroy and operate on the pool.

Enums

enum umf_pool_create_flag_t#

Supported pool creation flags.

Values:

enumerator UMF_POOL_CREATE_FLAG_NONE#: Pool will be created with no additional flags.

enumerator UMF_POOL_CREATE_FLAG_OWN_PROVIDER#: Pool will own the specified provider and destroy it in umfPoolDestroy.

enumerator UMF_POOL_CREATE_FLAG_DISABLE_TRACKING#: Pool will not track memory allocations

Typedefs

typedef struct umf_memory_pool_t *umf_memory_pool_handle_t#: A struct containing a memory pool handle alongside an ops structure containing pointers to implementations of provider-specific functions.

typedef struct umf_memory_pool_ops_t umf_memory_pool_ops_t#: This structure comprises function pointers used by corresponding umfPool* calls. Each memory pool implementation should initialize all function pointers.

typedef enum umf_pool_create_flag_t umf_pool_create_flag_t: Supported pool creation flags.

typedef uint32_t umf_pool_create_flags_t#: Type for combinations of pool creation flags.

Functions

umf_result_t umfPoolCreate(const umf_memory_pool_ops_t *ops, umf_memory_provider_handle_t provider, void *params, umf_pool_create_flags_t flags, umf_memory_pool_handle_t *hPool)#

Creates new memory pool.

Parameters:

ops – instance of umf_memory_pool_ops_t
provider – memory provider that will be used for coarse-grain allocations.
params – pointer to pool-specific parameters
flags – a combination of umf_pool_create_flag_t
hPool – [out] handle to the newly created memory pool

Returns:

UMF_RESULT_SUCCESS on success or appropriate error code on failure.

void umfPoolDestroy(umf_memory_pool_handle_t hPool)#

Destroys memory pool.

Parameters:

hPool – handle to the pool

void *umfPoolMalloc(umf_memory_pool_handle_t hPool, size_t size)#

Allocates size bytes of uninitialized storage from hPool.

Parameters:

hPool – specified memory hPool
size – number of bytes to allocate

Returns:

Pointer to the allocated memory.

void *umfPoolAlignedMalloc(umf_memory_pool_handle_t hPool, size_t size, size_t alignment)#

Allocates size bytes of uninitialized storage from the specified hPool with the specified alignment.

Parameters:

hPool – specified memory hPool
size – number of bytes to allocate
alignment – alignment of the allocation in bytes

Returns:

Pointer to the allocated memory

void *umfPoolCalloc(umf_memory_pool_handle_t hPool, size_t num, size_t size)#

Allocates memory from hPool for an array of num elements of size bytes each and initializes all bytes in the allocated storage to zero.

Parameters:

hPool – specified memory hPool
num – number of objects
size – number of bytes to allocate for each object

Returns:

Pointer to the allocated memory

void *umfPoolRealloc(umf_memory_pool_handle_t hPool, void *ptr, size_t size)#

Reallocates memory from hPool.

Parameters:

hPool – specified memory hPool
ptr – pointer to the memory block to be reallocated
size – new size for the memory block in bytes

Returns:

Pointer to the allocated memory

size_t umfPoolMallocUsableSize(umf_memory_pool_handle_t hPool, void *ptr)#

Obtains size of block of memory allocated from the hPool for a given ptr.

Parameters:

hPool – specified memory hPool
ptr – pointer to the allocated memory

Returns:

size of the memory block allocated from the hPool

umf_result_t umfPoolFree(umf_memory_pool_handle_t hPool, void *ptr)#

Frees the memory space of the specified hPool pointed by ptr.

Parameters:

hPool – specified memory hPool
ptr – pointer to the allocated memory to free

Returns:

UMF_RESULT_SUCCESS on success or appropriate error code on failure. Whether any status other than UMF_RESULT_SUCCESS can be returned depends on the memory provider used by the hPool.

umf_result_t umfFree(void *ptr)#

Frees the memory space pointed by ptr if it belongs to UMF pool, does nothing otherwise.

Parameters:

ptr – pointer to the allocated memory

Returns:

UMF_RESULT_SUCCESS on success or appropriate error code on failure. Whether any status other than UMF_RESULT_SUCCESS can be returned depends on the memory provider used by the pool.

umf_result_t umfPoolGetLastAllocationError(umf_memory_pool_handle_t hPool)#

Retrieve umf_result_t representing the error of the last failed allocation operation in this thread (malloc, calloc, realloc, aligned_malloc).

Implementations must store the error code in thread-local storage prior to returning NULL from the allocation functions.
If the last allocation/de-allocation operation succeeded, the value returned by this function is unspecified.
The application may call this function from simultaneous threads.
The implementation of this function should be lock-free.

Parameters:

hPool – specified memory pool handle for which the last allocation error is returned

Returns:

Error code describing the failure of the last failed allocation operation. The value is undefined if the previous allocation was successful.

umf_memory_pool_handle_t umfPoolByPtr(const void *ptr)#

Retrieve memory pool associated with a given ptr. Only memory allocated with the usage of a memory provider is being tracked.

Parameters:

ptr – pointer to memory belonging to a memory pool

Returns:

Handle to a memory pool that contains ptr or NULL if pointer does not belong to any UMF pool.

umf_result_t umfPoolGetMemoryProvider(umf_memory_pool_handle_t hPool, umf_memory_provider_handle_t *hProvider)#

Retrieve memory provider associated with a given pool.

Parameters:

hPool – specified memory pool
hProvider – [out] memory providers handle.

Returns:

UMF_RESULT_SUCCESS on success or appropriate error code on failure. UMF_RESULT_ERROR_INVALID_ARGUMENT if hProvider is NULL

Disjoint Pool#

The Disjoint Pool allocates user data using the configured provider, while also preserving metadata in DRAM.

Defines

UMF_DISJOINT_POOL_MIN_BUCKET_DEFAULT_SIZE#

Typedefs

typedef struct umf_disjoint_pool_shared_limits_t *umf_disjoint_pool_shared_limits_handle_t#: Memory limits that can be shared between multiple pool instances, i.e. if multiple pools use the same shared limits, sum of those pools’ sizes cannot exceed MaxSize.

typedef struct umf_disjoint_pool_params_t *umf_disjoint_pool_params_handle_t#: handle to the parameters of the disjoint pool.

Functions

umf_disjoint_pool_shared_limits_handle_t umfDisjointPoolSharedLimitsCreate(size_t MaxSize)#

Create a pool limits struct.

Parameters:

MaxSize – specifies hard limit for memory allocated from a provider.

Returns:

handle to the created shared limits struct.

void umfDisjointPoolSharedLimitsDestroy(umf_disjoint_pool_shared_limits_handle_t hSharedLimits)#

Destroy previously created pool limits struct.

Parameters:

hSharedLimits – handle to the shared limits struct.

umf_result_t umfDisjointPoolParamsCreate(umf_disjoint_pool_params_handle_t *hParams)#

Create a struct to store parameters of disjoint pool.

Parameters:

hParams – [out] handle to the newly created parameters struct.

Returns:

UMF_RESULT_SUCCESS on success or appropriate error code on failure.

umf_result_t umfDisjointPoolParamsDestroy(umf_disjoint_pool_params_handle_t hParams)#

Destroy parameters struct.

Parameters:

hParams – handle to the parameters of the disjoint pool.

Returns:

UMF_RESULT_SUCCESS on success or appropriate error code on failure.

umf_result_t umfDisjointPoolParamsSetSlabMinSize(umf_disjoint_pool_params_handle_t hParams, size_t slabMinSize)#

Set minimum allocation size that will be requested from the memory provider.

Parameters:

hParams – handle to the parameters of the disjoint pool.
slabMinSize – minimum allocation size.

Returns:

UMF_RESULT_SUCCESS on success or appropriate error code on failure.

umf_result_t umfDisjointPoolParamsSetMaxPoolableSize(umf_disjoint_pool_params_handle_t hParams, size_t maxPoolableSize)#

Set size limit for allocations that are subject to pooling.

Parameters:

hParams – handle to the parameters of the disjoint pool.
maxPoolableSize – maximum poolable size.

Returns:

UMF_RESULT_SUCCESS on success or appropriate error code on failure.

umf_result_t umfDisjointPoolParamsSetCapacity(umf_disjoint_pool_params_handle_t hParams, size_t maxCapacity)#

Set maximum capacity of each bucket. Each bucket will hold a max of maxCapacity unfreed slabs.

Parameters:

hParams – handle to the parameters of the disjoint pool.
maxCapacity – maximum capacity of each bucket.

Returns:

UMF_RESULT_SUCCESS on success or appropriate error code on failure.

umf_result_t umfDisjointPoolParamsSetMinBucketSize(umf_disjoint_pool_params_handle_t hParams, size_t minBucketSize)#

Set minimum bucket allocation size.

Parameters:

hParams – handle to the parameters of the disjoint pool.
minBucketSize – minimum bucket size. Must be power of 2.

Returns:

UMF_RESULT_SUCCESS on success or appropriate error code on failure.

umf_result_t umfDisjointPoolParamsSetTrace(umf_disjoint_pool_params_handle_t hParams, int poolTrace)#

Set trace level for pool usage statistics.

Parameters:

hParams – handle to the parameters of the disjoint pool.
poolTrace – trace level.

Returns:

UMF_RESULT_SUCCESS on success or appropriate error code on failure.

umf_result_t umfDisjointPoolParamsSetSharedLimits(umf_disjoint_pool_params_handle_t hParams, umf_disjoint_pool_shared_limits_handle_t hSharedLimits)#

Set shared limits for disjoint pool.

Parameters:

hParams – handle to the parameters of the disjoint pool.
hSharedLimits – handle tp the shared limits.

Returns:

UMF_RESULT_SUCCESS on success or appropriate error code on failure.

umf_result_t umfDisjointPoolParamsSetName(umf_disjoint_pool_params_handle_t hParams, const char *name)#

Set custom name of the disjoint pool to be used in the traces.

Parameters:

hParams – handle to the parameters of the disjoint pool.
name – custom name of the pool.

Returns:

UMF_RESULT_SUCCESS on success or appropriate error code on failure.

umf_memory_pool_ops_t *umfDisjointPoolOps(void)#

Jemalloc Pool#

A jemalloc-based memory pool manager. More info about jemalloc could be found here: jemalloc/jemalloc.

Typedefs

typedef struct umf_jemalloc_pool_params_t *umf_jemalloc_pool_params_handle_t#: handle to the parameters of the jemalloc pool.

Functions

umf_result_t umfJemallocPoolParamsCreate(umf_jemalloc_pool_params_handle_t *hParams)#

Create a struct to store parameters of jemalloc pool.

Parameters:

hParams – [out] handle to the newly created parameters struct.

Returns:

UMF_RESULT_SUCCESS on success or appropriate error code on failure.

umf_result_t umfJemallocPoolParamsDestroy(umf_jemalloc_pool_params_handle_t hParams)#

Destroy parameters struct.

Parameters:

hParams – handle to the parameters of the jemalloc pool.

Returns:

UMF_RESULT_SUCCESS on success or appropriate error code on failure.

umf_result_t umfJemallocPoolParamsSetKeepAllMemory(umf_jemalloc_pool_params_handle_t hParams, bool keepAllMemory)#

Set if umfMemoryProviderFree() should never be called.

Parameters:

hParams – handle to the parameters of the jemalloc pool.
keepAllMemory – true if the jemalloc pool should not call umfMemoryProviderFree, false otherwise.

Returns:

UMF_RESULT_SUCCESS on success or appropriate error code on failure.

umf_memory_pool_ops_t *umfJemallocPoolOps(void)#

Proxy Pool#

Proxy Pool forwards all requests to the underlying memory provider. Currently umfPoolRealloc, umfPoolCalloc and umfPoolMallocUsableSize functions are not supported by the Proxy Pool.

Functions

umf_memory_pool_ops_t *umfProxyPoolOps(void)#

Scalable Pool#

Typedefs

typedef struct umf_scalable_pool_params_t *umf_scalable_pool_params_handle_t#: handle to the parameters of the scalable pool.

Functions

umf_result_t umfScalablePoolParamsCreate(umf_scalable_pool_params_handle_t *hParams)#

Create a struct to store parameters of scalable pool.

Parameters:

hParams – [out] handle to the newly created parameters struct.

Returns:

UMF_RESULT_SUCCESS on success or appropriate error code on failure.

umf_result_t umfScalablePoolParamsDestroy(umf_scalable_pool_params_handle_t hParams)#

Destroy parameters struct.

Parameters:

hParams – handle to the parameters of the scalable pool.

Returns:

UMF_RESULT_SUCCESS on success or appropriate error code on failure.

umf_result_t umfScalablePoolParamsSetGranularity(umf_scalable_pool_params_handle_t hParams, size_t granularity)#

Set granularity of allocations that scalable pool requests from a memory provider.

Parameters:

hParams – handle to the parameters of the scalable pool.
granularity – granularity in bytes.

Returns:

UMF_RESULT_SUCCESS on success or appropriate error code on failure.

umf_result_t umfScalablePoolParamsSetKeepAllMemory(umf_scalable_pool_params_handle_t hParams, bool keepAllMemory)#

Set if scalable pool should keep all memory allocated from memory provider till destruction.

Parameters:

hParams – handle to the parameters of the scalable pool.
keepAllMemory – true if the scalable pool should not call umfMemoryProviderFree until it is destroyed, false otherwise.

Returns:

UMF_RESULT_SUCCESS on success or appropriate error code on failure.

umf_memory_pool_ops_t *umfScalablePoolOps(void)#

Return ops structure containing pointers to the scalable pool implementation.

Returns:: pointer to the umf_memory_pool_ops_t struct.

Providers#

The memory provider is responsible for coarse-grained memory allocations and memory page management.

UMF includes predefined providers, but can also work with providers which implement the memory provider API.

Memory Provider#

The memory provider API provides a functions for allocating, deallocating and manipulating coarse-grained memory as well as functions that create, destroy and operate on the provider.

Enums

enum umf_memory_visibility_t#

Memory visibility mode.

Values:

enumerator UMF_MEM_MAP_PRIVATE#: private memory mapping

enumerator UMF_MEM_MAP_SHARED#: shared memory mapping (Linux only)

enum umf_mem_protection_flags_t#

Protection of the memory allocations.

Values:

enumerator UMF_PROTECTION_NONE#: Memory allocations can not be accessed.

enumerator UMF_PROTECTION_READ#: Memory allocations can be read.

enumerator UMF_PROTECTION_WRITE#: Memory allocations can be written.

enumerator UMF_PROTECTION_EXEC#: Memory allocations can be executed.

Typedefs

typedef enum umf_memory_visibility_t umf_memory_visibility_t: Memory visibility mode.

typedef enum umf_mem_protection_flags_t umf_mem_protection_flags_t: Protection of the memory allocations.

typedef struct umf_memory_provider_t *umf_memory_provider_handle_t#: A struct containing memory provider specific set of functions.

Functions

umf_result_t umfMemoryProviderCreate(const umf_memory_provider_ops_t *ops, void *params, umf_memory_provider_handle_t *hProvider)#

Creates new memory provider.

Parameters:

ops – instance of umf_memory_provider_ops_t
params – pointer to provider-specific parameters
hProvider – [out] pointer to the newly created memory provider

Returns:

UMF_RESULT_SUCCESS on success or appropriate error code on failure.

void umfMemoryProviderDestroy(umf_memory_provider_handle_t hProvider)#

Destroys memory provider.

Parameters:

hProvider – handle to the memory provider

umf_result_t umfMemoryProviderAlloc(umf_memory_provider_handle_t hProvider, size_t size, size_t alignment, void **ptr)#

Allocates size bytes of uninitialized storage from memory hProvider with the specified alignment.

Parameters:

hProvider – handle to the memory provider
size – number of bytes to allocate
alignment – alignment of the allocation in bytes, it has to be a multiple or a divider of the minimum page size
ptr – [out] pointer to the allocated memory

Returns:

UMF_RESULT_SUCCESS on success or appropriate error code on failure

umf_result_t umfMemoryProviderFree(umf_memory_provider_handle_t hProvider, void *ptr, size_t size)#

Frees the memory space pointed by ptr from the memory hProvider.

Parameters:

hProvider – handle to the memory provider
ptr – pointer to the allocated memory to free
size – size of the allocation

Returns:

UMF_RESULT_SUCCESS on success or appropriate error code on failure

void umfMemoryProviderGetLastNativeError(umf_memory_provider_handle_t hProvider, const char **ppMessage, int32_t *pError)#

Retrieve string representation of the underlying provider specific result reported by the last API that returned UMF_RESULT_ERROR_MEMORY_PROVIDER_SPECIFIC. Allows for a provider independent way to return a provider specific result.

Implementations must store the message and error code in thread-local storage prior to returning UMF_RESULT_ERROR_MEMORY_PROVIDER_SPECIFIC.
The message and error code will only be valid if a previously called entry-point returned UMF_RESULT_ERROR_MEMORY_PROVIDER_SPECIFIC.
The memory pointed to by the C string returned in ppMessage is owned by the adapter and must be null terminated.
The application may call this function from simultaneous threads.
The implementation of this function should be lock-free.

Parameters:

hProvider – handle to the memory provider
ppMessage – [out] pointer to a string containing provider specific result in string representation
pError – [out] pointer to an integer where the adapter specific error code will be stored

umf_result_t umfMemoryProviderGetRecommendedPageSize(umf_memory_provider_handle_t hProvider, size_t size, size_t *pageSize)#

Retrieve recommended page size for a given allocation size.

Parameters:

hProvider – handle to the memory provider
size – allocation size
pageSize – [out] pointer to the recommended page size

Returns:

UMF_RESULT_SUCCESS on success or appropriate error code on failure.

umf_result_t umfMemoryProviderGetMinPageSize(umf_memory_provider_handle_t hProvider, void *ptr, size_t *pageSize)#

Retrieve minimum possible page size used by memory region referenced by a given ptr or minimum possible page size that can be used by the hProvider if ptr is NULL.

Parameters:

hProvider – handle to the memory provider
ptr – [optional] pointer to memory allocated by the memory hProvider
pageSize – [out] pointer to the minimum possible page size

Returns:

UMF_RESULT_SUCCESS on success or appropriate error code on failure.

umf_result_t umfMemoryProviderPurgeLazy(umf_memory_provider_handle_t hProvider, void *ptr, size_t size)#

Discard physical pages within the virtual memory mapping associated at the given addr and size. This call is asynchronous and may delay purging the pages indefinitely.

Parameters:

hProvider – handle to the memory provider
ptr – beginning of the virtual memory range
size – size of the virtual memory range

Returns:

UMF_RESULT_SUCCESS on success or appropriate error code on failure. UMF_RESULT_ERROR_INVALID_ALIGNMENT if ptr or size is not page-aligned. UMF_RESULT_ERROR_NOT_SUPPORTED if operation is not supported by this provider.

umf_result_t umfMemoryProviderPurgeForce(umf_memory_provider_handle_t hProvider, void *ptr, size_t size)#

Discard physical pages within the virtual memory mapping associated at the given addr and size. This call is synchronous and if it succeeds, pages are guaranteed to be zero-filled on the next access.

Parameters:

hProvider – handle to the memory provider
ptr – beginning of the virtual memory range
size – size of the virtual memory range

Returns:

UMF_RESULT_SUCCESS on success or appropriate error code on failure UMF_RESULT_ERROR_INVALID_ALIGNMENT if ptr or size is not page-aligned. UMF_RESULT_ERROR_NOT_SUPPORTED if operation is not supported by this provider.

umf_result_t umfMemoryProviderGetIPCHandleSize(umf_memory_provider_handle_t hProvider, size_t *size)#

Retrieve the size of opaque data structure required to store IPC data.

Parameters:

hProvider – [in] handle to the memory provider.
size – [out] pointer to the size.

Returns:

UMF_RESULT_SUCCESS on success or appropriate error code on failure. UMF_RESULT_ERROR_NOT_SUPPORTED if IPC functionality is not supported by this provider.

umf_result_t umfMemoryProviderGetIPCHandle(umf_memory_provider_handle_t hProvider, const void *ptr, size_t size, void *providerIpcData)#

Retrieve an IPC memory handle for the specified allocation.

Parameters:

hProvider – [in] handle to the memory provider.
ptr – [in] beginning of the virtual memory range returned by umfMemoryProviderAlloc function.
size – [in] size of the memory address range.
providerIpcData – [out] pointer to the preallocated opaque data structure to store IPC handle.

Returns:

UMF_RESULT_SUCCESS on success or appropriate error code on failure. UMF_RESULT_ERROR_INVALID_ARGUMENT if ptr was not allocated by this provider. UMF_RESULT_ERROR_NOT_SUPPORTED if IPC functionality is not supported by this provider.

umf_result_t umfMemoryProviderPutIPCHandle(umf_memory_provider_handle_t hProvider, void *providerIpcData)#

Release IPC handle retrieved with get_ipc_handle function.

Parameters:

hProvider – [in] handle to the memory provider.
providerIpcData – [in] pointer to the IPC opaque data structure.

Returns:

UMF_RESULT_SUCCESS on success or appropriate error code on failure. UMF_RESULT_ERROR_INVALID_ARGUMENT if providerIpcData was not created by this provider. UMF_RESULT_ERROR_NOT_SUPPORTED if IPC functionality is not supported by this provider.

umf_result_t umfMemoryProviderOpenIPCHandle(umf_memory_provider_handle_t hProvider, void *providerIpcData, void **ptr)#

Open IPC handle.

Parameters:

hProvider – [in] handle to the memory provider.
providerIpcData – [in] pointer to the IPC opaque data structure.
ptr – [out] pointer to the memory to be used in the current process.

Returns:

UMF_RESULT_SUCCESS on success or appropriate error code on failure. UMF_RESULT_ERROR_INVALID_ARGUMENT if providerIpcData cannot be handled by the provider. UMF_RESULT_ERROR_NOT_SUPPORTED if IPC functionality is not supported by this provider.

umf_result_t umfMemoryProviderCloseIPCHandle(umf_memory_provider_handle_t hProvider, void *ptr, size_t size)#

Close an IPC memory handle.

Parameters:

hProvider – [in] handle to the memory provider.
ptr – [in] pointer returned by umfMemoryProviderOpenIPCHandle function.
size – [in] size of the memory address range.

Returns:

UMF_RESULT_SUCCESS on success or appropriate error code on failure. UMF_RESULT_ERROR_INVALID_ARGUMENT if invalid hProvider or ptr are passed. UMF_RESULT_ERROR_NOT_SUPPORTED if IPC functionality is not supported by this provider.

const char *umfMemoryProviderGetName(umf_memory_provider_handle_t hProvider)#

Retrieve name of a given memory hProvider.

Parameters:

hProvider – handle to the memory provider

Returns:

pointer to a string containing the name of the hProvider

umf_memory_provider_handle_t umfGetLastFailedMemoryProvider(void)#

Retrieve handle to the last memory provider that returned status other than UMF_RESULT_SUCCESS on the calling thread.

Handle to the memory provider is stored in the thread local storage. The handle is updated every time a memory provider returns status other than UMF_RESULT_SUCCESS.

Returns:: Handle to the memory provider

umf_result_t umfMemoryProviderAllocationSplit(umf_memory_provider_handle_t hProvider, void *ptr, size_t totalSize, size_t firstSize)#

Splits a coarse grain allocation into 2 adjacent allocations that can be managed (freed) separately.

Parameters:

hProvider – handle to the memory provider
ptr – pointer to the beginning of the allocation
totalSize – total size of the allocation to be split
firstSize – size of the first new allocation, second allocation

Returns:

UMF_RESULT_SUCCESS on success or appropriate error code on failure

umf_result_t umfMemoryProviderAllocationMerge(umf_memory_provider_handle_t hProvider, void *lowPtr, void *highPtr, size_t totalSize)#

Merges two coarse grain allocations into a single allocation that can be managed (freed) as a whole.

Parameters:

hProvider – handle to the memory provider
lowPtr – pointer to the first allocation
highPtr – pointer to the second allocation (should be > lowPtr)
totalSize – size of a new merged allocation. Should be equal to the sum of sizes of allocations beginning at lowPtr and highPtr

Returns:

UMF_RESULT_SUCCESS on success or appropriate error code on failure

Coarse Provider#

A memory provider that can provide memory from:

A given pre-allocated buffer (the fixed-size memory provider option) or
From an additional upstream provider (e.g. provider that does not support the free() operation like the File memory provider or the DevDax memory provider - see below).

Enums

enum coarse_memory_provider_strategy_t#

Coarse Memory Provider allocation strategy.

Values:

enumerator UMF_COARSE_MEMORY_STRATEGY_FASTEST#: Always allocate a free block of the (size + alignment) size and cut out the properly aligned part leaving two remaining parts. It is the fastest strategy but causes memory fragmentation when alignment is greater than 0. It is the best strategy when alignment always equals 0.

enumerator UMF_COARSE_MEMORY_STRATEGY_FASTEST_BUT_ONE#: Check if the first free block of the ‘size’ size has the correct alignment. If not, use the UMF_COARSE_MEMORY_STRATEGY_FASTEST strategy.

enumerator UMF_COARSE_MEMORY_STRATEGY_CHECK_ALL_SIZE#: Look through all free blocks of the ‘size’ size and choose the first one with the correct alignment. If none of them had the correct alignment, use the UMF_COARSE_MEMORY_STRATEGY_FASTEST strategy.

enumerator UMF_COARSE_MEMORY_STRATEGY_MAX#: The maximum value (it has to be the last one).

Typedefs

typedef enum coarse_memory_provider_strategy_t coarse_memory_provider_strategy_t: Coarse Memory Provider allocation strategy.

typedef struct coarse_memory_provider_params_t coarse_memory_provider_params_t#: Coarse Memory Provider settings struct.

typedef struct coarse_memory_provider_stats_t coarse_memory_provider_stats_t#: Coarse Memory Provider stats (TODO move to CTL)

Functions

umf_memory_provider_ops_t *umfCoarseMemoryProviderOps(void)#

coarse_memory_provider_stats_t umfCoarseMemoryProviderGetStats(umf_memory_provider_handle_t provider)#

static inline coarse_memory_provider_params_t umfCoarseMemoryProviderParamsDefault(void)#: Create default params for the coarse memory provider.

OS Memory Provider#

A memory provider that provides memory from an operating system.

Enums

enum umf_numa_mode_t#

Memory binding mode Specifies how memory is bound to NUMA nodes on systems that support NUMA. Not every mode is supported on every system.

Values:

enumerator UMF_NUMA_MODE_DEFAULT#: Default binding mode. Actual binding policy is system-specific. On linux this corresponds to MPOL_DEFAULT. If this mode is specified, nodemask must be NULL and maxnode must be 0.

enumerator UMF_NUMA_MODE_BIND#: Restricts memory allocation to nodes specified in nodemask. Allocations might come from any of the allowed nodes. Nodemask must specify at

enumerator UMF_NUMA_MODE_INTERLEAVE#: Interleaves memory allocations across the set of nodes specified in nodemask. Nodemask must specify at least one node.

enumerator UMF_NUMA_MODE_PREFERRED#: Specifies preferred node for allocation. If allocation cannot be fulfilled, memory will be allocated from other nodes.

enumerator UMF_NUMA_MODE_SPLIT#: Allocation will be split evenly across nodes specified in nodemask. umf_numa_split_partition_t can be passed in umf_os_memory_provider_params_t structure to specify other distribution.

enumerator UMF_NUMA_MODE_LOCAL#: The memory is allocated on the node of the CPU that triggered the allocation. If this mode is specified, nodemask must be NULL and maxnode must be 0.

enum umf_os_memory_provider_native_error#

OS Memory Provider operation results.

Values:

enumerator UMF_OS_RESULT_SUCCESS#: Success.

enumerator UMF_OS_RESULT_ERROR_ALLOC_FAILED#: Memory allocation failed.

enumerator UMF_OS_RESULT_ERROR_ADDRESS_NOT_ALIGNED#: Allocated address is not aligned.

enumerator UMF_OS_RESULT_ERROR_BIND_FAILED#: Binding memory to NUMA node failed.

enumerator UMF_OS_RESULT_ERROR_FREE_FAILED#: Memory deallocation failed.

enumerator UMF_OS_RESULT_ERROR_PURGE_LAZY_FAILED#: Lazy purging failed.

enumerator UMF_OS_RESULT_ERROR_PURGE_FORCE_FAILED#: Force purging failed.

enumerator UMF_OS_RESULT_ERROR_TOPO_DISCOVERY_FAILED#: HWLOC topology discovery failed.

Typedefs

typedef enum umf_numa_mode_t umf_numa_mode_t: Memory binding mode Specifies how memory is bound to NUMA nodes on systems that support NUMA. Not every mode is supported on every system.

typedef struct umf_numa_split_partition_t umf_numa_split_partition_t#: This structure specifies a user-defined page distribution within a single allocation in UMF_NUMA_MODE_SPLIT mode.

typedef struct umf_os_memory_provider_params_t umf_os_memory_provider_params_t#: Memory provider settings struct.

typedef enum umf_os_memory_provider_native_error umf_os_memory_provider_native_error_t#: OS Memory Provider operation results.

Functions

umf_memory_provider_ops_t *umfOsMemoryProviderOps(void)#

static inline umf_os_memory_provider_params_t umfOsMemoryProviderParamsDefault(void)#: Create default params for os memory provider.

Level Zero Provider#

A memory provider that provides memory from L0 device.

Typedefs

typedef struct _ze_device_handle_t *ze_device_handle_t#

typedef struct _ze_context_handle_t *ze_context_handle_t#

typedef struct level_zero_memory_provider_params_t level_zero_memory_provider_params_t#: Level Zero Memory Provider settings struct.

Functions

umf_memory_provider_ops_t *umfLevelZeroMemoryProviderOps(void)#

DevDax Memory Provider#

A memory provider that provides memory from a device DAX (a character device file /dev/daxX.Y).

Enums

enum umf_devdax_memory_provider_native_error#

Devdax Memory Provider operation results.

Values:

enumerator UMF_DEVDAX_RESULT_SUCCESS#: Success.

enumerator UMF_DEVDAX_RESULT_ERROR_ALLOC_FAILED#: Memory allocation failed.

enumerator UMF_DEVDAX_RESULT_ERROR_ADDRESS_NOT_ALIGNED#: Allocated address is not aligned.

enumerator UMF_DEVDAX_RESULT_ERROR_FREE_FAILED#: Memory deallocation failed.

enumerator UMF_DEVDAX_RESULT_ERROR_PURGE_FORCE_FAILED#: Force purging failed.

Typedefs

typedef struct umf_devdax_memory_provider_params_t umf_devdax_memory_provider_params_t#: Memory provider settings struct.

typedef enum umf_devdax_memory_provider_native_error umf_devdax_memory_provider_native_error_t#: Devdax Memory Provider operation results.

Functions

umf_memory_provider_ops_t *umfDevDaxMemoryProviderOps(void)#

static inline umf_devdax_memory_provider_params_t umfDevDaxMemoryProviderParamsDefault(char *path, size_t size)#: Create default params for the devdax memory provider.

File Memory Provider#

A memory provider that provides memory by mapping a regular, extendable file.

Enums

enum umf_file_memory_provider_native_error#

File Memory Provider operation results.

Values:

enumerator UMF_FILE_RESULT_SUCCESS#: Success.

enumerator UMF_FILE_RESULT_ERROR_ALLOC_FAILED#: Memory allocation failed.

enumerator UMF_FILE_RESULT_ERROR_FREE_FAILED#: Memory deallocation failed.

enumerator UMF_FILE_RESULT_ERROR_PURGE_FORCE_FAILED#: Force purging failed.

Typedefs

typedef struct umf_file_memory_provider_params_t umf_file_memory_provider_params_t#: Memory provider settings struct.

typedef enum umf_file_memory_provider_native_error umf_file_memory_provider_native_error_t#: File Memory Provider operation results.

Functions

umf_memory_provider_ops_t *umfFileMemoryProviderOps(void)#

static inline umf_file_memory_provider_params_t umfFileMemoryProviderParamsDefault(const char *path)#: Create default params for the file memory provider.

Memspace#

TODO: Add general information about memspaces.

Memspace#

Typedefs

typedef struct umf_memspace_t *umf_memspace_handle_t#

typedef const struct umf_memspace_t *umf_const_memspace_handle_t#

typedef int (*umf_memspace_filter_func_t)(umf_const_memspace_handle_t hMemspace, umf_const_memtarget_handle_t hMemtarget, void *args)#

Custom filter function for umfMemspaceUserFilter.

Param hMemspace:: handle to memspace
Param hMemtarget:: handle to memory target
Param args:: user provided arguments
Return:: zero if hMemtarget should be removed from memspace, positive otherwise, and negative on error

Functions

umf_result_t umfPoolCreateFromMemspace(umf_const_memspace_handle_t hMemspace, umf_const_mempolicy_handle_t hPolicy, umf_memory_pool_handle_t *hPool)#

Creates new memory pool from memspace and policy.

Parameters:

hMemspace – handle to memspace
hPolicy – handle to policy
hPool – [out] handle to the newly created memory pool

Returns:

UMF_RESULT_SUCCESS on success or appropriate error code on failure.

umf_result_t umfMemoryProviderCreateFromMemspace(umf_const_memspace_handle_t hMemspace, umf_const_mempolicy_handle_t hPolicy, umf_memory_provider_handle_t *hProvider)#

Creates new memory provider from memspace and policy.

Parameters:

hMemspace – handle to memspace
hPolicy – handle to policy
hProvider – [out] handle to the newly created memory provider

Returns:

UMF_RESULT_SUCCESS on success or appropriate error code on failure.

umf_result_t umfMemspaceCreateFromNumaArray(unsigned *nodeIds, size_t numIds, umf_memspace_handle_t *hMemspace)#

Creates new memspace from array of NUMA node ids.

Parameters:

nodeIds – array of NUMA node ids
numIds – size of the array
hMemspace – [out] handle to the newly created memspace

Returns:

UMF_RESULT_SUCCESS on success or appropriate error code on failure.

void umfMemspaceDestroy(umf_memspace_handle_t hMemspace)#

Destroys memspace.

Parameters:

hMemspace – handle to memspace

umf_const_memspace_handle_t umfMemspaceHostAllGet(void)#

Retrieves predefined host all memspace.

Returns:: host all memspace handle on success or NULL on failure.

umf_const_memspace_handle_t umfMemspaceHighestCapacityGet(void)#

Retrieves predefined highest capacity memspace.

Returns:: highest capacity memspace handle on success or NULL on failure.

umf_const_memspace_handle_t umfMemspaceHighestBandwidthGet(void)#

Retrieves predefined highest bandwidth memspace.

Returns:: highest bandwidth memspace handle on success or NULL on failure (no HMAT support).

umf_const_memspace_handle_t umfMemspaceLowestLatencyGet(void)#

Retrieves predefined lowest latency memspace.

Returns:: lowest latency memspace handle on success or NULL on failure (no HMAT support).

umf_result_t umfMemspaceNew(umf_memspace_handle_t *hMemspace)#

Creates new empty memspace, which can be populated with umfMemspaceMemtargetAdd()

Parameters:

hMemspace – [out] handle to the newly created memspace

Returns:

UMF_RESULT_SUCCESS on success or appropriate error code on failure.

size_t umfMemspaceMemtargetNum(umf_const_memspace_handle_t hMemspace)#

Returns number of memory targets in memspace.

Parameters:

hMemspace – handle to memspace

Returns:

number of memory targets in memspace

umf_const_memtarget_handle_t umfMemspaceMemtargetGet(umf_const_memspace_handle_t hMemspace, unsigned targetNum)#

Returns memory target by index.

Parameters:

hMemspace – handle to memspace
targetNum – index of the memory target

Returns:

memory target handle on success or NULL on invalid input.

umf_result_t umfMemspaceMemtargetAdd(umf_memspace_handle_t hMemspace, umf_const_memtarget_handle_t hMemtarget)#

Adds memory target to memspace.

This function duplicates the memory target and then adds it to the memspace. This means that original memtarget handle and the handle of the duplicated memtarget are different and you cannot use it interchangeably. You can use umfMemspaceMemtargetGet() to retrieve new handle.

Parameters:

hMemspace – handle to memspace
hMemtarget – handle to memory target

Returns:

UMF_RESULT_SUCCESS on success or appropriate error code on failure.

umf_result_t umfMemspaceMemtargetRemove(umf_memspace_handle_t hMemspace, umf_const_memtarget_handle_t hMemtarget)#

Removes memory target from memspace.

Parameters:

hMemspace – handle to memspace
hMemtarget – handle to memory target

Returns:

UMF_RESULT_SUCCESS on success or appropriate error code on failure.

umf_result_t umfMemspaceClone(umf_const_memspace_handle_t hMemspace, umf_memspace_handle_t *hNewMemspace)#

Clones memspace.

Parameters:

hMemspace – handle to memspace
hNewMemspace – [out] handle to the newly created memspace

Returns:

UMF_RESULT_SUCCESS on success or appropriate error code on failure.

umf_result_t umfMemspaceFilterById(umf_memspace_handle_t hMemspace, unsigned *ids, size_t size)#

Removes all memory targets with non-matching numa node ids.

Parameters:

hMemspace – handle to memspace
ids – array of numa node ids
size – size of the array

Returns:

UMF_RESULT_SUCCESS on success or appropriate error code on failure. If the error code is UMF_RESULT_UNKNOWN the memspace is corrupted, otherwise the memspace is not modified.

umf_result_t umfMemspaceFilterByCapacity(umf_memspace_handle_t hMemspace, int64_t size)#

Filters out memory targets that capacity is less than specified size.

Negative values of size parameters are reserved for future extension of functionality of this function.

Parameters:

hMemspace – handle to memspace
size – minimum capacity of memory target

Returns:

UMF_RESULT_SUCCESS on success or appropriate error code on failure. If the error code is UMF_RESULT_UNKNOWN the memspace is corrupted, otherwise the memspace is not modified.

umf_result_t umfMemspaceUserFilter(umf_memspace_handle_t hMemspace, umf_memspace_filter_func_t filter, void *args)#

Filters out memory targets based on user provided function.

Parameters:

hMemspace – handle to memspace
filter – user provided function
args – user provided arguments

Returns:

UMF_RESULT_SUCCESS on success or appropriate error code on failure. If the error code is UMF_RESULT_UNKNOWN the memspace is corrupted, otherwise the memspace is not modified.

Mempolicy#

TODO: Add general information about mempolicies.

Mempolicy#

Enums

enum umf_mempolicy_membind_t#

Values:

enumerator UMF_MEMPOLICY_INTERLEAVE#: Interleave memory from all memory in memspace.

enumerator UMF_MEMPOLICY_BIND#: Bind memory to memspace.

enumerator UMF_MEMPOLICY_PREFERRED#: Prefer memory from memspace but fallback to other memory if not available.

enumerator UMF_MEMPOLICY_SPLIT#: Allocation will be split evenly across nodes specified in nodemask. umf_mempolicy_split_partition_t can be used to specify different distribution.

Typedefs

typedef struct umf_mempolicy_t *umf_mempolicy_handle_t#

typedef const struct umf_mempolicy_t *umf_const_mempolicy_handle_t#

typedef enum umf_mempolicy_membind_t umf_mempolicy_membind_t

typedef struct umf_mempolicy_split_partition_t umf_mempolicy_split_partition_t#: user defined partition for UMF_MEMPOLICY_SPLIT mode

Functions

umf_result_t umfMempolicyCreate(umf_mempolicy_membind_t bind, umf_mempolicy_handle_t *hPolicy)#

Creates a new memory policy.

Parameters:

bind – memory binding policy
hPolicy – [out] handle to the newly created memory policy

Returns:

UMF_RESULT_SUCCESS on success or appropriate error code on failure.

umf_result_t umfMempolicyDestroy(umf_mempolicy_handle_t hPolicy)#

Destroys memory policy.

Parameters:

hPolicy – handle to memory policy

Returns:

UMF_RESULT_SUCCESS on success or appropriate error code on failure.

umf_result_t umfMempolicySetInterleavePartSize(umf_mempolicy_handle_t hPolicy, size_t partSize)#

Sets custom part size for interleaved memory policy - by default it’s interleaved by pages.

Parameters:

hPolicy – handle to memory policy
partSize – size of the part or zero to use default part size (page size)

Returns:

UMF_RESULT_SUCCESS on success or appropriate error code on failure.

umf_result_t umfMempolicySetCustomSplitPartitions(umf_mempolicy_handle_t hPolicy, umf_mempolicy_split_partition_t *partList, size_t partListLen)#

Sets custom split partitions.

Parameters:

hPolicy – handle to memory policy
partList – ordered array of partitions
partListLen – length of the partList array

Returns:

UMF_RESULT_SUCCESS on success or appropriate error code on failure.

Memtarget#

TODO: Add general information about memtargets.

Memtarget#

Enums

enum umf_memtarget_type_t#

Values:

enumerator UMF_MEMTARGET_TYPE_UNKNOWN#

enumerator UMF_MEMTARGET_TYPE_NUMA#

Typedefs

typedef struct umf_memtarget_t *umf_memtarget_handle_t#

typedef const struct umf_memtarget_t *umf_const_memtarget_handle_t#

typedef enum umf_memtarget_type_t umf_memtarget_type_t

Functions

umf_result_t umfMemtargetGetType(umf_const_memtarget_handle_t hMemtarget, umf_memtarget_type_t *type)#

Gets the type of the memory target.

Parameters:

hMemtarget – handle to the memory target
type – [out] type of the memory target

Returns:

UMF_RESULT_SUCCESS on success or appropriate error code on failure.

umf_result_t umfMemtargetGetCapacity(umf_const_memtarget_handle_t hMemtarget, size_t *capacity)#

Get size of the memory target in bytes.

Parameters:

hMemtarget – handle to the memory target
capacity – [out] capacity of the memory target

Returns:

UMF_RESULT_SUCCESS on success or appropriate error code on failure.

umf_result_t umfMemtargetGetId(umf_const_memtarget_handle_t hMemtarget, unsigned *id)#

Get physical ID of the memory target.

Parameters:

hMemtarget – handle to the memory target
id – [out] id of the memory target

Returns:

UMF_RESULT_SUCCESS on success or appropriate error code on failure.

Inter-Process Communication#

IPC API allows retrieving IPC handles for the memory buffers allocated from UMF memory pools. The memory provider used by the pool should support IPC operations for this API to work. Otherwise IPC APIs return an error.

IPC API#

Typedefs

typedef struct umf_ipc_data_t *umf_ipc_handle_t#

Functions

umf_result_t umfPoolGetIPCHandleSize(umf_memory_pool_handle_t hPool, size_t *size)#

Returns the size of IPC handles for the specified pool.

Parameters:

hPool – [in] Pool handle
size – [out] size of IPC handle in bytes.

Returns:

UMF_RESULT_SUCCESS on success or appropriate error code on failure.

umf_result_t umfGetIPCHandle(const void *ptr, umf_ipc_handle_t *ipcHandle, size_t *size)#

Creates an IPC handle for the specified UMF allocation.

Parameters:

ptr – pointer to the allocated memory.
ipcHandle – [out] returned IPC handle.
size – [out] size of IPC handle in bytes.

Returns:

UMF_RESULT_SUCCESS on success or appropriate error code on failure.

umf_result_t umfPutIPCHandle(umf_ipc_handle_t ipcHandle)#

Release IPC handle retrieved by umfGetIPCHandle.

Parameters:

ipcHandle – IPC handle.

Returns:

UMF_RESULT_SUCCESS on success or appropriate error code on failure.

umf_result_t umfOpenIPCHandle(umf_memory_pool_handle_t hPool, umf_ipc_handle_t ipcHandle, void **ptr)#

Open IPC handle retrieved by umfGetIPCHandle.

Parameters:

hPool – [in] Pool handle where to open the the IPC handle.
ipcHandle – [in] IPC handle.
ptr – [out] pointer to the memory in the current process.

Returns:

UMF_RESULT_SUCCESS on success or appropriate error code on failure.

umf_result_t umfCloseIPCHandle(void *ptr)#

Close IPC handle.

Parameters:

ptr – [in] pointer to the memory.

Returns:

UMF_RESULT_SUCCESS on success or appropriate error code on failure.

API Documentation

Contents

API Documentation#

Globals#

Pools#

Memory Pool#

Disjoint Pool#

Jemalloc Pool#

Proxy Pool#

Scalable Pool#

Providers#

Memory Provider#

Coarse Provider#

OS Memory Provider#

Level Zero Provider#

DevDax Memory Provider#

File Memory Provider#

Memspace#

Memspace#

Mempolicy#

Mempolicy#

Memtarget#

Memtarget#

Inter-Process Communication#

IPC API#