C Specification

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

// Provided by cl_khr_external_memory
cl_int clEnqueueAcquireExternalMemObjectsKHR(
    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);
clEnqueueAcquireExternalMemObjectsKHR is provided by the cl_khr_external_memory extension.

Parameters

  • command_queue specifies a valid command-queue.

  • num_mem_objects specifies the number of memory objects to acquire.

  • 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 clEnqueueAcquireExternalMemObjectsKHR can be executed. If event_wait_list is NULL, then clEnqueueAcquireExternalMemObjectsKHR does not explicitly 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 acquire the memory objects that are created using external handles before they can be used by any OpenCL commands queued to a command-queue. Behavior is undefined if a memory object created from an external memory handle is used by an OpenCL command queued to a command-queue without being acquired. This is to guarantee that the state of the memory objects is up-to-date and they are accessible to OpenCL.

The following restrictions shall apply:

  • Each memory object must be acquired only once. Acquiring a memory object multiple times without releasing it results in implementation-defined behavior.

  • The acquire 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 acquire can be performed on a command-queue associated with any device in the context.

  • The memory object will be acquired 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 acquired for all devices in the context.

See “Example with Acquire / Release” 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.

clEnqueueAcquireExternalMemObjectsKHR 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