OpenCL™规范 5.5.1. 保留和释放内存对象

5.5.1. Retaining and Releasing Memory Objects

5.5.1. 保留和释放内存对象

To retain a memory object, call the function

要保留内存对象，请调用函数

// Provided by CL_VERSION_1_0
cl_int clRetainMemObject(
    cl_mem memobj);

• memobj specifies the memory object to be retained.

• memobj指定要保留的内存对象。

The memobj reference count is incremented.

memobj引用计数递增。

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

如果函数执行成功，clRetainMemObject将返回CL_SUCCESS。否则，它将返回以下错误之一：

• CL_INVALID_MEM_OBJECT if memobj is not a valid memory object (buffer or image object).

• CL_INVALID_MEM_OBJECT，如果memobj不是有效的内存对象（缓冲区或图像对象）。

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

• CL_OUT_OF_RESOURCES，如果在设备上分配OpenCL实现所需的资源失败。

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

• CL_OUT_OF_HOST_MEMORY，如果在主机上分配OpenCL实现所需的资源失败。

clCreateBuffer, clCreateBufferWithProperties, clCreateSubBuffer, clCreateImage, clCreateImageWithProperties, clCreateImage2D, clCreateImage3D and clCreatePipe perform an implicit retain.

clCreateBuffer、clCreateBufferWithProperties、clCreateSubBuffer、clCreateImage、clCreateImageWithProperties、clCreateImage2D、clCreateImage 3D和clCreatePipe执行隐式保留。

To release a memory object, call the function

要释放内存对象，请调用函数

// Provided by CL_VERSION_1_0
cl_int clReleaseMemObject(
    cl_mem memobj);

• memobj specifies the memory object to be released.

• memobj指定要释放的内存对象。

The memobj reference count is decremented.

memobj引用计数递减。

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

如果函数执行成功，clReleaseMemObject将返回CL_SUCCESS。否则，它将返回以下错误之一：

• CL_INVALID_MEM_OBJECT if memobj is not a valid memory object.

• CL_INVALID_MEM_OBJECT，如果memobj不是有效的内存对象。

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

• CL_OUT_OF_RESOURCES，如果在设备上分配OpenCL实现所需的资源失败。

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

• CL_OUT_OF_HOST_MEMORY，如果在主机上分配OpenCL实现所需的资源失败。

After the memobj reference count becomes zero and commands queued for execution on a command-queue(s) that use memobj have finished, the memory object is deleted. If memobj is a buffer object, memobj cannot be deleted until all sub-buffer objects associated with memobj are deleted. Using this function to release a reference that was not obtained by creating the object or by calling clRetainMemObject causes undefined behavior.

​在memobj引用计数变为零并且在使用memobj的命令队列上排队等待执行的命令已经完成之后，存储器对象被删除。如果memobj是缓冲区对象，则在删除与memobj相关联的所有子缓冲区对象之前，不能删除memobj。使用此函数释放不是通过创建对象或调用clRetainMemObject获得的引用会导致未定义的行为。

To register a callback function with a memory object that is called when the memory object is destroyed, call the function

要向内存对象注册回调函数，当内存对象被破坏时，调用该函数

// Provided by CL_VERSION_1_1
cl_int clSetMemObjectDestructorCallback(
    cl_mem memobj,
    void (CL_CALLBACK* pfn_notify)(cl_mem memobj, void* user_data),
    void* user_data);

clSetMemObjectDestructorCallback is missing before version 1.1. clSetMemObjectDestructorCallback在版本1.1之前丢失。

• memobj specifies the memory object to register the callback to.

• memobj指定要将回调注册到的内存对象。

• pfn_notify is the callback function to register. This callback function may be called asynchronously by the OpenCL implementation. It is the application’s responsibility to ensure that the callback function is thread-safe. The parameters to this callback function are:
  
  pfn_notify是要注册的回调函数。这个回调函数可以由OpenCL实现异步调用。应用程序有责任确保回调函数是线程安全的。此回调函数的参数为：

  • memobj is the memory object being deleted. When the callback function is called by the implementation, this memory object is not longer valid. memobj is only provided for reference purposes.

  • memobj是被删除的内存对象。当实现调用回调函数时，此内存对象不再有效。memobj仅供参考。

  • user_data is a pointer to user-supplied data.

  • user_data是指向用户提供的数据的指针。

• user_data will be passed as the user_data argument when pfn_notify is called. user_data can be NULL.

• 当调用pfn_notify时，user_data将作为user_data参数传递。user_data可以为NULL。

