Command queue wrapper

The command queue wrapper module provides functionality for simple handling of OpenCL command queue objects. More...

Macros
#define	ccl_queue_get_info(cq, param_name, err)
	Get a CCLWrapperInfo command queue information object. More...
#define	ccl_queue_get_info(cq, param_name, err)
	Get a CCLWrapperInfo command queue information object. More...
#define	ccl_queue_get_info_array(cq, param_name, param_type, err)
	Macro which returns an array command queue information value. More...
#define	ccl_queue_get_info_array(cq, param_name, param_type, err)
	Macro which returns an array command queue information value. More...
#define	ccl_queue_get_info_scalar(cq, param_name, param_type, err)
	Macro which returns a scalar command queue information value. More...
#define	ccl_queue_get_info_scalar(cq, param_name, param_type, err)
	Macro which returns a scalar command queue information value. More...
#define	ccl_queue_ref(cq)   ccl_wrapper_ref((CCLWrapper*) cq)
	Increase the reference count of the command queue object. More...
#define	ccl_queue_ref(cq)   ccl_wrapper_ref((CCLWrapper*) cq)
	Increase the reference count of the command queue object. More...
#define	ccl_queue_unref(cq)   ccl_queue_destroy(cq)
	Alias to ccl_queue_destroy(). More...
#define	ccl_queue_unref(cq)   ccl_queue_destroy(cq)
	Alias to ccl_queue_destroy(). More...
#define	ccl_queue_unwrap(cq)   ((cl_command_queue) ccl_wrapper_unwrap((CCLWrapper*) cq))
	Get the OpenCL command queue object. More...
#define	ccl_queue_unwrap(cq)   ((cl_command_queue) ccl_wrapper_unwrap((CCLWrapper*) cq))
	Get the OpenCL command queue object. More...

Typedefs
typedef struct ccl_queue	CCLQueue
	Command queue wrapper class.

Functions
CCLEvent *	ccl_enqueue_barrier (CCLQueue *cq, CCLEventWaitList *evt_wait_lst, CCLErr **err)
	Enqueues a barrier command on the given command queue. More...
CCLEvent *	ccl_enqueue_marker (CCLQueue *cq, CCLEventWaitList *evt_wait_lst, CCLErr **err)
	Enqueues a marker command on the given command queue. More...
void	ccl_queue_destroy (CCLQueue *cq)
	Decrements the reference count of the command queue wrapper object. More...
cl_bool	ccl_queue_finish (CCLQueue *cq, CCLErr **err)
	Blocks until all previously queued OpenCL commands in a command-queue are issued to the associated device and have completed. More...
cl_bool	ccl_queue_flush (CCLQueue *cq, CCLErr **err)
	Issues all previously queued commands in a command queue to the associated device. More...
void	ccl_queue_gc (CCLQueue *cq)
	Release all events associated with the command queue. More...
CCLContext *	ccl_queue_get_context (CCLQueue *cq, CCLErr **err)
	Get the context associated with the given command queue wrapper object. More...
CCLDevice *	ccl_queue_get_device (CCLQueue *cq, CCLErr **err)
	Get the device associated with the given command queue wrapper object. More...
CCLQueue *	ccl_queue_new (CCLContext *ctx, CCLDevice *dev, cl_command_queue_properties properties, CCLErr **err)
	Create a new command queue wrapper object. More...
CCLQueue *	ccl_queue_new_full (CCLContext *ctx, CCLDevice *dev, const cl_queue_properties *prop_full, CCLErr **err)
	Create a new command queue wrapper object. More...
CCLQueue *	ccl_queue_new_wrap (cl_command_queue command_queue)
	Get the command queue wrapper for the given OpenCL command queue. More...

Detailed Description

The command queue wrapper module provides functionality for simple handling of OpenCL command queue objects.

Queue wrappers can be instantiated with the ccl_queue_new() and ccl_queue_new_full() constructors. While both constructors can be used with any OpenCL version, the later is targeted for OpenCL >= 2.0, exposing features such as on-device queues to client code. If OpenCL >= 2.0 features are requested for platforms which do not support them, a warning will be logged and the queue will be created without the unsupported features.

