org.lwjgl.opencl

Class KHRTerminateContext

java.lang.Object

org.lwjgl.opencl.KHRTerminateContext

public class KHRTerminateContext
extends java.lang.Object

Native bindings to the khr_terminate_context extension.

OpenCL provides an API to release a context. This operation is done only after all queues, memory object, programs and kernels are released, which in turn might wait for all ongoing operations to complete. However, there are cases in which a fast release is required, or release operation cannot be done, as commands are stuck in mid execution. An example of the first case can be program termination due to exception, or quick shutdown due to low power. Examples of the second case are when a kernel is running too long, or gets stuck, or it may result from user action which makes the results of the computation unnecessary.

In many cases, the driver or the device is capable of speeding up the closure of ongoing operations when the results are no longer required in a much more expedient manner than waiting for all previously enqueued operations to finish.

This extension implements a new query to check whether a device can terminate an OpenCL context and adds an API to terminate a context.

Field Summary

Fields

Modifier and Type	Field and Description
static int	CL_CONTEXT_TERMINATE_KHR Specifies whether the context can be terminated.
static int	CL_DEVICE_TERMINATE_CAPABILITY_KHR Describes the termination capability of the OpenCL device.

Method Summary

Modifier and Type	Method and Description
static int	clTerminateContextKHR(long context) Terminates all pending work associated with the context and renders all data owned by the context invalid.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

CL_DEVICE_TERMINATE_CAPABILITY_KHR

public static final int CL_DEVICE_TERMINATE_CAPABILITY_KHR

Describes the termination capability of the OpenCL device. This is a bitfield where a value of CL_DEVICE_TERMINATE_CAPABILITY_CONTEXT_KHR indicates that context termination is supported.

See Also:

Constant Field Values

CL_CONTEXT_TERMINATE_KHR

public static final int CL_CONTEXT_TERMINATE_KHR

Specifies whether the context can be terminated. The default value is FALSE.

See Also:

Constant Field Values

Method Detail

clTerminateContextKHR

public static int clTerminateContextKHR(long context)

Terminates all pending work associated with the context and renders all data owned by the context invalid. 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 TERMINATED_KHR. Event objects can be queried using GetEventInfo. Event callbacks can be registered and registered event callbacks will be called with event_command_exec_status set to TERMINATED_KHR. WaitForEvents will return 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. GetEventProfilingInfo returns 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 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 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.

Parameters:

context - the context to terminate

Returns:

SUCCESS if the function is executed successfully. Otherwise, it returns one of the following errors: "INVALID_CONTEXT if context is not a valid OpenCL context.", "CONTEXT_TERMINATED_KHR if context has already been terminated.", "INVALID_OPERATION if context was not created with CONTEXT_TERMINATE_KHR set to TRUE.", OORE, OOHME