Clover Git
OpenCL 1.1 software implementation
Public Member Functions | Private Attributes

Coal::CommandQueue Class Reference

Command queue. More...

#include <commandqueue.h>

Inheritance diagram for Coal::CommandQueue:
Collaboration diagram for Coal::CommandQueue:

List of all members.

Public Member Functions

 CommandQueue (Context *ctx, DeviceInterface *device, cl_command_queue_properties properties, cl_int *errcode_ret)
 ~CommandQueue ()
cl_int queueEvent (Event *event)
 Queue an event.
cl_int info (cl_command_queue_info param_name, size_t param_value_size, void *param_value, size_t *param_value_size_ret) const
 Information about the command queue.
cl_int setProperty (cl_command_queue_properties properties, cl_bool enable, cl_command_queue_properties *old_properties)
 Set properties of the command queue.
cl_int checkProperties () const
 Check the properties given.
void pushEventsOnDevice ()
 Push events on the device.
void cleanEvents ()
 Remove from the event list completed events.
void flush ()
 Flush the command queue.
void finish ()
 Finish the command queue.
Event ** events (unsigned int &count)
 Return all the events in the command queue.

Private Attributes

cl_command_queue_properties p_properties
std::list< Event * > p_events
pthread_mutex_t p_event_list_mutex
pthread_cond_t p_event_list_cond
bool p_flushed

Detailed Description

Command queue.

This class holds a list of events that will be pushed on a given device.

More details are given on the Command Queues, Events and Worker Threads page.

Definition at line 58 of file commandqueue.h.

Constructor & Destructor Documentation

