Command queue. More...

#include <commandqueue.h>

Inheritance diagram for Coal::CommandQueue:

Collaboration diagram for Coal::CommandQueue:

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
DeviceInterface *	p_device
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
	)

Definition at line 50 of file commandqueue.cpp.

References checkProperties(), Coal::Context::hasDevice(), p_event_list_cond, and p_event_list_mutex.

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.

Returns:: 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.

Note:: Retains all the events

Parameters:

count number of events in the event queue

Returns:: 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);

Parameters:

param_name	Name of the property to retrieve
param_value_size	Size of the application-allocated buffer in which to put the value.
param_value	Pointer to an application-allocated buffer where the property data will be stored. Ignored if NULL.
param_value_size_ret	Size of the value retrieved, ignored if NULL.

Returns:: 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.

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.

Parameters:

event event to be queued

Returns:: 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.

Note:: This function is deprecated and only there for OpenCL 1.0 compatibility

Parameters:

properties	property to enable or disable
enable	true to enable the property, false to disable it
old_properties	old value of the properties, ignored if NULL