OpenCL™规范 5.8.2. 保留和释放程序对象

5.8.2. Retaining and Releasing Program Objects

5.8.2. 保留和释放程序对象

To retain a program object, call the function

要保留程序对象，请调用函数

// Provided by CL_VERSION_1_0
cl_int clRetainProgram(
    cl_program program);

• program is the program object to be retained.

• 程序是要保留的程序对象。

The program reference count is incremented. All APIs that create a program do an implicit retain.

程序引用计数递增。所有创建程序的API都会进行隐式保留。

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

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

• CL_INVALID_PROGRAM if program is not a valid program object.

• CL_INVALID_PROGRAM，如果程序不是有效的程序对象。

• 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实现所需的资源。

To release a program object, call the function

要释放程序对象，请调用函数

// Provided by CL_VERSION_1_0
cl_int clReleaseProgram(
    cl_program program);

• program is the program object to be released.

• 程序是要发布的程序对象。

The program reference count is decremented. The program object is deleted after all kernel objects associated with program have been deleted and the program reference count becomes zero.

程序引用计数递减。在与程序关联的所有内核对象都被删除并且程序引用计数变为零之后，程序对象被删除。

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

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

• CL_INVALID_PROGRAM if program is not a valid program object.

• CL_INVALID_PROGRAM，如果程序不是有效的程序对象。

• 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实现所需的资源。

Using this function to release a reference that was not obtained by creating the object or by calling clRetainProgram causes undefined behavior.

​使用此函数释放不是通过创建对象或调用clRetainProgram获得的引用会导致未定义的行为。

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

要向程序对象注册回调函数，并在程序对象被销毁时调用该函数，请调用该函数

// Provided by CL_VERSION_2_2
cl_int clSetProgramReleaseCallback(
    cl_program program,
    void (CL_CALLBACK* pfn_notify)(cl_program program, void* user_data),
    void* user_data);

clSetProgramReleaseCallback is missing before version 2.2 and deprecated by version 3.0. clSetProgramReleaseCallback在2.2版本之前缺失，在3.0版本中已弃用。

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

• program指定要注册回调的内存对象。

• 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实现可以异步调用此回调函数。应用程序有责任确保回调函数是线程安全的。此回调函数的参数为：

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

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

  • 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 clSetProgramReleaseCallback registers the specified callback function on a callback stack associated with program. The registered callback functions are called in the reverse order in which they were registered. The registered callback functions are called after destructors (if any) for program scope global variables (if any) are called and before the program object is deleted. This provides a mechanism for an application to be notified when destructors for program scope global variables are complete.

​对clSetProgramReleaseCallback的每次调用都会在与program关联的回调堆栈上注册指定的回调函数。已注册的回调函数按注册的相反顺序调用。在调用程序作用域全局变量的析构函数（如果有的话）之后和删除程序对象之前，会调用已注册的回调函数。这提供了一种机制，当程序作用域全局变量的析构函数完成时，应用程序会收到通知。

clSetProgramReleaseCallback may unconditionally return an error if no devices in the context associated with program support destructors for program scope global variables. Support for constructors and destructors for program scope global variables is required only for OpenCL 2.2 devices.

如果与程序关联的上下文中没有设备支持程序作用域全局变量的析构函数，clSetProgramReleaseCallback可能会无条件返回错误。仅OpenCL 2.2设备需要支持程序作用域全局变量的构造函数和析构函数。

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

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

• CL_INVALID_PROGRAM if program is not a valid program object.

• CL_INVALID_PROGRAM，如果程序不是有效的程序对象。

• CL_INVALID_OPERATION if no devices in the context associated with program support destructors for program scope global variables.

• 如果与program关联的上下文中没有设备支持程序作用域全局变量的析构函数，则使用CL_INVALID_OPERATION。

• 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实现所需的资源。