CommandQueue::CommandQueue ( Context ctx,
DeviceInterface device,
cl_command_queue_properties  properties,
cl_int *  errcode_ret 
CommandQueue::~CommandQueue ( )

Definition at line 71 of file commandqueue.cpp.

References p_event_list_cond, and p_event_list_mutex.

Member Function Documentation

cl_int CommandQueue::checkProperties ( ) const

Check the properties given.

CL_SUCCESS if they are valid, an error code otherwise

Definition at line 142 of file commandqueue.cpp.

References Coal::DeviceInterface::info(), p_device, and p_properties.

Referenced by CommandQueue(), and setProperty().

void CommandQueue::cleanEvents ( )

Remove from the event list completed events.

This function is called periodically to clean the event list from completed events.

It is needed to do that out of pushEventsOnDevice() as deleting event may dereference() this command queue, and also delete it. It would produce crashes.

Definition at line 223 of file commandqueue.cpp.

References clReleaseEvent(), Coal::Event::Complete, p_event_list_cond, p_event_list_mutex, p_events, Coal::Object::references(), and Coal::Object::setReleaseParent().

Referenced by finish(), and worker().

Event ** CommandQueue::events ( unsigned int &  count)

Return all the events in the command queue.

Retains all the events
countnumber of events in the event queue
events currently in the event queue

Definition at line 373 of file commandqueue.cpp.

References p_event_list_mutex, p_events, and Coal::Object::reference().

void CommandQueue::finish ( )

Finish the command queue.

Pushes the events like flush() but also wait for them to be completed before returning.

Definition at line 180 of file commandqueue.cpp.

References cleanEvents(), p_event_list_cond, p_event_list_mutex, and p_events.

void CommandQueue::flush ( )

Flush the command queue.

Pushes all the events on the device, and then return. The event don't need to be completed after this call.

Definition at line 169 of file commandqueue.cpp.

References p_event_list_cond, p_event_list_mutex, and p_flushed.

cl_int CommandQueue::info ( cl_command_queue_info  param_name,
size_t  param_value_size,
void *  param_value,
size_t *  param_value_size_ret 
) const

Information about the command queue.

This function is used to retrieve information about an object. Sometimes, the size of the data retrieved is unknown (for example, a string). The application can call this function twice, the first time to get the size, then it allocates a buffer, and finally get the data.

 const char *string = 0;
 size_t len;

 object->info(FOO_PROPERTY_STRING, 0, 0, &len);
 string = std::malloc(len);
 object->info(FOO_PROPERTY_STRING, len, string, 0);
param_nameName of the property to retrieve
param_value_sizeSize of the application-allocated buffer in which to put the value.
param_valuePointer to an application-allocated buffer where the property data will be stored. Ignored if NULL.
param_value_size_retSize of the value retrieved, ignored if NULL.
CL_SUCCESS in case of success, otherwise a CL error code.

Definition at line 78 of file commandqueue.cpp.

References p_device, p_properties, Coal::Object::parent(), Coal::Object::references(), and SIMPLE_ASSIGN.

Referenced by Coal::BufferEvent::BufferEvent(), Coal::CopyBufferEvent::CopyBufferEvent(), Coal::CopyBufferRectEvent::CopyBufferRectEvent(), Coal::KernelEvent::KernelEvent(), Coal::NativeKernelEvent::NativeKernelEvent(), and worker().

void CommandQueue::pushEventsOnDevice ( )

Push events on the device.

This function implements a big part of what is described in Command Queues, Events and Worker Threads .

It is called by Coal::Event::setStatus() when an event is completed, or by queueEvent(). Its purpose is to explore the list of queued events (p_events) and to call Coal::DeviceInterface::pushEvent() for each event meeting its push conditions.


If the command queue has the CL_OUT_OF_ORDER_EXEC_MODE_ENABLE property disabled, an event can be pushed only if all the previous ones in the list are completed with success. This way, an event must be completed before any other can be pushed. This ensures in-order execution.

If this property is enable, more complex heuristics are used.

The event list p_events is explored from top to bottom. At each loop iteration, checks are performed to see if the event can be pushed.

  • When a Coal::BarrierEvent is encountered, no more events can be pushed, except if the Coal::BarrierEvent is the first in the list, as that means there are no other events that can be pushed, so the barrier can go away
  • All events that are already pushed or finished are skipped
  • The wait list of the event is then explored to ensure that all its dependencies are met.
  • Finally, if the events passes all the tests, it is either pushed on the device, or simply set to Coal::Event::Complete if it's a dummy event (see Coal::Event::isDummy()).

Definition at line 260 of file commandqueue.cpp.

References Coal::Event::Barrier, Coal::Event::Complete, p_device, p_event_list_cond, p_event_list_mutex, p_events, p_flushed, p_properties, Coal::DeviceInterface::pushEvent(), Coal::Event::Queued, Coal::Event::Submit, Coal::Event::Submitted, Coal::Event::waitEvents(), and Coal::Event::WaitForEvents.

Referenced by queueEvent().

cl_int CommandQueue::queueEvent ( Event event)

Queue an event.

eventevent to be queued
CL_SUCCESS if success, otherwise an error code

Definition at line 196 of file commandqueue.cpp.

References Coal::DeviceInterface::initEventDeviceData(), p_device, p_event_list_mutex, p_events, p_flushed, p_properties, pushEventsOnDevice(), and Coal::Event::Queue.

Referenced by queueEvent().

cl_int CommandQueue::setProperty ( cl_command_queue_properties  properties,
cl_bool  enable,
cl_command_queue_properties *  old_properties 

Set properties of the command queue.

This function is deprecated and only there for OpenCL 1.0 compatibility
propertiesproperty to enable or disable
enabletrue to enable the property, false to disable it
old_propertiesold value of the properties, ignored if NULL
CL_SUCCESS if all is good, an error code if properties is invalid

Definition at line 127 of file commandqueue.cpp.

References checkProperties(), and p_properties.

Member Data Documentation

Definition at line 178 of file commandqueue.h.

Referenced by checkProperties(), info(), pushEventsOnDevice(), and queueEvent().

pthread_cond_t Coal::CommandQueue::p_event_list_cond [private]
pthread_mutex_t Coal::CommandQueue::p_event_list_mutex [private]
std::list<Event *> Coal::CommandQueue::p_events [private]

Definition at line 181 of file commandqueue.h.

Referenced by cleanEvents(), events(), finish(), pushEventsOnDevice(), and queueEvent().

Definition at line 184 of file commandqueue.h.

Referenced by flush(), pushEventsOnDevice(), and queueEvent().

cl_command_queue_properties Coal::CommandQueue::p_properties [private]

Definition at line 179 of file commandqueue.h.

Referenced by checkProperties(), info(), pushEventsOnDevice(), queueEvent(), and setProperty().

The documentation for this class was generated from the following files:
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Defines