.. _experimental-async-allocations: ================================================================================ Async Allocation Functions ================================================================================ .. warning:: Experimental features: * May be replaced, updated, or removed at any time. * Do not require maintaining API/ABI stability of their own additions over time. * Do not require conformance testing of their own additions. Motivation -------------------------------------------------------------------------------- Asynchronous allocations can allow queues to allocate and free memory between UR command enqueues without forcing synchronization points in the asynchronous command DAG associated with a queue. Through the enqueue-ordering semantics, memory allocated within a pool can be reused so as to avoid expensive and redundant calls into the OS, which can improve performance. API -------------------------------------------------------------------------------- Enums ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ * :ref:`ur-device-info-t` * :ref:`UR_DEVICE_INFO_ASYNC_USM_ALLOCATIONS_SUPPORT_EXP ` * :ref:`ur-usm-pool-flags-t` * :ref:`UR_USM_POOL_FLAG_USE_NATIVE_MEMORY_POOL_EXP ` * :ref:`UR_USM_POOL_FLAG_READ_ONLY_EXP ` * :ref:`ur-usm-pool-info-t` * :ref:`UR_USM_POOL_INFO_RELEASE_THRESHOLD_EXP ` * :ref:`UR_USM_POOL_INFO_MAXIMUM_SIZE_EXP ` * :ref:`UR_USM_POOL_INFO_RESERVED_CURRENT_EXP ` * :ref:`UR_USM_POOL_INFO_RESERVED_HIGH_EXP ` * :ref:`UR_USM_POOL_INFO_USED_CURRENT_EXP ` * :ref:`UR_USM_POOL_INFO_USED_HIGH_EXP ` * :ref:`ur-command-t` * :ref:`UR_COMMAND_ENQUEUE_USM_DEVICE_ALLOC_EXP ` * :ref:`UR_COMMAND_ENQUEUE_USM_SHARED_ALLOC_EXP ` * :ref:`UR_COMMAND_ENQUEUE_USM_HOST_ALLOC_EXP ` * :ref:`UR_COMMAND_ENQUEUE_USM_FREE_EXP ` * :ref:`ur-structure-type-t` * :ref:`UR_STRUCTURE_TYPE_EXP_ASYNC_USM_ALLOC_PROPERTIES ` * :ref:`ur-exp-async-usm-alloc-flags-t` Types ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ * :ref:`ur-exp-async-usm-alloc-properties-t` * :ref:`ur-usm-pool-buffer-desc-t` Functions ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ * :ref:`urEnqueueUSMDeviceAllocExp` * :ref:`urEnqueueUSMSharedAllocExp` * :ref:`urEnqueueUSMHostAllocExp` * :ref:`urEnqueueUSMFreeExp` * :ref:`urUSMPoolCreateExp` * :ref:`urUSMPoolDestroyExp` * :ref:`urUSMPoolGetDefaultDevicePoolExp` * :ref:`urUSMPoolGetInfoExp` * :ref:`urUSMPoolSetInfoExp` * :ref:`urUSMPoolSetDevicePoolExp` * :ref:`urUSMPoolGetDevicePoolExp` * :ref:`urUSMPoolTrimToExp` Changelog -------------------------------------------------------------------------------- +----------+----------------------------------------------------------+ | Revision | Changes | +==========+==========================================================+ | 1.0 | Initial Draft | +----------+----------------------------------------------------------+ | 1.1 | Fix typos/warnings/descriptions | | | Change enum values | | | Add missing properties/enums/funcs to API list | +----------+----------------------------------------------------------+ | 1.2 | Rename DEVICE_INFO_ASYNC_USM_ALLOCATIONS_EXP to | | | DEVICE_INFO_ASYNC_USM_ALLOCATIONS_SUPPORT_EXP for | | | better consistency with other UR enums | +----------+----------------------------------------------------------+ | 1.3 | Remove USMPoolSetThresholdExp | | | Replace with USMPoolSetInfoExp | +----------+----------------------------------------------------------+ | 1.4 | Introduce usm_pool_buffer_desc_t to enable pool | | | creation from a USM memory object | +----------+----------------------------------------------------------+ Support -------------------------------------------------------------------------------- Adapters which support this experimental feature *must* return true for the new ``:ref:`UR_DEVICE_INFO_ASYNC_USM_ALLOCATIONS_SUPPORT_EXP `\`` device info query. Contributors -------------------------------------------------------------------------------- * Hugh Delaney `hugh.delaney@codeplay.com `_ * Sean Stirling `sean.stirling@codeplay.com `_ * Krzysztof Swiecicki `krzysztof.swiecicki@intel.com `_