C Specification

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

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.

Parameters

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

  • 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:

    • 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.

    • user_data is a pointer to user supplied data.

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

Description

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 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 returns CL_SUCCESS if the function is executed successfully. Otherwise, it returns one of the following errors:

  • CL_INVALID_PROGRAM if program is not a valid program object.

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

  • CL_INVALID_VALUE if pfn_notify is NULL.

  • 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

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 2014-2023 The Khronos Group Inc.

SPDX-License-Identifier: CC-BY-4.0