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_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_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_t#

Configuration of Disjoint Pool.

Functions

umf_disjoint_pool_shared_limits_t *umfDisjointPoolSharedLimitsCreate(size_t MaxSize)#

Create a pool limits struct.

Parameters

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

Returns

pointer to created pool limits struct

void umfDisjointPoolSharedLimitsDestroy(umf_disjoint_pool_shared_limits_t *PoolLimits)#

Destroy previously created pool limits struct.

Parameters

  • PoolLimits – pointer to a pool limits struct

umf_memory_pool_ops_t *umfDisjointPoolOps(void)#
static inline umf_disjoint_pool_params_t umfDisjointPoolParamsDefault(void)#

Create default params struct for disjoint pool.

Jemalloc Pool#

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

Functions

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#

Functions

umf_memory_pool_ops_t *umfScalablePoolOps(void)#

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.

Typedefs

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

OS Memory Provider#

A memory provider that provides memory from an operating system.

Enums

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.

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 (supported on Linux only)

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_mem_protection_flags_t umf_mem_protection_flags_t

Protection of the memory allocations.

typedef enum umf_memory_visibility_t umf_memory_visibility_t

Memory visibility mode.

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.

Enums

enum umf_usm_memory_type_t#

USM memory allocation type.

Values:

enumerator UMF_MEMORY_TYPE_UNKNOWN#

The memory pointed to is of unknown type.

enumerator UMF_MEMORY_TYPE_HOST#

The memory pointed to is a host allocation.

enumerator UMF_MEMORY_TYPE_DEVICE#

The memory pointed to is a device allocation.

enumerator UMF_MEMORY_TYPE_SHARED#

The memory pointed to is a shared ownership allocation.

Typedefs

typedef enum umf_usm_memory_type_t umf_usm_memory_type_t

USM memory allocation type.

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)#

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#

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).

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.

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.