Instantiation and destruction of queue wrappers follows the cf4ocl new/destroy rule; as such, queues should be freed with the ccl_queue_destroy() destructor.

Queue wrappers created with the CL_QUEUE_PROFILING_ENABLE property can be automatically profiled with the profiler module.

Information about queue objects can be fetched using the info macros:

• ccl_queue_get_info_scalar()
• ccl_queue_get_info_array()
• ccl_queue_get_info()

Example:

    /* Wrappers for OpenCL objects. */
    CCLQueue* queue;
    /* Error handling object (must be initialized to NULL). */
    CCLErr* err = NULL;

    /* Create a command queue. */
    queue = ccl_queue_new(ctx, dev, 0, &err);

    /* Release wrappers. */
    ccl_queue_destroy(queue);

Macro Definition Documentation

#define ccl_queue_get_info	(		cq,
			param_name,
			err
	)

Value:

ccl_wrapper_get_info((CCLWrapper*) cq, NULL, param_name, 0, \
        CCL_INFO_QUEUE, CL_FALSE, err)

Get a CCLWrapperInfo command queue information object.

Parameters

[in]	cq	The command queue wrapper object.
[in]	param_name	Name of information/parameter to get.
[out]	err	Return location for a CCLErr object, or NULL if error reporting is to be ignored.

Returns

The requested command queue information object. This object will be automatically freed when the command queue wrapper object is destroyed. If an error occurs, NULL is returned.

Definition at line 163 of file ccl_queue_wrapper.h.

#define ccl_queue_get_info	(		cq,
			param_name,
			err
	)

Value:

ccl_wrapper_get_info((CCLWrapper*) cq, NULL, param_name, 0, \
        CCL_INFO_QUEUE, CL_FALSE, err)

Get a CCLWrapperInfo command queue information object.

Parameters

[in]	cq	The command queue wrapper object.
[in]	param_name	Name of information/parameter to get.
[out]	err	Return location for a CCLErr object, or NULL if error reporting is to be ignored.

Returns

The requested command queue information object. This object will be automatically freed when the command queue wrapper object is destroyed. If an error occurs, NULL is returned.

Definition at line 163 of file ccl_queue_wrapper.h.

#define ccl_queue_get_info_array	(		cq,
			param_name,
			param_type,
			err
	)

Value:

(param_type) ccl_wrapper_get_info_value((CCLWrapper*) cq, \
        NULL, param_name, sizeof(param_type), CCL_INFO_QUEUE, CL_FALSE, err)

Macro which returns an array command queue information value.

Use with care. In case an error occurs, NULL is returned, which might be ambiguous if NULL is a valid return value. In this case, it is necessary to check the error object.

Parameters

[in]	cq	The command queue wrapper object.
[in]	param_name	Name of information/parameter to get value of.
[in]	param_type	Type of parameter (e.g. char*, size_t*, etc.).
[out]	err	Return location for a CCLErr object, or NULL if error reporting is to be ignored.

Returns

The requested command queue information value. This value will be automatically freed when the command queue wrapper object is destroyed. If an error occurs, NULL is returned.

Definition at line 203 of file ccl_queue_wrapper.h.

#define ccl_queue_get_info_array	(		cq,
			param_name,
			param_type,
			err
	)

Value:

(param_type) ccl_wrapper_get_info_value((CCLWrapper*) cq, \
        NULL, param_name, sizeof(param_type), CCL_INFO_QUEUE, CL_FALSE, err)

Macro which returns an array command queue information value.

Use with care. In case an error occurs, NULL is returned, which might be ambiguous if NULL is a valid return value. In this case, it is necessary to check the error object.

Parameters

[in]	cq	The command queue wrapper object.
[in]	param_name	Name of information/parameter to get value of.
[in]	param_type	Type of parameter (e.g. char*, size_t*, etc.).
[out]	err	Return location for a CCLErr object, or NULL if error reporting is to be ignored.

Returns

The requested command queue information value. This value will be automatically freed when the command queue wrapper object is destroyed. If an error occurs, NULL is returned.

Definition at line 203 of file ccl_queue_wrapper.h.

#define ccl_queue_get_info_scalar	(		cq,
			param_name,
			param_type,
			err
	)

Value:

