CLEvent (JavaCL Core / BridJ 1.0.0-RC4 API)

java.lang.Object
- com.nativelibs4java.opencl.CLEvent

Direct Known Subclasses:

CLUserEvent
```
public class CLEvent
extends Object
```
OpenCL event object.
Event objects can be used to refer to a kernel execution command (clEnqueueNDRangeKernel, clEnqueueTask, clEnqueueNativeKernel), or read, write, map and copy commands on memory objects (clEnqueue{Read|Write|Map}{Buffer|Image}, clEnqueueCopy{Buffer|Image}, clEnqueueCopyBufferToImage, or clEnqueueCopyImageToBuffer).
An event object can be used to track the execution status of a command.
The API calls that enqueue commands to a command-queue create a new event object that is returned in the event argument.
In case of an error enqueuing the command in the command-queue the event argument does not return an event object.
The execution status of an enqueued command at any given point in time can be CL_QUEUED (command has been enqueued in the command-queue), CL_SUBMITTED (enqueued command has been submitted by the host to the device associated with the command-queue), CL_RUNNING (device is currently executing this command), CL_COMPLETE (command has successfully completed) or the appropriate error code if the command was abnormally terminated (this may be caused by a bad memory access etc.).
The error code returned by a terminated command is a negative integer value.
A command is considered to be complete if its execution status is CL_COMPLETE or is a negative integer value.
If the execution of a command is terminated, the command-queue associated with this terminated command, and the associated context (and all other command-queues in this context) may no longer be available.
The behavior of OpenCL API calls that use this context (and command-queues associated with this context) are now considered to be implementation- defined.
The user registered callback function specified when context is created can be used to report appropriate error information.

Author:

ochafik

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`static class`	`CLEvent.CommandExecutionStatus` Values for CL_EVENT_COMMAND_EXECUTION_STATUS
`static class`	`CLEvent.CommandType` Values for CL_EVENT_COMMAND_TYPE
`static interface`	`CLEvent.EventCallback`

Field Summary

Fields
Modifier and Type	Field and Description
`static CLEvent`	`FIRE_AND_FORGET` Pass this to special value to any method that expects a variable number of events to wait for and that returns an event, to completely avoid returning the completion event (will return null instead of the event).

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`boolean`	`equals(Object obj)` Underyling implementation pointer-based equality test
`CLEvent.CommandExecutionStatus`	`getCommandExecutionStatus()` Return the execution status of the command identified by event.
`int`	`getCommandExecutionStatusValue()` Return the execution status of the command identified by event.
`CLEvent.CommandType`	`getCommandType()` Return the command associated with event.
`static <E extends TypedPointer,A extends com.nativelibs4java.opencl.CLAbstractEntity> Pointer<E>`	`getEntities(A[] objects, Pointer<E> out)`
`long`	`getProfilingCommandEnd()` A 64-bit value that describes the current device time counter in nanoseconds when the command identified by event has finished execution on the device.
`long`	`getProfilingCommandQueued()` A 64-bit value that describes the current device time counter in nanoseconds when the command identified by event is enqueued in a command-queue by the host.
`long`	`getProfilingCommandStart()` A 64-bit value that describes the current device time counter in nanoseconds when the command identified by event starts execution on the device.
`long`	`getProfilingCommandSubmit()` A 64-bit value that describes the current device time counter in nanoseconds when the command identified by event that has been enqueued is submitted by the host to the device associated with the command- queue.
`CLQueue`	`getQueue()`
`int`	`hashCode()` Underyling implementation pointer-based hashCode computation
`void`	`invokeUponCompletion(Runnable action)` Invoke an action in a separate thread only after completion of the command associated with this event.
`static void`	`invokeUponCompletion(Runnable action, CLEvent... eventsToWaitFor)` Invoke an action in a separate thread only after completion of all of the commands associated with the specified events.
`void`	`release()` Manual release of the OpenCL resources represented by this object.
`void`	`setCallback(int commandExecStatus, CLEvent.EventCallback callback)` Calls clSetEventCallback.
`void`	`setCompletionCallback(CLEvent.EventCallback callback)` Registers a user callback function for the completion execution status (CL_COMPLETE).
`String`	`toString()`
`void`	`waitFor()` Wait for this event, blocking the caller thread independently of any queue until all of the command associated with this events completes.
`static void`	`waitFor(CLEvent... eventsToWaitFor)` Calls clWaitForEvents.

Methods inherited from class java.lang.Object
getClass, notify, notifyAll, wait, wait, wait

- Field Detail
  - FIRE_AND_FORGET
```
public static final CLEvent FIRE_AND_FORGET
```
    Pass this to special value to any method that expects a variable number of events to wait for and that returns an event, to completely avoid returning the completion event (will return null instead of the event).
- Method Detail
  - getQueue
```
public CLQueue getQueue()
```
  - setCompletionCallback
