Event Pool

Event Pool#

oneAPI Level Zero Specification - Version 1.18.31

Event Pool Functions#

zeEventPoolCreate#

Added in version 1.0

ZE_APIEXPORT ze_result_t ZE_APICALL zeEventPoolCreate(ze_context_handle_t hContext, const ze_event_pool_desc_t *desc, uint32_t numDevices, ze_device_handle_t *phDevices, ze_event_pool_handle_t *phEventPool)#

Creates a pool of events on the context.

  • The application must only use events within the pool for the device(s), or their sub-devices, which were provided during creation.

  • The application may call this function from simultaneous threads.

  • The implementation of this function must be thread-safe.

Parameters:

  • hContext – [in] handle of the context object

  • desc – [in] pointer to event pool descriptor

  • numDevices – [in][optional] number of device handles; must be 0 if nullptr == phDevices

  • phDevices – [in][optional][range(0, numDevices)] array of device handles which have visibility to the event pool. if nullptr, then event pool is visible to all devices supported by the driver instance.

  • phEventPool – [out] pointer handle of event pool object created

Returns:

zeEventPoolDestroy#

Added in version 1.0

ZE_APIEXPORT ze_result_t ZE_APICALL zeEventPoolDestroy(ze_event_pool_handle_t hEventPool)#

Deletes an event pool object.

  • The application must destroy all event handles created from the pool before destroying the pool itself.

  • The application must ensure the device is not currently referencing the any event within the pool before it is deleted.

  • The implementation of this function may immediately free all Host and Device allocations associated with this event pool.

  • The application must not call this function from simultaneous threads with the same event pool handle.

  • The implementation of this function must be thread-safe.

Parameters:

hEventPool – [in][release] handle of event pool object to destroy

Returns:

zeEventPoolGetIpcHandle#

Added in version 1.0

ZE_APIEXPORT ze_result_t ZE_APICALL zeEventPoolGetIpcHandle(ze_event_pool_handle_t hEventPool, ze_ipc_event_pool_handle_t *phIpc)#

Gets an IPC event pool handle for the specified event handle that can be shared with another process.

  • Event pool must have been created with ZE_EVENT_POOL_FLAG_IPC.

  • The application may call this function from simultaneous threads.

Parameters:

  • hEventPool – [in] handle of event pool object

  • phIpc – [out] Returned IPC event handle

Returns:

zeEventPoolOpenIpcHandle#

Added in version 1.0

ZE_APIEXPORT ze_result_t ZE_APICALL zeEventPoolOpenIpcHandle(ze_context_handle_t hContext, ze_ipc_event_pool_handle_t hIpc, ze_event_pool_handle_t *phEventPool)#

Opens an IPC event pool handle to retrieve an event pool handle from another process.

  • Multiple calls to this function with the same IPC handle will return unique event pool handles.

  • The event handle in this process should not be freed with zeEventPoolDestroy, but rather with zeEventPoolCloseIpcHandle.

  • If the original event pool has been created for a device containing a number of sub-devices, then the event pool returned by this call may be used on a device containing the same number of sub-devices, or on any of those sub-devices.

  • However, if the original event pool has been created for a sub-device, then the event pool returned by this call cannot be used on a device containing any number of sub-devices, and must be used only in a sub-device. This ensures functional correctness for any implementation or optimizations the underlying Level Zero driver may do on event pools and events.

  • The application may call this function from simultaneous threads.

Parameters:

  • hContext – [in] handle of the context object to associate with the IPC event pool handle

  • hIpc – [in] IPC event pool handle

  • phEventPool – [out] pointer handle of event pool object created

Returns:

zeEventPoolCloseIpcHandle#

Added in version 1.0

ZE_APIEXPORT ze_result_t ZE_APICALL zeEventPoolCloseIpcHandle(ze_event_pool_handle_t hEventPool)#

Closes an IPC event handle in the current process.

  • Closes an IPC event handle by destroying events that were opened in this process using zeEventPoolOpenIpcHandle.

  • The application must not call this function from simultaneous threads with the same event pool handle.

Parameters:

hEventPool – [in][release] handle of event pool object

Returns:

zeEventPoolPutIpcHandle#

Added in version 1.6

ZE_APIEXPORT ze_result_t ZE_APICALL zeEventPoolPutIpcHandle(ze_context_handle_t hContext, ze_ipc_event_pool_handle_t hIpc)#

Returns an IPC event pool handle to the driver.

  • This call must be used for IPC handles previously obtained with zeEventPoolGetIpcHandle.

  • Upon call, driver may release any underlying resources associated with the IPC handle. For instance, it may close the file descriptor contained in the IPC handle, if such type of handle is being used by the driver.

  • This call does not destroy the original event pool for which the IPC handle was created.

  • This function may not be called from simultaneous threads with the same IPC handle.

  • The implementation of this function should be lock-free.

Parameters:

  • hContext – [in] handle of the context object associated with the IPC event pool handle

  • hIpc – [in] IPC event pool handle

Returns:

zeEventPoolGetContextHandle#

Added in version 1.9

ZE_APIEXPORT ze_result_t ZE_APICALL zeEventPoolGetContextHandle(ze_event_pool_handle_t hEventPool, ze_context_handle_t *phContext)#

Gets the handle of the context on which the event pool was created.

  • The application may call this function from simultaneous threads.

  • The implementation of this function should be lock-free.

Parameters:

  • hEventPool – [in] handle of the event pool

  • phContext – [out] handle of the context on which the event pool was created

Returns:

zeEventPoolGetFlags#

Added in version 1.9

ZE_APIEXPORT ze_result_t ZE_APICALL zeEventPoolGetFlags(ze_event_pool_handle_t hEventPool, ze_event_pool_flags_t *pFlags)#

Gets the creation flags used to create the event pool.

  • The application may call this function from simultaneous threads.

  • The implementation of this function should be lock-free.

Parameters:

  • hEventPool – [in] handle of the event pool

  • pFlags – [out] creation flags used to create the event pool; may be 0 or a valid combination of ze_event_pool_flag_t

Returns:

Event Pool Enums#

ze_event_pool_flags_t#

Added in version 1.0

enum ze_event_pool_flag_t#

Values:

enumerator ZE_EVENT_POOL_FLAG_HOST_VISIBLE#

signals and waits are also visible to host

enumerator ZE_EVENT_POOL_FLAG_IPC#

signals and waits may be shared across processes

enumerator ZE_EVENT_POOL_FLAG_KERNEL_TIMESTAMP#

Indicates all events in pool will contain kernel timestamps.

enumerator ZE_EVENT_POOL_FLAG_KERNEL_MAPPED_TIMESTAMP#

Indicates all events in pool will contain kernel timestamps synchronized to host time domain; cannot be combined with ZE_EVENT_POOL_FLAG_KERNEL_TIMESTAMP (since v1.6)

enumerator ZE_EVENT_POOL_FLAG_FORCE_UINT32#

Value marking end of ZE_EVENT_POOL_FLAG_* ENUMs.

Event Pool Structures#

ze_event_pool_desc_t#

Added in version 1.0

struct ze_event_pool_desc_t#

Event pool descriptor.

Public Members

ze_structure_type_t stype#

[in] type of this structure

const void *pNext#

[in][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).

ze_event_pool_flags_t flags#

[in] creation flags. must be 0 (default) or a valid combination of ze_event_pool_flag_t; default behavior is signals and waits are visible to the entire device and peer devices.

uint32_t count#

[in] number of events within the pool; must be greater than 0