API Documentation — Intel Unified Memory Framework 0.12.0 documentation (original) (raw)

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

External required dependency is unavailable or missing.

enumerator UMF_RESULT_ERROR_OUT_OF_RESOURCES#

Out of internal resources.

enumerator UMF_RESULT_ERROR_UNKNOWN#

Unknown error.

enum umf_ctl_query_type_t#

Type of the CTL query.

Values:

enumerator CTL_QUERY_READ#

enumerator CTL_QUERY_WRITE#

enumerator CTL_QUERY_RUNNABLE#

enumerator CTL_QUERY_SUBTREE#

enumerator MAX_CTL_QUERY_TYPE#

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 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, const 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, const 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/deallocation 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

umf_result_t umfPoolSetTag(umf_memory_pool_handle_t hPool, void *tag, void **oldTag)#

Set a custom tag on the memory pool that can be later retrieved using umfPoolGetTag.

Parameters:

• hPool – specified memory pool
• tag – tag to be set
• oldTag – [out][optional] previous tag set on the memory pool

Returns:

UMF_RESULT_SUCCESS on success or appropriate error code on failure.

umf_result_t umfPoolGetTag(umf_memory_pool_handle_t hPool, void **tag)#

Retrieve the tag associated with the memory pool or NULL if no tag is set.

Parameters:

• hPool – specified memory pool
• tag – [out] tag associated with the memory pool

Returns:

UMF_RESULT_SUCCESS on success.

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 to 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. Name longer than 64 characters will be truncated.

Returns:

UMF_RESULT_SUCCESS on success or appropriate error code on failure.

const 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 optional parameters of the jemalloc pool.

Functions

umf_result_t umfJemallocPoolParamsCreate(umf_jemalloc_pool_params_handle_t *hParams)#

Create an optional 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 umfJemallocPoolParamsSetNumArenas(umf_jemalloc_pool_params_handle_t hParams, size_t numArenas)#

Customize number of arenas created for this pool. Default is the number of CPU cores * 4.

The number of arenas is limited by jemalloc; setting this value too high may reduce the number of pools available for creation.

Parameters:

• hParams – handle to the parameters of the jemalloc pool.
• numArenas – number of arenas.

Returns:

UMF_RESULT_SUCCESS on success or appropriate error code on failure.

const 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

const umf_memory_pool_ops_t *umfProxyPoolOps(void)#

Scalable Pool#

A oneTBB-based memory pool manager.

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.

const 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 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, const 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, const 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

Fixed Memory Provider#

A memory provider that can provide memory from a given preallocated buffer.

Enums

enum umf_fixed_memory_provider_native_error_t#

Fixed Memory Provider operation results.

Values:

enumerator UMF_FIXED_RESULT_SUCCESS#

Success.

enumerator UMF_FIXED_RESULT_ERROR_PURGE_FORCE_FAILED#

Force purging failed.

Typedefs

typedef struct umf_fixed_memory_provider_params_t *umf_fixed_memory_provider_params_handle_t#

Functions

umf_result_t umfFixedMemoryProviderParamsCreate(umf_fixed_memory_provider_params_handle_t *hParams, void *ptr, size_t size)#

Create a struct to store parameters of the Fixed Memory Provider.

Parameters:

• hParams – [out] handle to the newly created parameters struct.
• ptr – [in] pointer to the memory region.
• size – [in] size of the memory region in bytes.

Returns:

UMF_RESULT_SUCCESS on success or appropriate error code on failure.

umf_result_t umfFixedMemoryProviderParamsSetMemory(umf_fixed_memory_provider_params_handle_t hParams, void *ptr, size_t size)#

Set the memory region in params struct. Overwrites the previous value. It provides an ability to use the same instance of params to create multiple instances of the provider for different memory regions.

Parameters:

• hParams – [in] handle to the parameters of the Fixed Memory Provider.
• ptr – [in] pointer to the memory region.
• size – [in] size of the memory region in bytes.

Returns:

UMF_RESULT_SUCCESS on success or appropriate error code on failure.

umf_result_t umfFixedMemoryProviderParamsDestroy(umf_fixed_memory_provider_params_handle_t hParams)#

Destroy parameters struct.

Parameters:

