C Specification

To enqueue a command to release OpenCL memory objects created from external memory handles, call the function

// Provided by cl_khr_external_memory
cl_int clEnqueueReleaseExternalMemObjectsKHR(
    cl_command_queue command_queue,
    cl_uint num_mem_objects,
    const cl_mem* mem_objects,
    cl_uint num_events_in_wait_list,
    const cl_event* event_wait_list,
    cl_event* event);

Parameters

  • command_queue specifies a valid command-queue.

  • num_mem_objects specifies the number of memory objects to release.

  • mem_objects points to a list of valid memory objects.

  • num_events_in_wait_list specifies the number of events in event_wait_list.

  • event_wait_list points to the list of events that need to complete before clEnqueueReleaseExternalMemObjectsKHR can be executed. If event_wait_list is NULL, then clEnqueueReleaseExternalMemObjectsKHR does not wait on any event to complete. If event_wait_list is NULL, num_events_in_wait_list must be 0. If event_wait_list is not NULL, the list of events pointed to by event_wait_list must be valid and num_events_in_wait_list must be greater than 0. The events specified in event_wait_list act as synchronization points. The context associated with events in event_wait_list and that of command_queue must be the same.

  • event returns an event object that identifies this particular command and can be used to query or queue a wait for this particular command to complete. event can be NULL in which case it will not be possible for the application to query the status of this command or queue a wait for this command to complete.

Description

Applications must release memory objects that were acquired using clEnqueueReleaseExternalMemObjectsKHR before using any external memory handles that were specified when the memory objects were created or accessing the external memory that these handles represent outside of OpenCL, otherwise behavior is undefined. This is to guarantee that the state of memory objects is up-to-date and that they are accessible outside of OpenCL.

The following restrictions shall apply:

  • Each memory object must be released only once. Releasing a memory object multiple times without acquiring it results in implementation-defined behavior.

  • The release must be performed on a command-queue associated with a device that was one of the devices specified via CL_MEM_DEVICE_HANDLE_LIST_KHR when the memory object was imported using clCreateBufferWithProperties or clCreateImageWithProperties. If CL_MEM_DEVICE_HANDLE_LIST_KHR was not specified, the release can be performed on a command-queue associated with any device in the context.

  • The memory object will be released for all devices specified via CL_MEM_DEVICE_HANDLE_LIST_KHR when the memory object was imported using clCreateBufferWithProperties or clCreateImageWithProperties. If CL_MEM_DEVICE_HANDLE_LIST_KHR was not specified, the memory object will be released for all devices in the context.

See “Example with Acquire / Release” provided in https://www.khronos.org/registry/OpenCL/specs/3.0-unified/html/OpenCL_API.html#cl_khr_external_memory-Sample-Code for more details on how to use this API.

If num_mem_objects is 0 and mem_objects is NULL, the command will trivially succeed after its event dependencies are satisfied and will update its completion event.

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

  • CL_INVALID_VALUE if num_mem_objects is zero and mem_objects is not a NULL value, or if num_mem_objects is greater than 0 and mem_objects is NULL.

  • CL_INVALID_MEM_OBJECT if any of the memory objects in mem_objects is not a valid OpenCL memory object created using an external memory handle.

  • CL_INVALID_COMMAND_QUEUE

    • if command_queue is not a valid command-queue, or

    • if device associated with command_queue is not one of the devices specified by CL_MEM_DEVICE_HANDLE_LIST_KHR at the time of creating one or more of mem_objects, or

    • if one or more of mem_objects belong to a context that does not contain a device associated with command_queue.

  • CL_INVALID_EVENT_WAIT_LIST

    • if event_wait_list is NULL and num_events_in_wait_list is not 0, or

    • if event_wait_list is not NULL and num_events_in_wait_list is 0, or

    • if event objects in event_wait_list are not valid events.

  • CL_EXEC_STATUS_ERROR_FOR_EVENTS_IN_WAIT_LIST if the execution status of any of the events in event_wait_list is a negative integer value.

  • 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_command_queue, cl_event, cl_khr_external_memory, cl_mem, cl_uint

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