*((param_type*) ccl_wrapper_get_info_value((CCLWrapper*) cq, \
        NULL, param_name, sizeof(param_type), CCL_INFO_QUEUE, CL_FALSE, err))

Macro which returns a scalar command queue information value.

Use with care. In case an error occurs, zero is returned, which might be ambiguous if zero is a valid return value. In this case, it is necessary to check the error object.

Parameters

[in]	cq	The command queue wrapper object.
[in]	param_name	Name of information/parameter to get value of.
[in]	param_type	Type of parameter (e.g. cl_uint, size_t, etc.).
[out]	err	Return location for a CCLErr object, or NULL if error reporting is to be ignored.

Returns

The requested command queue information value. This value will be automatically freed when the command queue wrapper object is destroyed. If an error occurs, zero is returned.

Definition at line 183 of file ccl_queue_wrapper.h.

#define ccl_queue_get_info_scalar	(		cq,
			param_name,
			param_type,
			err
	)

Value:

*((param_type*) ccl_wrapper_get_info_value((CCLWrapper*) cq, \
        NULL, param_name, sizeof(param_type), CCL_INFO_QUEUE, CL_FALSE, err))

Macro which returns a scalar command queue information value.

Use with care. In case an error occurs, zero is returned, which might be ambiguous if zero is a valid return value. In this case, it is necessary to check the error object.

Parameters

[in]	cq	The command queue wrapper object.
[in]	param_name	Name of information/parameter to get value of.
[in]	param_type	Type of parameter (e.g. cl_uint, size_t, etc.).
[out]	err	Return location for a CCLErr object, or NULL if error reporting is to be ignored.

Returns

The requested command queue information value. This value will be automatically freed when the command queue wrapper object is destroyed. If an error occurs, zero is returned.

Definition at line 183 of file ccl_queue_wrapper.h.

#define ccl_queue_ref

(

cq

)

ccl_wrapper_ref((CCLWrapper*) cq)

Increase the reference count of the command queue object.

Parameters

[in]

cq

The command queue wrapper object.

Definition at line 212 of file ccl_queue_wrapper.h.

#define ccl_queue_ref

(

cq

)

ccl_wrapper_ref((CCLWrapper*) cq)

Increase the reference count of the command queue object.

Parameters

[in]

cq

The command queue wrapper object.

Definition at line 212 of file ccl_queue_wrapper.h.

#define ccl_queue_unref

(

cq

)

ccl_queue_destroy(cq)

Alias to ccl_queue_destroy().

Parameters

[in]

cq

Command queue wrapper object to destroy if reference count is 1, otherwise just decrement the reference count.

Definition at line 221 of file ccl_queue_wrapper.h.

#define ccl_queue_unref

(

cq

)

ccl_queue_destroy(cq)

Alias to ccl_queue_destroy().

Parameters

[in]

cq

Command queue wrapper object to destroy if reference count is 1, otherwise just decrement the reference count.

Definition at line 221 of file ccl_queue_wrapper.h.

#define ccl_queue_unwrap

(

cq

)

((cl_command_queue) ccl_wrapper_unwrap((CCLWrapper*) cq))

Get the OpenCL command queue object.

Parameters

[in]

cq

The command queue wrapper object.

Returns

The OpenCL command queue object.

Definition at line 229 of file ccl_queue_wrapper.h.

#define ccl_queue_unwrap

(

cq

)

((cl_command_queue) ccl_wrapper_unwrap((CCLWrapper*) cq))

Get the OpenCL command queue object.

Parameters

[in]

cq

The command queue wrapper object.

Returns

The OpenCL command queue object.

Definition at line 229 of file ccl_queue_wrapper.h.

Function Documentation

CCLEvent * ccl_enqueue_barrier	(	CCLQueue *	cq,
		CCLEventWaitList *	evt_wait_lst,
		CCLErr **	err
	)

Enqueues a barrier command on the given command queue.

The barrier can wait on a given list of events, or wait until all previous enqueued commands have completed if evt_wait_lst is NULL. A marker event is returned, which can be used to identify this barrier command later on. This function is a wrapper for the clEnqueueBarrierWithWaitList() OpenCL function (OpenCL >= 1.2).

