C Specification

To release an event object, call the function

cl_int clReleaseEvent(
    cl_event event);

Parameters

  • event is the event object to be released.

Description

The event reference count is decremented.

The event object is deleted once the reference count becomes zero, the specific command identified by this event has completed (or terminated) and there are no commands in the command-queues of a context that require a wait for this event to complete. Using this function to release a reference that was not obtained by creating the object or by calling clRetainEvent causes undefined behavior.

Developers should be careful when releasing their last reference count on events created by clCreateUserEvent that have not yet been set to status of CL_​COMPLETE or an error. If the user event was used in the event_wait_list argument passed to a clEnqueue* API or another application host thread is waiting for it in clWaitForEvents, those commands and host threads will continue to wait for the event status to reach CL_​COMPLETE or error, even after the application has released the object. Since in this scenario the application has released its last reference count to the user event, it would be in principle no longer valid for the application to change the status of the event to unblock all the other machinery. As a result the waiting tasks will wait forever, and associated events, cl_mem objects, command queues and contexts are likely to leak. In-order command queues caught up in this deadlock may cease to do any work.

clReleaseEvent returns CL_​SUCCESS if the function is executed successfully. Otherwise, it returns one of the following errors:

  • CL_​INVALID_​EVENT if event is 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 (c) 2014-2020 Khronos Group. This work is licensed under a Creative Commons Attribution 4.0 International License.