C Specification

To release an event object, call the function

// Provided by CL_VERSION_1_0
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

CL_VERSION_1_0, cl_event

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

Copyright 2014-2025 The Khronos Group Inc.

SPDX-License-Identifier: CC-BY-4.0