• hParams – [in] handle to the parameters of the Fixed Memory Provider.

Returns:

UMF_RESULT_SUCCESS on success or appropriate error code on failure.

const umf_memory_provider_ops_t *umfFixedMemoryProviderOps(void)#

Retrieve the operations structure for the Fixed Memory Provider.

Returns:

Pointer to the umf_memory_provider_ops_t structure.

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

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 struct umf_os_memory_provider_params_t *umf_os_memory_provider_params_handle_t#

Functions

umf_result_t umfOsMemoryProviderParamsCreate(umf_os_memory_provider_params_handle_t *hParams)#

Create a struct to store parameters of the OS memory provider.

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 umfOsMemoryProviderParamsDestroy(umf_os_memory_provider_params_handle_t hParams)#

Destroy parameters struct.

Parameters:

• hParams – handle to the parameters of the OS memory provider.

Returns:

UMF_RESULT_SUCCESS on success or appropriate error code on failure.

umf_result_t umfOsMemoryProviderParamsSetProtection(umf_os_memory_provider_params_handle_t hParams, unsigned protection)#

Set protection flags for the OS memory provider.

Parameters:

• hParams – handle to the parameters of the OS memory provider.
• protection – combination of umf_mem_protection_flags_t flags.

Returns:

UMF_RESULT_SUCCESS on success or appropriate error code on failure.

umf_result_t umfOsMemoryProviderParamsSetVisibility(umf_os_memory_provider_params_handle_t hParams, umf_memory_visibility_t visibility)#

Set visibility mode for the OS memory provider.

Parameters:

• hParams – handle to the parameters of the OS memory provider.
• visibility – memory visibility mode.

Returns:

UMF_RESULT_SUCCESS on success or appropriate error code on failure.

umf_result_t umfOsMemoryProviderParamsSetShmName(umf_os_memory_provider_params_handle_t hParams, const char *shm_name)#

Set a name of a shared memory file for the OS memory provider.

Parameters:

• hParams – handle to the parameters of the OS memory provider.
• shm_name – a name of a shared memory file.

Returns:

UMF_RESULT_SUCCESS on success or appropriate error code on failure.

umf_result_t umfOsMemoryProviderParamsSetNumaList(umf_os_memory_provider_params_handle_t hParams, unsigned *numa_list, unsigned numa_list_len)#

Set NUMA nodes for the OS memory provider.

Parameters:

• hParams – handle to the parameters of the OS memory provider.
• numa_list – ordered list of NUMA nodes.
• numa_list_len – length of the numa_list.

Returns:

UMF_RESULT_SUCCESS on success or appropriate error code on failure.

umf_result_t umfOsMemoryProviderParamsSetNumaMode(umf_os_memory_provider_params_handle_t hParams, umf_numa_mode_t numa_mode)#

Set NUMA mode for the OS memory provider.

Parameters:

• hParams – handle to the parameters of the OS memory provider.
• numa_mode – NUMA mode. Describes how node list is interpreted.

Returns:

UMF_RESULT_SUCCESS on success or appropriate error code on failure.

umf_result_t umfOsMemoryProviderParamsSetPartSize(umf_os_memory_provider_params_handle_t hParams, size_t part_size)#

Set part size for the interleave mode. 0 means default (system specific) It might be rounded up because of HW constraints.

Parameters:

• hParams – handle to the parameters of the OS memory provider.
• part_size – part size for interleave mode.

Returns:

UMF_RESULT_SUCCESS on success or appropriate error code on failure.

umf_result_t umfOsMemoryProviderParamsSetPartitions(umf_os_memory_provider_params_handle_t hParams, umf_numa_split_partition_t *partitions, unsigned partitions_len)#

Set partitions for the split mode.

Parameters:

• hParams – handle to the parameters of the OS memory provider.
• partitions – ordered list of the partitions for the split mode.
• partitions_len – length of the partitions array.

Returns:

UMF_RESULT_SUCCESS on success or appropriate error code on failure.

const umf_memory_provider_ops_t *umfOsMemoryProviderOps(void)#

Level Zero Provider#

A memory provider that provides memory from L0 device.

Enums

enum umf_level_zero_memory_provider_free_policy_t#

Values:

