org.lwjgl.opencl.KHRTerminateContext Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of lwjgl-opencl Show documentation
An open, royalty-free standard for cross-platform, parallel programming of diverse processors found in personal computers, servers, mobile devices and embedded platforms.
There is a newer version: 3.3.4
Show newest version
/*
 * Copyright LWJGL. All rights reserved.
 * License terms: https://www.lwjgl.org/license
 * MACHINE GENERATED FILE, DO NOT EDIT
 */
package org.lwjgl.opencl;

import static org.lwjgl.system.Checks.*;
import static org.lwjgl.system.JNI.*;

/**
 * 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.
 */
public class KHRTerminateContext {

	/**
	 * Describes the termination capability of the OpenCL device. This is a bitfield where a value of {@code CL_DEVICE_TERMINATE_CAPABILITY_CONTEXT_KHR}
	 * indicates that context termination is supported.
	 */
	public static final int CL_DEVICE_TERMINATE_CAPABILITY_KHR = 0x200F;

	/** Specifies whether the context can be terminated. The default value is {@link CL10#CL_FALSE FALSE}. */
	public static final int CL_CONTEXT_TERMINATE_KHR = 0x2010;

	protected KHRTerminateContext() {
		throw new UnsupportedOperationException();
	}

	static boolean isAvailable(CLCapabilities caps) {
		return checkFunctions(
			caps.clTerminateContextKHR
		);
	}

	// --- [ clTerminateContextKHR ] ---

	/**
	 * 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 {@code TERMINATED_KHR}. Event objects can be queried using {@link CL10#clGetEventInfo GetEventInfo}. Event
	 * callbacks can be registered and registered event callbacks will be called with {@code event_command_exec_status} set to {@code TERMINATED_KHR}.
	 * {@link CL10#clWaitForEvents WaitForEvents} will return immediately for commands associated with event objects specified in {@code event_list}. The status of user
	 * events can be set. Event objects can be retained and released. {@link CL10#clGetEventProfilingInfo GetEventProfilingInfo} returns {@link CL10#CL_PROFILING_INFO_NOT_AVAILABLE 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 {@code 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 {@code CONTEXT_TERMINATED_KHR}. APIs
	 * that release OpenCL objects will continue to operate as though {@code 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.
	 * 
	 *
	 * @param context the context to terminate
	 *
	 * @return {@link CL10#CL_SUCCESS SUCCESS} if the function is executed successfully. Otherwise, it returns one of the following errors:
	 *         "{@link CL10#CL_INVALID_CONTEXT INVALID_CONTEXT} if {@code context} is not a valid OpenCL context.",
	 *         "{@code CONTEXT_TERMINATED_KHR} if {@code context} has already been terminated.",
	 *         "{@link CL10#CL_INVALID_OPERATION INVALID_OPERATION} if {@code context} was not created with {@link #CL_CONTEXT_TERMINATE_KHR CONTEXT_TERMINATE_KHR} set to {@link CL10#CL_TRUE TRUE}.",
	 *         OORE,
	 *         OOHME
	 */
	public static int clTerminateContextKHR(long context) {
		long __functionAddress = CL.getICD().clTerminateContextKHR;
		if ( CHECKS ) {
			check(__functionAddress);
			check(context);
		}
		return callPI(__functionAddress, context);
	}

}