itk::OpenCLEvent Class Reference

#include <itkOpenCLEvent.h>

Detailed Description

OpenCLEvent class represents an OpenCL event object.

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.

\table \row \o IsQueued() \o The command command has been enqueued in the command-queue. \row \o IsSubmitted() \o The enqueued command has been submitted by the host to the device associated with the command-queue. \row \o IsRunning() \o The command is currently executing on the OpenCL device. \row \o IsComplete() \o The command has successfully completed. \row \o IsError() \o The command has finished execution due to an error. \endtable

The method WaitForFinished() waits on the host thread for commands identified by event objects in event list to complete. A command is considered complete if its execution status is {CL_COMPLETE} or a negative value.

OpenCLBuffer buffer = context->CreateBufferDevice(size, OpenCLMemoryObject::WriteOnly);
OpenCLEvent event = buffer.ReadAsync(offset, data, size);
...
event.WaitForFinished();

The events specified in OpenCLEventList act as synchronization points. The OpenCLEventList are used to control execution order:

OpenCLBuffer buffer = context->CreateBufferDevice(size, OpenCLMemoryObject::WriteOnly);
OpenCLEvent event1 = buffer.ReadAsync(offset1, data1, size1);
OpenCLEvent event2 = buffer.ReadAsync(offset2, data2, size2);
 
OpenCLEventList events;
events << event1 << event2;
OpenCLEvent event3 = buffer.ReadAsync(offset3, data3, size3, events);
...
event3.WaitForFinished();

The OpenCL functions that are submitted to a command-queue are enqueued in the order the calls are made but can be configured to execute in-order or out-of-order. The properties argument in context->CreateCommandQueue() can be used to specify the execution order.

If the {CL_QUEUE_OUT_OF_ORDER_EXEC_MODE_ENABLE} property of a command-queue is not set, the commands enqueued to a command-queue execute in order. For example, if an application calls buffer.ReadAsync() to execute event1 followed by a buffer.ReadAsync() to execute event2, the application can assume that event1 finishes first and then event2 is executed. If the OpenCLCommandQueue::IsOutOfOrder() property of a command-queue is set, then there is no guarantee that event1 will finish before event2 starts execution.

See also

OpenCLCommandQueue::IsOutOfOrder(), OpenCLEventList, OpenCLUserEvent

Definition at line 92 of file itkOpenCLEvent.h.

Inheritance diagram for itk::OpenCLEvent:

Public Types
typedef OpenCLEvent	Self

Public Member Functions
cl_command_type	GetCommandType () const
cl_event	GetEventId () const
cl_ulong	GetFinishTime () const
cl_ulong	GetQueueTime () const
cl_ulong	GetRunTime () const
cl_int	GetStatus () const
cl_ulong	GetSubmitTime () const
bool	IsComplete () const
bool	IsError () const
bool	IsNull () const
bool	IsQueued () const
bool	IsRunning () const
bool	IsSubmitted () const
	OpenCLEvent ()
	OpenCLEvent (const cl_event id)
	OpenCLEvent (const OpenCLEvent &other)
OpenCLEvent &	operator= (const OpenCLEvent &other)
cl_int	SetCallback (cl_int type, void(CL_CALLBACK *pfn_notify)(cl_event, cl_int, void *), void *user_data=nullptr)
cl_int	WaitForFinished ()
	~OpenCLEvent ()

Private Attributes
cl_event	m_Id

Friends
class	OpenCLUserEvent

Member Typedef Documentation

Self

typedef OpenCLEvent itk::OpenCLEvent::Self

Standard class typedefs.

Definition at line 97 of file itkOpenCLEvent.h.

Constructor & Destructor Documentation

OpenCLEvent() [1/3]

itk::OpenCLEvent::OpenCLEvent

(

)

Constructs a null OpenCL event object.

OpenCLEvent() [2/3]

itk::OpenCLEvent::OpenCLEvent

(

const cl_event

id

)

Constructs an OpenCL event object from the identifier id. This class takes over ownership of id and will release it in the destructor.

OpenCLEvent() [3/3]

itk::OpenCLEvent::OpenCLEvent

(

const OpenCLEvent &

other

)

Constructs a copy of other. The {clRetainEvent()} function will be called to update the reference count on GetEventId().

~OpenCLEvent()

itk::OpenCLEvent::~OpenCLEvent

(

)

Releases this OpenCL event object by calling {clReleaseEvent()}.

Member Function Documentation

GetCommandType()

cl_command_type itk::OpenCLEvent::GetCommandType

(

)

const

Returns the type of command that generated this event.

GetEventId()

cl_event itk::OpenCLEvent::GetEventId ( ) const

inline

Returns the OpenCL identifier for this event.

Definition at line 123 of file itkOpenCLEvent.h.