enumerator UMF_LEVEL_ZERO_MEMORY_PROVIDER_FREE_POLICY_DEFAULT#

Free memory immediately. Default.

enumerator UMF_LEVEL_ZERO_MEMORY_PROVIDER_FREE_POLICY_BLOCKING_FREE#

Blocks until all commands using the memory are complete before freeing.

enumerator UMF_LEVEL_ZERO_MEMORY_PROVIDER_FREE_POLICY_DEFER_FREE#

Schedules the memory to be freed but does not free immediately.

Typedefs

typedef struct _ze_device_handle_t *ze_device_handle_t#

typedef struct _ze_context_handle_t *ze_context_handle_t#

typedef struct umf_level_zero_memory_provider_params_t *umf_level_zero_memory_provider_params_handle_t#

handle to the parameters of the Level Zero Memory Provider.

Functions

umf_result_t umfLevelZeroMemoryProviderParamsCreate(umf_level_zero_memory_provider_params_handle_t *hParams)#

Create a struct to store parameters of the Level Zero Memory Provider.

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 umfLevelZeroMemoryProviderParamsDestroy(umf_level_zero_memory_provider_params_handle_t hParams)#

Destroy parameters struct.

Parameters:

• hParams – handle to the parameters of the Level Zero Memory Provider.

Returns:

UMF_RESULT_SUCCESS on success or appropriate error code on failure.

umf_result_t umfLevelZeroMemoryProviderParamsSetContext(umf_level_zero_memory_provider_params_handle_t hParams, ze_context_handle_t hContext)#

Set the Level Zero context handle in the parameters struct.

Parameters:

• hParams – handle to the parameters of the Level Zero Memory Provider.
• hContext – handle to the Level Zero context. Cannot be NULL.

Returns:

UMF_RESULT_SUCCESS on success or appropriate error code on failure.

umf_result_t umfLevelZeroMemoryProviderParamsSetDevice(umf_level_zero_memory_provider_params_handle_t hParams, ze_device_handle_t hDevice)#

Set the Level Zero device handle in the parameters struct.

Parameters:

• hParams – handle to the parameters of the Level Zero Memory Provider.
• hDevice – handle to the Level Zero device. Can be NULL if memory type is UMF_MEMORY_TYPE_HOST.

Returns:

UMF_RESULT_SUCCESS on success or appropriate error code on failure.

umf_result_t umfLevelZeroMemoryProviderParamsSetMemoryType(umf_level_zero_memory_provider_params_handle_t hParams, umf_usm_memory_type_t memoryType)#

Set the memory type in the parameters struct.

Parameters:

• hParams – handle to the parameters of the Level Zero Memory Provider.
• memoryType – memory type.

Returns:

UMF_RESULT_SUCCESS on success or appropriate error code on failure.

umf_result_t umfLevelZeroMemoryProviderParamsSetResidentDevices(umf_level_zero_memory_provider_params_handle_t hParams, ze_device_handle_t *hDevices, uint32_t deviceCount)#

Set the resident devices in the parameters struct.

Parameters:

• hParams – handle to the parameters of the Level Zero Memory Provider.
• hDevices – array of devices for which the memory should be made resident.
• deviceCount – number of devices for which the memory should be made resident.

Returns:

UMF_RESULT_SUCCESS on success or appropriate error code on failure.

umf_result_t umfLevelZeroMemoryProviderParamsSetFreePolicy(umf_level_zero_memory_provider_params_handle_t hParams, umf_level_zero_memory_provider_free_policy_t policy)#

Set the memory free policy.

Parameters:

• hParams – handle to the parameters of the Level Zero Memory Provider.
• policy – memory free policy.

Returns:

UMF_RESULT_SUCCESS on success or appropriate error code on failure.

umf_result_t umfLevelZeroMemoryProviderParamsSetDeviceOrdinal(umf_level_zero_memory_provider_params_handle_t hParams, uint32_t deviceOrdinal)#

Set the device ordinal in the parameters struct.

Parameters:

• hParams – handle to the parameters of the Level Zero Memory Provider.
• deviceOrdinal – device ordinal.

Returns:

UMF_RESULT_SUCCESS on success or appropriate error code on failure.

const umf_memory_provider_ops_t *umfLevelZeroMemoryProviderOps(void)#