For platforms which do not support clEnqueueBarrierWithWaitList() (OpenCL <= 1.1), this function implements the same functionality by using the deprecated clEnqueueBarrier(), clEnqueueWaitForEvents() and clEnqueueMarker() OpenCL functions. If evt_wait_lst is NULL, clEnqueueBarrier() and clEnqueueMarker() are called in sequence; otherwise (if there are events which must be waited on), clEnqueueWaitForEvents() and clEnqueueMarker() are called in sequence. The calls on clEnqueueMarker() allow to fire a marker event (not produced by either clEnqueueBarrier() or clEnqueueWaitForEvents()). This marker event can then be used to queue a wait on.

Parameters

[in]	cq	Command queue wrapper object.
[in,out]	evt_wait_lst	List of events that need to complete before this command can be executed. The list will be cleared and can be reused by client code.
[out]	err	Return location for a CCLErr object, or NULL if error reporting is to be ignored.

Returns

An event wrapper object that identifies this particular command.

Examples:

canon.c.

Definition at line 771 of file ccl_queue_wrapper.c.

CCLEvent * ccl_enqueue_marker	(	CCLQueue *	cq,
		CCLEventWaitList *	evt_wait_lst,
		CCLErr **	err
	)

Enqueues a marker command on the given command queue.

The marker can wait on a given list of events, or wait until all previous enqueued commands have completed if evt_wait_lst is NULL. This function is a wrapper for the clEnqueueMarkerWithWaitList() OpenCL function (OpenCL >= 1.2).

For platforms which do not support clEnqueueMarkerWithWaitList() (OpenCL <= 1.1), this function uses the deprecated clEnqueueMarker() OpenCL function. However, in this case evt_wait_lst must be NULL, because clEnqueueMarker() does not support markers with wait lists. If evt_wait_lst is not NULL, it will be ignored (i.e. the marker will only fire an event after all commands queued before the marker command are complete) and a warning will be generated.

Note

Requires OpenCL >= 1.2 if evt_wait_lst is not NULL.

Parameters

[in]	cq	Command queue wrapper object.
[in,out]	evt_wait_lst	List of events that need to complete before this command can be executed. The list will be cleared and can be reused by client code. Must be NULL if OpenCL platform version is <= 1.1.
[out]	err	Return location for a CCLErr object, or NULL if error reporting is to be ignored.

Returns

An event wrapper object that identifies this particular command.

Definition at line 951 of file ccl_queue_wrapper.c.

void ccl_queue_destroy

(

CCLQueue *

cq

)

Decrements the reference count of the command queue wrapper object.

If it reaches 0, the command queue wrapper object is destroyed.

Parameters

[in]

cq

The command queue wrapper object.

Examples:

ca.c, canon.c, image_fill.c, and image_filter.c.

Definition at line 353 of file ccl_queue_wrapper.c.

cl_bool ccl_queue_finish	(	CCLQueue *	cq,
		CCLErr **	err
	)

Blocks until all previously queued OpenCL commands in a command-queue are issued to the associated device and have completed.

This function is a wrapper for the clFinish() OpenCL function.

Parameters

[in]	cq	The command queue wrapper object.
[out]	err	Return location for a CCLErr object, or NULL if error reporting is to be ignored.

Returns

CL_TRUE if operation is successful, or CL_FALSE otherwise.

Definition at line 612 of file ccl_queue_wrapper.c.

cl_bool ccl_queue_flush	(	CCLQueue *	cq,
		CCLErr **	err
	)

Issues all previously queued commands in a command queue to the associated device.

This function is a wrapper for the clFlush() OpenCL function.

Parameters

[in]	cq	The command queue wrapper object.
[out]	err	Return location for a CCLErr object, or NULL if error reporting is to be ignored.

Returns

CL_TRUE if operation is successful, or CL_FALSE otherwise.

Definition at line 577 of file ccl_queue_wrapper.c.

void ccl_queue_gc

(

CCLQueue *

cq

)

Release all events associated with the command queue.

cf4ocl command queue wrappers internally keep events for profiling purposes and simpler handling of event associated memory. However, a very large number of events can have an impact on utilized memory. In such cases, this function can be used to periodically release these events.

This function is also called by the ccl_prof_calc() function, i.e., the queue events are released after the profiling analysis is performed.

Parameters

[in]

cq