GetFinishTime()

cl_ulong itk::OpenCLEvent::GetFinishTime

(

)

const

Returns the device time in nanoseconds when the command finished running on the device. The return value is only valid if the command has finished execution and profiling was enabled on the command queue.

See also

GetQueueTime(), GetSubmitTime(), GetRunTime(), IsComplete()

GetQueueTime()

cl_ulong itk::OpenCLEvent::GetQueueTime

(

)

const

Returns the device time in nanoseconds when the command was queued for execution on the host. The return value is only valid if the command has finished execution and profiling was enabled on the command queue.

See also

GetSubmitTime(), GetRunTime(), GetFinishTime(), IsQueued()

GetRunTime()

cl_ulong itk::OpenCLEvent::GetRunTime

(

)

const

Returns the device time in nanoseconds when the command started running on the device. The return value is only valid if the command has finished execution and profiling was enabled on the command queue.

See also

GetQueueTime(), GetSubmitTime(), GetFinishTime(), IsRunning()

GetStatus()

cl_int itk::OpenCLEvent::GetStatus

(

)

const

Returns the status of this event, which is an error code or one of {CL_QUEUED}, {CL_SUBMITTED}, {CL_RUNNING} or {CL_COMPLETE}.

See also

IsQueued(), IsSubmitted(), IsRunning(), IsComplete(), IsError()

GetSubmitTime()

cl_ulong itk::OpenCLEvent::GetSubmitTime

(

)

const

Returns the device time in nanoseconds when the command was submitted by the host for execution on the device. The return value is only valid if the command has finished execution and profiling was enabled on the command queue.

See also

GetQueueTime(), GetRunTime(), GetFinishTime(), IsSubmitted()

IsComplete()

bool itk::OpenCLEvent::IsComplete ( ) const

inline

Returns true if the command associated with this OpenCL event has completed execution on the device.

See also

IsQueued(), IsSubmitted(), IsRunning(), IsError(), GetStatus()

Definition at line 144 of file itkOpenCLEvent.h.

IsError()

bool itk::OpenCLEvent::IsError ( ) const

inline

Returns true if an error has occurred on this OpenCL event.

See also

IsQueued(), IsSubmitted(), IsRunning(), IsComplete(), GetStatus()

Definition at line 148 of file itkOpenCLEvent.h.

IsNull()

bool itk::OpenCLEvent::IsNull ( ) const

inline

Returns true if this OpenCL event object is null, false otherwise.

Definition at line 120 of file itkOpenCLEvent.h.

IsQueued()

bool itk::OpenCLEvent::IsQueued ( ) const

inline

Returns true if the command associated with this OpenCL event has been queued for execution on the host, but has not yet been submitted to the device yet.

See also

IsSubmitted(), IsRunning(), IsComplete(), IsError(), GetStatus()

Definition at line 129 of file itkOpenCLEvent.h.

IsRunning()

bool itk::OpenCLEvent::IsRunning ( ) const

inline

Returns true if the command associated with this OpenCL event is running on the device, but has not yet finished.

See also

IsQueued(), IsSubmitted(), IsComplete(), IsError(), GetStatus()

Definition at line 139 of file itkOpenCLEvent.h.

IsSubmitted()

bool itk::OpenCLEvent::IsSubmitted ( ) const

inline

Returns true if the command associated with this OpenCL event has been submitted for execution on the device yet, but is not yet running.

See also

IsQueued(), IsRunning(), IsComplete(), IsError(), GetStatus()

Definition at line 134 of file itkOpenCLEvent.h.

operator=()

OpenCLEvent & itk::OpenCLEvent::operator=

(

const OpenCLEvent &

other

)

Assigns other to this OpenCL event object. The current GetEventId() will be released with {clReleaseEvent()}, and the new GetEventId() will be retained with {clRetainEvent()}.

SetCallback()

cl_int itk::OpenCLEvent::SetCallback	(	cl_int	type,
		void(CL_CALLBACK *pfn_notify)(cl_event, cl_int, void *)	,
		void *	user_data = nullptr
	)

Registers a user callback function for a specific command execution status. 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.

WaitForFinished()

cl_int itk::OpenCLEvent::WaitForFinished

(

)

Waits for this event to be signaled as finished. The calling thread is blocked until the event is signaled. This function returns immediately if the event is null.

See also

IsComplete(), OpenCLEventList::WaitForFinished()

Friends And Related Function Documentation

OpenCLUserEvent

friend class OpenCLUserEvent

friend

friends from OpenCL core

Definition at line 205 of file itkOpenCLEvent.h.

Field Documentation

m_Id

cl_event itk::OpenCLEvent::m_Id

private

Definition at line 202 of file itkOpenCLEvent.h.