C Specification

To return information about an event object, call the function

cl_int clGetEventInfo(
    cl_event event,
    cl_event_info param_name,
    size_t param_value_size,
    void* param_value,
    size_t* param_value_size_ret);

Parameters

  • event specifies the event object being queried.

  • param_name specifies the information to query. The list of supported param_name types and the information returned in param_value by clGetEventInfo is described in the Event Object Queries table.

  • param_value is a pointer to memory where the appropriate result being queried is returned. If param_value is NULL, it is ignored.

  • param_value_size is used to specify the size in bytes of memory pointed to by param_value. This size must be ≥ size of return type as described in the Event Object Queries table.

  • param_value_size_ret returns the actual size in bytes of data being queried by param_name. If param_value_size_ret is NULL, it is ignored.

Description

Table 1. List of supported param_names by clGetEventInfo
Event Info Return Type Description

CL_EVENT_COMMAND_QUEUE

cl_command_queue

Return the command-queue associated with event. For user event objects, a NULL value is returned.

CL_EVENT_CONTEXT

missing before version 1.1.

cl_context

Return the context associated with event.

CL_EVENT_COMMAND_TYPE

cl_command_type

Return the command type associated with event as described in the Event Command Types table.

CL_EVENT_COMMAND_EXECUTION_STATUS [1]

cl_int

Return the execution status of the command identified by event. Valid values are:

CL_QUEUED (command has been enqueued in the command-queue),

CL_SUBMITTED (enqueued command has been submitted by the host to the device associated with the command-queue),

CL_RUNNING (device is currently executing this command),

CL_COMPLETE (the command has completed), or

Error code given by a negative integer value. (command was abnormally terminated - this may be caused by a bad memory access etc.). These error codes come from the same set of error codes that are returned from the platform or runtime API calls as return values or errcode_ret values.

CL_EVENT_REFERENCE_COUNT [2]

cl_uint

Return the event reference count.

Table 2. List of supported event command types
Events Created By Event Command Type

clEnqueueNDRangeKernel

CL_COMMAND_NDRANGE_KERNEL

clEnqueueTask

CL_COMMAND_TASK

clEnqueueNativeKernel

CL_COMMAND_NATIVE_KERNEL

clEnqueueReadBuffer

CL_COMMAND_READ_BUFFER

clEnqueueWriteBuffer

CL_COMMAND_WRITE_BUFFER

clEnqueueCopyBuffer

CL_COMMAND_COPY_BUFFER

clEnqueueReadImage

CL_COMMAND_READ_IMAGE

clEnqueueWriteImage

CL_COMMAND_WRITE_IMAGE

clEnqueueCopyImage

CL_COMMAND_COPY_IMAGE

clEnqueueCopyBufferToImage

CL_COMMAND_COPY_BUFFER_TO_IMAGE

clEnqueueCopyImageToBuffer

CL_COMMAND_COPY_IMAGE_TO_BUFFER

clEnqueueMapBuffer

CL_COMMAND_MAP_BUFFER

clEnqueueMapImage

CL_COMMAND_MAP_IMAGE

clEnqueueUnmapMemObject

CL_COMMAND_UNMAP_MEM_OBJECT

clEnqueueMarker,
clEnqueueMarkerWithWaitList

CL_COMMAND_MARKER

clEnqueueReadBufferRect

CL_COMMAND_READ_BUFFER_RECT

missing before version 1.1.

clEnqueueWriteBufferRect

CL_COMMAND_WRITE_BUFFER_RECT

missing before version 1.1.

clEnqueueCopyBufferRect

CL_COMMAND_COPY_BUFFER_RECT

missing before version 1.1.

clCreateUserEvent

CL_COMMAND_USER

missing before version 1.1.

clEnqueueBarrier,
clEnqueueBarrierWithWaitList

CL_COMMAND_BARRIER

missing before version 1.2.

clEnqueueMigrateMemObjects

CL_COMMAND_MIGRATE_MEM_OBJECTS

missing before version 1.2.

clEnqueueFillBuffer

CL_COMMAND_FILL_BUFFER

missing before version 1.2.

clEnqueueFillImage

CL_COMMAND_FILL_IMAGE

missing before version 1.2.

clEnqueueSVMFree

CL_COMMAND_SVM_FREE

missing before version 2.0.

clEnqueueSVMMemcpy

CL_COMMAND_SVM_MEMCPY

missing before version 2.0.

clEnqueueSVMMemFill

CL_COMMAND_SVM_MEMFILL

missing before version 2.0.

clEnqueueSVMMap

CL_COMMAND_SVM_MAP

missing before version 2.0.

clEnqueueSVMUnmap

CL_COMMAND_SVM_UNMAP

missing before version 2.0.

clEnqueueSVMMigrateMem

CL_COMMAND_SVM_MIGRATE_MEM

missing before version 3.0.

Prior to OpenCL 3.0, implementations should return CL_COMMAND_MIGRATE_MEM_OBJECTS, but may return an implementation-defined event command type for clEnqueueSVMMigrateMem.

Using clGetEventInfo to determine if a command identified by event has finished execution (i.e. CL_EVENT_COMMAND_EXECUTION_STATUS returns CL_COMPLETE) is not a synchronization point. There are no guarantees that the memory objects being modified by command associated with event will be visible to other enqueued commands.

clGetEventInfo returns CL_SUCCESS if the function is executed successfully. Otherwise, it returns one of the following errors:

  • CL_INVALID_VALUE if param_name is not valid, or if size in bytes specified by param_value_size is < size of return type as described in the Kernel Argument Queries table and param_value is not NULL.

  • CL_INVALID_VALUE if information to query given in param_name cannot be queried for event.

  • CL_INVALID_EVENT if event is a not a valid event object.

  • CL_OUT_OF_RESOURCES if there is a failure to allocate resources required by the OpenCL implementation on the device.

  • CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.

See Also

Document Notes

For more information, see the OpenCL Specification

This page is extracted from the OpenCL Specification. Fixes and changes should be made to the Specification, not directly.

Copyright 2014-2023 The Khronos Group Inc.

SPDX-License-Identifier: CC-BY-4.0


1. The error code values are negative, and event state values are positive. The event state values are ordered from the largest value CL_QUEUED for the first or initial state to the smallest value (CL_COMPLETE or negative integer value) for the last or complete state. The value of CL_COMPLETE and CL_SUCCESS are the same.
2. The reference count returned should be considered immediately stale. It is unsuitable for general use in applications. This feature is provided for identifying memory leaks.