CUDA Provider#

A memory provider that provides memory from CUDA device.

Typedefs

typedef struct umf_cuda_memory_provider_params_t *umf_cuda_memory_provider_params_handle_t#

Functions

umf_result_t umfCUDAMemoryProviderParamsCreate(umf_cuda_memory_provider_params_handle_t *hParams)#

Create a struct to store parameters of the CUDA Memory Provider.

Parameters:

• hParams – [out] handle to the newly created parameters structure, initialized with the default (current) context and device ID.

Returns:

UMF_RESULT_SUCCESS on success or appropriate error code on failure.

umf_result_t umfCUDAMemoryProviderParamsDestroy(umf_cuda_memory_provider_params_handle_t hParams)#

Destroy parameters struct.

Parameters:

• hParams – handle to the parameters of the CUDA Memory Provider.

Returns:

UMF_RESULT_SUCCESS on success or appropriate error code on failure.

umf_result_t umfCUDAMemoryProviderParamsSetContext(umf_cuda_memory_provider_params_handle_t hParams, void *hContext)#

Set the CUDA context handle in the parameters struct.

Parameters:

• hParams – handle to the parameters of the CUDA Memory Provider.
• hContext – handle to the CUDA context.

Returns:

UMF_RESULT_SUCCESS on success or appropriate error code on failure.

umf_result_t umfCUDAMemoryProviderParamsSetDevice(umf_cuda_memory_provider_params_handle_t hParams, int hDevice)#

Set the CUDA device handle in the parameters struct.

Parameters:

• hParams – handle to the parameters of the CUDA Memory Provider.
• hDevice – handle to the CUDA device.

Returns:

UMF_RESULT_SUCCESS on success or appropriate error code on failure.

umf_result_t umfCUDAMemoryProviderParamsSetMemoryType(umf_cuda_memory_provider_params_handle_t hParams, umf_usm_memory_type_t memoryType)#

Set the memory type in the parameters struct.

Parameters:

• hParams – handle to the parameters of the CUDA Memory Provider.
• memoryType – memory type.

Returns:

UMF_RESULT_SUCCESS on success or appropriate error code on failure.

umf_result_t umfCUDAMemoryProviderParamsSetAllocFlags(umf_cuda_memory_provider_params_handle_t hParams, unsigned int flags)#

Set the allocation flags in the parameters struct.

Parameters:

• hParams – handle to the parameters of the CUDA Memory Provider.
• flags – valid combination of CUDA allocation flags.

Returns:

UMF_RESULT_SUCCESS on success or appropriate error code on failure.

const umf_memory_provider_ops_t *umfCUDAMemoryProviderOps(void)#

DevDax Memory Provider#

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

Enums

enum umf_devdax_memory_provider_native_error_t#

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

Functions

umf_result_t umfDevDaxMemoryProviderParamsCreate(umf_devdax_memory_provider_params_handle_t *hParams, const char *path, size_t size)#

Create a struct to store parameters of the Devdax Memory Provider.

Parameters:

• hParams – [out] handle to the newly created parameters struct.
• path – [in] path of the device DAX.
• size – [in] size of the device DAX in bytes.

Returns:

UMF_RESULT_SUCCESS on success or appropriate error code on failure.

umf_result_t umfDevDaxMemoryProviderParamsDestroy(umf_devdax_memory_provider_params_handle_t hParams)#

Destroy parameters struct.

Parameters:

• hParams – [in] handle to the parameters of the Devdax Memory Provider.

Returns:

UMF_RESULT_SUCCESS on success or appropriate error code on failure.

umf_result_t umfDevDaxMemoryProviderParamsSetDeviceDax(umf_devdax_memory_provider_params_handle_t hParams, const char *path, size_t size)#

Set a device DAX in the parameters struct. Overwrites the previous value. It provides an ability to use the same instance of params to create multiple instances of the provider for different DAX devices.

Parameters:

• hParams – [in] handle to the parameters of the Devdax Memory Provider.
• path – [in] path of the device DAX.
• size – [in] size of the device DAX in bytes.

Returns:

UMF_RESULT_SUCCESS on success or appropriate error code on failure.

