go home Home | Main Page | Modules | Namespace List | Class Hierarchy | Alphabetical List | Data Structures | File List | Namespace Members | Data Fields | Globals | Related Pages
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);
...
The OpenCLBuffer class represents an OpenCL buffer object.
OpenCLEvent ReadAsync(void *data, const std::vcl_size_t size, const OpenCLEventList &event_list=OpenCLEventList(), const std::vcl_size_t offset=0)
OpenCLEvent class represents an OpenCL event object.
cl_int 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);
events << event1 << event2;
OpenCLEvent event3 = buffer.ReadAsync(offset3, data3, size3, events);
...
event3.WaitForFinished();
OpenCLEventList class represents a list of OpenCLEvent objects.

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

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)
 
OpenCLEventoperator= (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

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.



Generated on 2024-07-17 for elastix by doxygen 1.11.0 (9b424b03c9833626cd435af22a444888fbbb192d) elastix logo