```
public void setCompletionCallback(CLEvent.EventCallback callback)
```
    Registers a user callback function for the completion execution status (CL_COMPLETE).
    
    Parameters:
    
    callback -
    
    Throws:
    
    UnsupportedOperationException - in OpenCL 1.0
    
    Since:
    
    OpenCL 1.1
  - setCallback
```
public void setCallback(int commandExecStatus,
                        CLEvent.EventCallback callback)
```
    Calls clSetEventCallback.
    Registers a user callback function for a specific command execution status.
    The registered callback function will be called when the execution status of command associated with event changes to the execution status specified by command_exec_status.
    
    Parameters:
    
    commandExecStatus - specifies the command execution status for which the callback is registered. The command execution callback values for which a callback can be registered are: CL_COMPLETE. There is no guarantee that the callback functions registered for various execution status values for an event will be called in the exact order that the execution status of a command changes.
    
    callback -
    
    Throws:
    
    UnsupportedOperationException - in OpenCL 1.0
    
    Since:
    
    OpenCL 1.1
  - waitFor
```
public void waitFor()
```
    Wait for this event, blocking the caller thread independently of any queue until all of the command associated with this events completes.
  - waitFor
```
public static void waitFor(CLEvent... eventsToWaitFor)
```
    Calls clWaitForEvents.
    Wait for events, blocking the caller thread independently of any queue until all of the commands associated with the events completed.
    
    Parameters:
    
    eventsToWaitFor - List of events which completion is to be waited for
  - invokeUponCompletion
```
public void invokeUponCompletion(Runnable action)
```
    Invoke an action in a separate thread only after completion of the command associated with this event.
    Returns immediately.
    
    Parameters:
    
    action - an action to be ran
    
    Throws:
    
    IllegalArgumentException - if action is null
  - invokeUponCompletion
```
public static void invokeUponCompletion(Runnable action,
                                        CLEvent... eventsToWaitFor)
```
    Invoke an action in a separate thread only after completion of all of the commands associated with the specified events.
    Returns immediately.
    
    Parameters:
    
    action - an action to be ran
    
    eventsToWaitFor - list of events which commands's completion should be waited for before the action is ran
    
    Throws:
    
    IllegalArgumentException - if action is null
  - getCommandExecutionStatus
```
public CLEvent.CommandExecutionStatus getCommandExecutionStatus()
```
    Return the execution status of the command identified by event.
    
    Throws:
    
    CLException - is the execution status denotes an error
  - getCommandExecutionStatusValue
```
public int getCommandExecutionStatusValue()
```
    Return the execution status of the command identified by event.
    
    Throws:
    
    CLException - is the execution status denotes an error
  - getCommandType
```
public CLEvent.CommandType getCommandType()
```
    Return the command associated with event.
  - getProfilingCommandQueued
```
public long getProfilingCommandQueued()
```
    A 64-bit value that describes the current device time counter in nanoseconds when the command identified by event is enqueued in a command-queue by the host.
  - getProfilingCommandSubmit
```
public long getProfilingCommandSubmit()
```
    A 64-bit value that describes the current device time counter in nanoseconds when the command identified by event that has been enqueued is submitted by the host to the device associated with the command- queue.
  - getProfilingCommandStart
```
public long getProfilingCommandStart()
```
    A 64-bit value that describes the current device time counter in nanoseconds when the command identified by event starts execution on the device.
  - getProfilingCommandEnd
```
public long getProfilingCommandEnd()
```
    A 64-bit value that describes the current device time counter in nanoseconds when the command identified by event has finished execution on the device.
  - toString
```
public String toString()
```
    Overrides:
    
    toString in class Object
  - release
```
public void release()
```
    Manual release of the OpenCL resources represented by this object.
    Note that resources are automatically released by the garbage collector, so in general there's no need to call this method.
    In an environment with fast allocation/deallocation of large objects, it might be safer to call release() manually, though.
    Note that release() does not necessarily free the object immediately : OpenCL maintains a reference count for all its objects, and an object released on the Java side might still be pointed to by running kernels or queued operations.
  - getEntities
```
public static <E extends TypedPointer,A extends com.nativelibs4java.opencl.CLAbstractEntity> Pointer<E> getEntities(A[] objects,
                                                                                                                    Pointer<E> out)
```
  - hashCode
```
public int hashCode()
```
    Underyling implementation pointer-based hashCode computation
    
    Overrides:
    
    hashCode in class Object
  - equals
```
public boolean equals(Object obj)
```
    Underyling implementation pointer-based equality test
    
    Overrides:
    
    equals in class Object

Class CLEvent

Nested Class Summary

Field Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

FIRE_AND_FORGET

Method Detail

getQueue

setCompletionCallback

setCallback

waitFor

waitFor

invokeUponCompletion

invokeUponCompletion

getCommandExecutionStatus

getCommandExecutionStatusValue

getCommandType

getProfilingCommandQueued

getProfilingCommandSubmit

getProfilingCommandStart

getProfilingCommandEnd

toString

release

getEntities

hashCode

equals