#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:

[legend]

Public Types
using	Self = OpenCLEvent

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

using itk::OpenCLEvent::Self = OpenCLEvent

Standard class typedefs.

Definition at line 96 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 128 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 165 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 173 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 121 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 138 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 156 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 147 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 Symbol Documentation

◆ OpenCLUserEvent

friend class OpenCLUserEvent

friend

friends from OpenCL core

Definition at line 238 of file itkOpenCLEvent.h.

Field Documentation

◆ m_Id

cl_event itk::OpenCLEvent::m_Id

private

Definition at line 235 of file itkOpenCLEvent.h.

Detailed Description

Public Types

Public Member Functions

Private Attributes

Friends

Member Typedef Documentation

◆ Self

Constructor & Destructor Documentation

◆ OpenCLEvent() [1/3]

◆ OpenCLEvent() [2/3]

◆ OpenCLEvent() [3/3]

◆ ~OpenCLEvent()

Member Function Documentation

◆ GetCommandType()

◆ GetEventId()

◆ GetFinishTime()

◆ GetQueueTime()

◆ GetRunTime()

◆ GetStatus()

◆ GetSubmitTime()

◆ IsComplete()

◆ IsError()

◆ IsNull()

◆ IsQueued()

◆ IsRunning()

◆ IsSubmitted()

◆ operator=()

◆ SetCallback()

◆ WaitForFinished()

Friends And Related Symbol Documentation

◆ OpenCLUserEvent

Field Documentation

◆ m_Id