The command queue wrapper object.

Definition at line 652 of file ccl_queue_wrapper.c.

CCLContext * ccl_queue_get_context	(	CCLQueue *	cq,
		CCLErr **	err
	)

Get the context associated with the given command queue wrapper object.

Parameters

[in]	cq	The command queue wrapper object.
[out]	err	Return location for a CCLErr object, or NULL if error reporting is to be ignored.

Returns

The context associated with the given command queue wrapper object, or NULL if an error occurs.

Definition at line 374 of file ccl_queue_wrapper.c.

CCLDevice * ccl_queue_get_device	(	CCLQueue *	cq,
		CCLErr **	err
	)

Get the device associated with the given command queue wrapper object.

Parameters

[in]	cq	The command queue wrapper object.
[out]	err	Return location for a CCLErr object, or NULL if error reporting is to be ignored.

Returns

The device associated with the given command queue wrapper object, or NULL if an error occurs.

Definition at line 427 of file ccl_queue_wrapper.c.

CCLQueue * ccl_queue_new	(	CCLContext *	ctx,
		CCLDevice *	dev,
		cl_command_queue_properties	properties,
		CCLErr **	err
	)

Create a new command queue wrapper object.

This function accepts a cl_command_queue_properties bitfield of command queue properties, mimicking the behavior of the OpenCL clCreateCommandQueue() constructor (deprecated in OpenCL 2.0). The exact OpenCL constructor used is automatically selected based on the OpenCL version of the underlying platform (i.e. clCreateCommandQueue() if OpenCL <= 1.2, or clCreateCommandQueueWithProperties() for OpenCL >= 2.0).

To specify OpenCL >= 2.0 only features, such as on-device queue size, use the ccl_queue_new_full() constructor.

Parameters

[in]	ctx	Context wrapper object.
[in]	dev	Device wrapper object, must be associated with ctx.
[in]	properties	Bitfield of command queue properties.
[out]	err	Return location for a CCLErr object, or NULL if error reporting is to be ignored.

Returns

The CCLQueue wrapper for the given device and context, or NULL if an error occurs.

Examples:

ca.c, canon.c, image_fill.c, and image_filter.c.

Definition at line 333 of file ccl_queue_wrapper.c.

CCLQueue * ccl_queue_new_full	(	CCLContext *	ctx,
		CCLDevice *	dev,
		const cl_queue_properties *	prop_full,
		CCLErr **	err
	)

Create a new command queue wrapper object.

This function accepts a zero-terminated list of cl_queue_properties (instead of the cl_command_queue_properties bitfield used in the ccl_queue_new() constructor), following the behavior of the clCreateCommandQueueWithProperties() function (OpenCL >= 2.0). The exact OpenCL constructor used is automatically selected based on the OpenCL version of the underlying platform (i.e. clCreateCommandQueue() if OpenCL <= 1.2, or clCreateCommandQueueWithProperties() for OpenCL >= 2.0). However, if OpenCL >= 2.0 only properties are specified and the underlying platform is OpenCL <= 1.2, a warning will be logged, and the queue will be created with OpenCL <= 1.2 properties only.

Parameters

[in]	ctx	Context wrapper object.
[in]	dev	Device wrapper object, must be associated with ctx.
[in]	prop_full	A zero-terminated list of cl_queue_properties.
[out]	err	Return location for a CCLErr object, or NULL if error reporting is to be ignored.

Returns

The CCLQueue wrapper for the given device and context, or NULL if an error occurs.

Definition at line 155 of file ccl_queue_wrapper.c.

CCLQueue * ccl_queue_new_wrap

(

cl_command_queue

command_queue

)

Get the command queue wrapper for the given OpenCL command queue.

If the wrapper doesn't exist, its created with a reference count of 1. Otherwise, the existing wrapper is returned and its reference count is incremented by 1.

This function will rarely be called from client code, except when clients wish to create the OpenCL command queue directly (using the clCreateCommandQueue() function) and then wrap the OpenCL command queue in a CCLQueue wrapper object.

Parameters

[in]

command_queue

The OpenCL command queue to be wrapped.

Returns

The CCLQueue wrapper for the given OpenCL command queue.

Definition at line 123 of file ccl_queue_wrapper.c.