umf_result_t umfDevDaxMemoryProviderParamsSetProtection(umf_devdax_memory_provider_params_handle_t hParams, unsigned protection)#

Set the protection flags in the parameters struct.

Parameters:

• hParams – [in] handle to the parameters of the Devdax Memory Provider.
• protection – [in] combination of ‘umf_mem_protection_flags_t’ flags.

Returns:

UMF_RESULT_SUCCESS on success or appropriate error code on failure.

const umf_memory_provider_ops_t *umfDevDaxMemoryProviderOps(void)#

File Memory Provider#

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

Enums

enum umf_file_memory_provider_native_error_t#

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

Functions

umf_result_t umfFileMemoryProviderParamsCreate(umf_file_memory_provider_params_handle_t *hParams, const char *path)#

Create a struct to store parameters of the File Memory Provider.

Parameters:

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

Returns:

UMF_RESULT_SUCCESS on success or appropriate error code on failure.

umf_result_t umfFileMemoryProviderParamsDestroy(umf_file_memory_provider_params_handle_t hParams)#

Destroy parameters struct.

Parameters:

• hParams – handle to the parameters of the File Memory Provider.

Returns:

UMF_RESULT_SUCCESS on success or appropriate error code on failure.

umf_result_t umfFileMemoryProviderParamsSetPath(umf_file_memory_provider_params_handle_t hParams, const char *path)#

Set the path in the parameters struct.

Parameters:

• hParams – handle to the parameters of the File Memory Provider.
• path – path to the file.

Returns:

UMF_RESULT_SUCCESS on success or appropriate error code on failure.

umf_result_t umfFileMemoryProviderParamsSetProtection(umf_file_memory_provider_params_handle_t hParams, unsigned protection)#

Set the protection in the parameters struct.

Parameters:

• hParams – handle to the parameters of the File Memory Provider.
• protection – protection. Combination of umf_mem_protection_flags_t flags

Returns:

UMF_RESULT_SUCCESS on success or appropriate error code on failure.

umf_result_t umfFileMemoryProviderParamsSetVisibility(umf_file_memory_provider_params_handle_t hParams, umf_memory_visibility_t visibility)#

Set the visibility in the parameters struct.

Parameters:

• hParams – handle to the parameters of the File Memory Provider.
• visibility – memory visibility mode.

Returns:

UMF_RESULT_SUCCESS on success or appropriate error code on failure.

const umf_memory_provider_ops_t *umfFileMemoryProviderOps(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#

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#

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#

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

UMF employs IPC caching to avoid multiple IPC handles being created for the same coarse-grain memory region allocated by the memory provider. UMF guarantees that for each coarse-grain memory region allocated by the memory provider, only one IPC handle is created when the umfGetIPCHandle function is called. All subsequent calls to the umfGetIPCHandle function for the pointer to the same memory region will return the entry from the cache.

The same is true for the umfOpenIPCHandle function. The actual mapping of the IPC handle to the virtual address space is created only once, and all subsequent calls to open the same IPC handle will return the entry from the cache. The size of the cache for opened IPC handles is controlled by the UMF_MAX_OPENED_IPC_HANDLESenvironment variable. By default, the cache size is unlimited. However, if the environment variable is set and the cache size exceeds the limit, old items will be evicted. UMF tracks the ref count for each entry in the cache and can evict only items with the ref count equal to 0. The ref count is increased when the umfOpenIPCHandle function is called and decreased when the umfCloseIPCHandle function is called for the corresponding IPC handle.

IPC API#

Typedefs

typedef struct umf_ipc_data_t *umf_ipc_handle_t#

typedef void *umf_ipc_handler_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_ipc_handler_handle_t hIPCHandler, umf_ipc_handle_t ipcHandle, void **ptr)#

Open IPC handle retrieved by umfGetIPCHandle.

Parameters:

• hIPCHandler – [in] IPC Handler handle used to open 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.

umf_result_t umfPoolGetIPCHandler(umf_memory_pool_handle_t hPool, umf_ipc_handler_handle_t *hIPCHandler)#

Get handle to the IPC handler from existing pool.

Parameters:

• hPool – [in] Pool handle
• hIPCHandler – [out] handle to the IPC handler

Returns:

UMF_RESULT_SUCCESS on success or appropriate error code on failure.