JOCL v2.6.0-rc-20250722
JOCL, OpenCL® API Binding for Java™ (public API).
CLEvent.java
Go to the documentation of this file.
1/*
2 * Copyright (c) 2009 JogAmp Community. All rights reserved.
3 *
4 * Redistribution and use in source and binary forms, with or without modification, are
5 * permitted provided that the following conditions are met:
6 *
7 * 1. Redistributions of source code must retain the above copyright notice, this list of
8 * conditions and the following disclaimer.
9 *
10 * 2. Redistributions in binary form must reproduce the above copyright notice, this list
11 * of conditions and the following disclaimer in the documentation and/or other materials
12 * provided with the distribution.
13 *
14 * THIS SOFTWARE IS PROVIDED BY JogAmp Community ``AS IS'' AND ANY EXPRESS OR IMPLIED
15 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
16 * FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL JogAmp Community OR
17 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
18 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
19 * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
20 * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
21 * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
22 * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
23 *
24 * The views and conclusions contained in the software and documentation are those of the
25 * authors and should not be interpreted as representing official policies, either expressed
26 * or implied, of JogAmp Community.
27 */
28
29package com.jogamp.opencl;
30
31import com.jogamp.opencl.impl.CLTLInfoAccessor;
32import com.jogamp.opencl.llb.CL;
33import com.jogamp.opencl.llb.impl.CLEventCallback;
34import com.jogamp.common.nio.PointerBuffer;
35import java.nio.Buffer;
36
37import static com.jogamp.opencl.llb.CL.*;
38import static com.jogamp.opencl.CLException.*;
39
40/**
41 * Event objects can be used for synchronizing command queues, e.g you can wait until a
42 * event occurs or they can also be used to capture profiling information that
43 * measure execution time of a command.
44 * Profiling of OpenCL commands can be enabled by using a {@link com.jogamp.opencl.CLCommandQueue} created with
45 * {@link com.jogamp.opencl.CLCommandQueue.Mode#PROFILING_MODE}.
46 * @author Michael Bien, et al.
47 */
48public class CLEvent extends CLObjectResource {
49
50 private final CLEventInfoAccessor eventInfo;
51 private final CLEventProfilingInfoAccessor eventProfilingInfo;
52 private final CL binding;
53
54 CLEvent(final CLContext context, final long id) {
55 super(context, id);
56 binding = context.getPlatform().getCLBinding();
57 this.eventInfo = new CLEventInfoAccessor();
58 this.eventProfilingInfo = new CLEventProfilingInfoAccessor();
59 }
60
61 /**
62 * Registers a callback which will be called when the event terminates (COMPLETE or ERROR).
63 */
64 public void registerCallback(final CLEventListener callback) {
66 }
67
68 // apparently only ExecutionStatus.COMPLETE is allowed -> private
69 private void registerCallback(final CLEventListener callback, final ExecutionStatus trigger) {
70 binding.clSetEventCallback(ID, trigger.STATUS, new CLEventCallback() {
71 @Override public void eventStateChanged(final long event, final int status) {
72 callback.eventStateChanged(CLEvent.this, status);
73 }
74 });
75 }
76
77 @Override
78 public void release() {
79 super.release();
80 final int ret = binding.clReleaseEvent(ID);
81 checkForError(ret, "can not release event");
82 }
83
84 /**
85 * Returns the execution status of the command which triggers this event.
86 */
89 }
90
91 /**
92 * Returns true only if {@link #getStatus} returns {@link ExecutionStatus#COMPLETE}.
93 */
94 public boolean isComplete() {
95 return ExecutionStatus.COMPLETE.equals(getStatus());
96 }
97
98 public int getStatusCode() {
99 return (int)eventInfo.getLong(CL_EVENT_COMMAND_EXECUTION_STATUS);
100 }
101
103 final int status = (int)eventInfo.getLong(CL_EVENT_COMMAND_TYPE);
104 return CommandType.valueOf(status);
105 }
106
107 public long getProfilingInfo(final ProfilingCommand command) {
108 return eventProfilingInfo.getLong(command.COMMAND);
109 }
110
111
112 @Override
113 public String toString() {
114 return getClass().getSimpleName()+" [id: " + ID
115 + " name: " + getType()
116 + " status: " + getStatus()+"]";
117 }
118
119 @Override
120 public boolean equals(final Object obj) {
121 if (obj == null) {
122 return false;
123 }
124 if (getClass() != obj.getClass()) {
125 return false;
126 }
127 final CLEvent other = (CLEvent) obj;
128 if (this.context != other.context && (this.context == null || !this.context.equals(other.context))) {
129 return false;
130 }
131 if (this.ID != other.ID) {
132 return false;
133 }
134 return true;
135 }
136
137 @Override
138 public int hashCode() {
139 int hash = 5;
140 hash = 13 * hash + (this.context != null ? this.context.hashCode() : 0);
141 hash = 13 * hash + (int) (this.ID ^ (this.ID >>> 32));
142 return hash;
143 }
144
145
146
147 private class CLEventInfoAccessor extends CLTLInfoAccessor {
148
149 @Override
150 protected int getInfo(final int name, final long valueSize, final Buffer value, final PointerBuffer valueSizeRet) {
151 return binding.clGetEventInfo(ID, name, valueSize, value, valueSizeRet);
152 }
153
154 }
155
156 private class CLEventProfilingInfoAccessor extends CLTLInfoAccessor {
157
158 @Override
159 protected int getInfo(final int name, final long valueSize, final Buffer value, final PointerBuffer valueSizeRet) {
160 return binding.clGetEventProfilingInfo(ID, name, valueSize, value, valueSizeRet);
161 }
162
163 }
164
165 // TODO merge with ExecutionStatus?
166
167 public enum ProfilingCommand {
168
169 /**
170 * A 64-bit value that describes the current device time counter in nanoseconds
171 * when the command identified by event is enqueued in a command-queue by the host.
172 */
173 QUEUED(CL_PROFILING_COMMAND_QUEUED),
174
175 /**
176 * A 64-bit value that describes the current device time counter in nanoseconds when
177 * the command identified by event that has been enqueued is submitted by the host to
178 * the device associated with the commandqueue.
179 */
180 SUBMIT(CL_PROFILING_COMMAND_SUBMIT),
181
182 /**
183 * A 64-bit value that describes the current device time counter in nanoseconds when
184 * the command identified by event starts execution on the device.
185 */
186 START(CL_PROFILING_COMMAND_START),
187
188 /**
189 * A 64-bit value that describes the current device time counter in nanoseconds when
190 * the command identified by event has finished execution on the device.
191 */
192 END(CL_PROFILING_COMMAND_END);
193
194 /**
195 * Value of wrapped OpenCL profiling command.
196 */
197 public final int COMMAND;
198
199 private ProfilingCommand(final int command) {
200 this.COMMAND = command;
201 }
202
203 public static ProfilingCommand valueOf(final int status) {
204 switch(status) {
205 case(CL_PROFILING_COMMAND_QUEUED):
206 return QUEUED;
207 case(CL_PROFILING_COMMAND_SUBMIT):
208 return SUBMIT;
209 case(CL_PROFILING_COMMAND_START):
210 return START;
211 case(CL_PROFILING_COMMAND_END):
212 return END;
213 }
214 return null;
215 }
216
217 }
218
219
220
221 public enum ExecutionStatus {
222
223 /**
224 * Command has been enqueued in the command-queue.
225 */
226 QUEUED(CL_QUEUED),
227
228 /**
229 * Enqueued command has been submitted by the host to the device
230 * associated with the command-queue.
231 */
232 SUBMITTED(CL_SUBMITTED),
233
234 /**
235 * Device is currently executing this command.
236 */
237 RUNNING(CL_RUNNING),
238
239 /**
240 * The command has completed.
241 */
242 COMPLETE(CL_COMPLETE),
243
244 /**
245 * The command did not complete because of an error.
246 */
247 ERROR(-1);
248
249
250 /**
251 * Value of wrapped OpenCL command execution status.
252 */
253 public final int STATUS;
254
255 private ExecutionStatus(final int status) {
256 this.STATUS = status;
257 }
258
259 public static ExecutionStatus valueOf(final int status) {
260 switch(status) {
261 case(CL_QUEUED):
262 return QUEUED;
263 case(CL_SUBMITTED):
264 return SUBMITTED;
265 case(CL_RUNNING):
266 return RUNNING;
267 case(CL_COMPLETE):
268 return COMPLETE;
269 }
270 if(status < 0) {
271 return ERROR;
272 }
273 return null;
274 }
275 }
276
277 public enum CommandType {
278
279 NDRANGE_KERNEL(CL_COMMAND_NDRANGE_KERNEL),
280 TASK(CL_COMMAND_TASK),
281 NATIVE_KERNEL(CL_COMMAND_NATIVE_KERNEL),
282 READ_BUFFER(CL_COMMAND_READ_BUFFER),
283 WRITE_BUFFER(CL_COMMAND_WRITE_BUFFER),
284 COPY_BUFFER(CL_COMMAND_COPY_BUFFER),
285 READ_IMAGE(CL_COMMAND_READ_IMAGE),
286 WRITE_IMAGE(CL_COMMAND_WRITE_IMAGE),
287 COPY_IMAGE(CL_COMMAND_COPY_IMAGE),
288 COPY_BUFFER_TO_IMAGE(CL_COMMAND_COPY_BUFFER_TO_IMAGE),
289 COPY_IMAGE_TO_BUFFER(CL_COMMAND_COPY_IMAGE_TO_BUFFER),
290 MAP_BUFFER(CL_COMMAND_MAP_BUFFER),
291 MAP_IMAGE(CL_COMMAND_MAP_IMAGE),
292 UNMAP_MEM_OBJECT(CL_COMMAND_UNMAP_MEM_OBJECT),
293 MARKER(CL_COMMAND_MARKER),
294 READ_BUFFER_RECT(CL_COMMAND_READ_BUFFER_RECT),
295 WRITE_BUFFER_RECT(CL_COMMAND_WRITE_BUFFER_RECT),
296 COPY_BUFFER_RECT(CL_COMMAND_COPY_BUFFER_RECT),
297 USER(CL_COMMAND_USER),
298 ACQUIRE_GL_OBJECTS(CL_COMMAND_ACQUIRE_GL_OBJECTS),
299 RELEASE_GL_OBJECTS(CL_COMMAND_RELEASE_GL_OBJECTS),
300 GL_FENCE_SYNC_OBJECT_KHR(CL_COMMAND_GL_FENCE_SYNC_OBJECT_KHR);
301
302 /**
303 * Value of wrapped OpenCL command type.
304 */
305 public final int TYPE;
306
307 private CommandType(final int type) {
308 this.TYPE = type;
309 }
310
311 public static CommandType valueOf(final int commandType) {
312 final CommandType[] values = CommandType.values();
313 for (final CommandType value : values) {
314 if(value.TYPE == commandType)
315 return value;
316 }
317 return null;
318 }
319
320 }
321
322}
CLContext is responsible for managing objects such as command-queues, memory, program and kernel obje...
Definition: CLContext.java:79
CLPlatform getPlatform()
Returns the CLPlatform this context is running on.
Definition: CLContext.java:569
Event objects can be used for synchronizing command queues, e.g you can wait until a event occurs or ...
Definition: CLEvent.java:48
boolean equals(final Object obj)
Definition: CLEvent.java:120
long getProfilingInfo(final ProfilingCommand command)
Definition: CLEvent.java:107
CommandType getType()
Definition: CLEvent.java:102
ExecutionStatus getStatus()
Returns the execution status of the command which triggers this event.
Definition: CLEvent.java:87
boolean isComplete()
Returns true only if getStatus returns ExecutionStatus#COMPLETE.
Definition: CLEvent.java:94
void registerCallback(final CLEventListener callback)
Registers a callback which will be called when the event terminates (COMPLETE or ERROR).
Definition: CLEvent.java:64
void release()
Releases the OpenCL resource.
Definition: CLEvent.java:78
final long ID
The OpenCL object handle.
Definition: CLObject.java:41
Internal utility for common OpenCL clGetFooInfo calls.
static CommandType valueOf(final int commandType)
Definition: CLEvent.java:311
final int TYPE
Value of wrapped OpenCL command type.
Definition: CLEvent.java:305
RUNNING
Device is currently executing this command.
Definition: CLEvent.java:237
static ExecutionStatus valueOf(final int status)
Definition: CLEvent.java:259
QUEUED
Command has been enqueued in the command-queue.
Definition: CLEvent.java:226
ERROR
The command did not complete because of an error.
Definition: CLEvent.java:247
SUBMITTED
Enqueued command has been submitted by the host to the device associated with the command-queue.
Definition: CLEvent.java:232
COMPLETE
The command has completed.
Definition: CLEvent.java:242
final int STATUS
Value of wrapped OpenCL command execution status.
Definition: CLEvent.java:253
START
A 64-bit value that describes the current device time counter in nanoseconds when the command identif...
Definition: CLEvent.java:186
SUBMIT
A 64-bit value that describes the current device time counter in nanoseconds when the command identif...
Definition: CLEvent.java:180
final int COMMAND
Value of wrapped OpenCL profiling command.
Definition: CLEvent.java:197
QUEUED
A 64-bit value that describes the current device time counter in nanoseconds when the command identif...
Definition: CLEvent.java:173
static ProfilingCommand valueOf(final int status)
Definition: CLEvent.java:203
END
A 64-bit value that describes the current device time counter in nanoseconds when the command identif...
Definition: CLEvent.java:192
A callback for a specific command execution status.
void eventStateChanged(CLEvent event, int status)
Java bindings to OpenCL, the Open Computing Language.
Definition: CL.java:26
int clGetEventInfo(long event, int param_name, long param_value_size, Buffer param_value, PointerBuffer param_value_size_ret)
Interface to C language function: cl_int {@native clGetEventInfo}(cl_event event,...
int clGetEventProfilingInfo(long event, int param_name, long param_value_size, Buffer param_value, PointerBuffer param_value_size_ret)
Interface to C language function: cl_int {@native clGetEventProfilingInfo}(cl_event event,...
int clReleaseEvent(long event)
Interface to C language function: cl_int {@native clReleaseEvent}(cl_event event)
int clSetEventCallback(long event, int type, CLEventCallback cb)
Interface to C language function: int32_t {@native clSetEventCallback}(cl_event event,...
A callback for a specific command execution status.