C Specification

To terminate all pending work associated with a context and render all data owned by the context invalid, call the function

// Provided by cl_khr_terminate_context
cl_int clTerminateContextKHR(
    cl_context context);
clTerminateContextKHR is provided by the cl_khr_terminate_context extension.

Parameters

  • context must be a valid OpenCL context.

Description

It is the responsibility of the application to release all objects associated with the context being terminated.

When a context is terminated:

  • The execution status of enqueued commands will be CL_CONTEXT_TERMINATED_KHR. Event objects can be queried using clGetEventInfo. Event callbacks can be registered and registered event callbacks will be called with event_command_status set to CL_CONTEXT_TERMINATED_KHR. clWaitForEvents will return as immediately for commands associated with event objects specified in event_list. The status of user events can be set. Event objects can be retained and released. clGetEventProfilingInfo returns CL_PROFILING_INFO_NOT_AVAILABLE.

  • The context is considered to be terminated. A callback function registered when the context was created will be called. Only queries, retain and release operations can be performed on the context. All other APIs that use a context as an argument will return CL_CONTEXT_TERMINATED_KHR.

  • The contents of the memory regions of the memory objects is undefined. Queries, registering a destructor callback, retain and release operations can be performed on the memory objects.

  • Once a context has been terminated, all OpenCL API calls that create objects or enqueue commands will return CL_CONTEXT_TERMINATED_KHR. APIs that release OpenCL objects will continue to operate as though clTerminateContextKHR was not called.

  • The behavior of callbacks will remain unchanged, and will report appropriate error, if executing after termination of context. This behavior is similar to enqueued commands, after the command-queue has become invalid.

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

  • CL_INVALID_CONTEXT if context is not a valid OpenCL context.

  • CL_CONTEXT_TERMINATED_KHR if context has already been terminated.

  • CL_INVALID_OPERATION if context was not created with CL_CONTEXT_TERMINATE_KHR set to CL_TRUE.

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

An implementation that supports this extension must be able to terminate commands currently executing on devices or queued across all command-queues associated with the context that is being terminated. The implementation cannot implement this extension by waiting for currently executing (or queued) commands to finish execution on devices associated with this context (i.e. doing a clFinish).

See Also

cl_context, cl_khr_terminate_context

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