Each call to clSetMemObjectDestructorCallback registers the specified callback function on a destructor callback stack associated with memobj. The registered callback functions are called in the reverse order in which they were registered. The registered callback functions are called and then the memory object’s resources are freed and the memory object is deleted. Therefore, the memory object destructor callback provides a mechanism for an application to safely re-use or free a host_ptr that was specified when memobj was created and used as the storage bits for the memory object.

​对clSetMemObjectDestructorCallback的每次调用都会在与membj关联的析构函数回调堆栈上注册指定的回调函数。已注册的回调函数的调用顺序与它们的注册顺序相反。调用已注册的回调函数，然后释放内存对象的资源并删除内存对象。因此，内存对象析构函数回调为应用程序提供了一种机制，可以安全地重新使用或释放在创建memobj时指定的host_ptr，并将其用作内存对象的存储位。

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

如果函数执行成功，clSetMemObjectDestructorCallback将返回CL_SUCCESS。否则，它将返回以下错误之一：

• CL_INVALID_MEM_OBJECT if memobj is not a valid memory object.

• CL_INVALID_MEM_OBJECT，如果memobj不是有效的内存对象。

• CL_INVALID_VALUE if pfn_notify is NULL.

• 如果pfn_notify为NULL，则CL_INVALID_VALUE。

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

• CL_OUT_OF_RESOURCES，如果在设备上分配OpenCL实现所需的资源失败。

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

• CL_OUT_OF_HOST_MEMORY，如果在主机上分配OpenCL实现所需的资源失败。

When the user callback function is called by the implementation, the contents of the memory region pointed to by host_ptr (if the memory object is created with CL_MEM_USE_HOST_PTR) are undefined. The callback function is typically used by the application to either free or reuse the memory region pointed to by host_ptr. 当实现调用用户回调函数时，host_ptr指向的内存区域的内容（如果内存对象是用CL_MEM_USE_host_ptr创建的）是未定义的。回调函数通常由应用程序用来释放或重用host_ptr指向的内存区域。 ​ The behavior of calling expensive system routines, OpenCL API calls to create contexts or command-queues, or blocking OpenCL operations from the following list below, in a callback is undefined. 在回调中调用昂贵的系统例程、OpenCL API调用以创建上下文或命令队列，或阻止以下列表中的OpenCL操作的行为是未定义的。 clFinish, clWaitForEvents, blocking calls to clEnqueueReadBuffer, clEnqueueReadBufferRect, clEnqueueWriteBuffer, clEnqueueWriteBufferRect, ​阻塞调用clEnqueueReadBuffer、clEnqueueRead BufferRect、clEnQueue WriteBuffer、clEnqueueWriteBufferRect， blocking calls to clEnqueueReadImage and clEnqueueWriteImage, ​​阻塞调用clEnqueueReadImage和clEnqueueWriteImage，​ blocking calls to clEnqueueMapBuffer, clEnqueueMapImage, ​​阻塞调用clEnqueueMapBuffer、clEnqueueMap Image， blocking calls to clBuildProgram, clCompileProgram or clLinkProgram ​​阻塞调用clBuildProgram、clCompileProgram或clLinkProgram ​ If an application needs to wait for completion of a routine from the above list in a callback, please use the non-blocking form of the function, and assign a completion callback to it to do the remainder of your work. Note that when a callback (or other code) enqueues commands to a command-queue, the commands are not required to begin execution until the queue is flushed. In standard usage, blocking enqueue calls serve this role by implicitly flushing the queue. Since blocking calls are not permitted in callbacks, those callbacks that enqueue commands on a command-queue should either call clFlush on the queue before returning or arrange for clFlush to be called later on another thread. 如果应用程序需要在回调中等待完成上面列表中的例程，请使用该函数的非阻塞形式，并为其分配一个完成回调来完成剩余的工作。请注意，当回调（或其他代码）将命令排入命令队列时，在刷新队列之前，不需要开始执行命令。在标准用法中，阻塞队列调用通过隐式刷新队列来服务于此角色。由于回调中不允许阻塞调用，因此那些将命令排入命令队列的回调应该在返回之前调用队列上的clFlush，或者安排稍后在另一个线程上调用clFlush。 ​ The user callback function may not call OpenCL APIs with the memory object for which the callback function is invoked and for such cases the behavior of OpenCL APIs is considered to be undefined. 用户回调函数可能不会使用调用回调函数的内存对象来调用OpenCL API，在这种情况下，OpenCL API的行为被认为是未定义的。