cf4ocl (C Framework for OpenCL)
v2.1.0
Object-oriented framework for developing and benchmarking OpenCL projects in C/C++
|
The event wrapper module provides functionality for simple handling of OpenCL event objects. More...
Modules | |
Event wait lists | |
This module provides simple management of event wait lists. | |
Macros | |
#define | ccl_event_get_info(evt, param_name, err) |
Get a CCLWrapperInfo event information object. More... | |
#define | ccl_event_get_info(evt, param_name, err) |
Get a CCLWrapperInfo event information object. More... | |
#define | ccl_event_get_info_array(evt, param_name, param_type, err) |
Macro which returns an array event information value. More... | |
#define | ccl_event_get_info_array(evt, param_name, param_type, err) |
Macro which returns an array event information value. More... | |
#define | ccl_event_get_info_scalar(evt, param_name, param_type, err) |
Macro which returns a scalar event information value. More... | |
#define | ccl_event_get_info_scalar(evt, param_name, param_type, err) |
Macro which returns a scalar event information value. More... | |
#define | ccl_event_get_profiling_info(evt, param_name, err) |
Get a CCLWrapperInfo event profiling information object. More... | |
#define | ccl_event_get_profiling_info(evt, param_name, err) |
Get a CCLWrapperInfo event profiling information object. More... | |
#define | ccl_event_get_profiling_info_array(evt, param_name, param_type, err) |
Macro which returns an array event profiling information value. More... | |
#define | ccl_event_get_profiling_info_array(evt, param_name, param_type, err) |
Macro which returns an array event profiling information value. More... | |
#define | ccl_event_get_profiling_info_scalar(evt, param_name, param_type, err) |
Macro which returns a scalar event profiling information value. More... | |
#define | ccl_event_get_profiling_info_scalar(evt, param_name, param_type, err) |
Macro which returns a scalar event profiling information value. More... | |
#define | ccl_event_ref(evt) ccl_wrapper_ref((CCLWrapper*) evt) |
Increase the reference count of the event object. More... | |
#define | ccl_event_ref(evt) ccl_wrapper_ref((CCLWrapper*) evt) |
Increase the reference count of the event object. More... | |
#define | ccl_event_unref(evt) ccl_event_destroy(evt) |
Alias to ccl_event_destroy(). More... | |
#define | ccl_event_unref(evt) ccl_event_destroy(evt) |
Alias to ccl_event_destroy(). More... | |
#define | ccl_event_unwrap(evt) ((cl_event) ccl_wrapper_unwrap((CCLWrapper*) evt)) |
Get the OpenCL event object. More... | |
#define | ccl_event_unwrap(evt) ((cl_event) ccl_wrapper_unwrap((CCLWrapper*) evt)) |
Get the OpenCL event object. More... | |
Typedefs | |
typedef void(* | ccl_event_callback )(cl_event event, cl_int event_command_exec_status, void *user_data) |
Prototype for user event callback functions. More... | |
typedef void(* | ccl_event_callback )(cl_event event, cl_int event_command_exec_status, void *user_data) |
Prototype for user event callback functions. More... | |
typedef struct ccl_event | CCLEvent |
Event wrapper class. | |
Functions | |
void | ccl_event_destroy (CCLEvent *evt) |
Decrements the reference count of the event wrapper object. More... | |
cl_command_type | ccl_event_get_command_type (CCLEvent *evt, CCLErr **err) |
Get the command type which fired the given event. More... | |
const char * | ccl_event_get_final_name (CCLEvent *evt) |
Get the final event name for profiling purposes. More... | |
const char * | ccl_event_get_name (CCLEvent *evt) |
Get the event name for profiling purposes. More... | |
cl_uint | ccl_event_get_opencl_version (CCLEvent *evt, CCLErr **err) |
Get the OpenCL version of the platform associated with this event object. More... | |
CCLEvent * | ccl_event_new_wrap (cl_event event) |
Get the event wrapper for the given OpenCL event. More... | |
cl_bool | ccl_event_set_callback (CCLEvent *evt, cl_int command_exec_callback_type, ccl_event_callback pfn_notify, void *user_data, CCLErr **err) |
Wrapper for OpenCL clSetEventCallback() function. More... | |
void | ccl_event_set_name (CCLEvent *evt, const char *name) |
Set event name for profiling purposes. More... | |
cl_bool | ccl_event_wait (CCLEventWaitList *evt_wait_lst, CCLErr **err) |
Waits on the host thread for commands identified by events in the wait list to complete. More... | |
CCLEventWaitList * | ccl_event_wait_list_add (CCLEventWaitList *evt_wait_lst,...) |
Add event wrapper objects to an event wait list (variable argument list version). More... | |
CCLEventWaitList * | ccl_event_wait_list_add_v (CCLEventWaitList *evt_wait_lst, CCLEvent **evts) |
Add event wrapper objects to an event wait list (array version). More... | |
void | ccl_event_wait_list_clear (CCLEventWaitList *evt_wait_lst) |
Clears an event wait list. More... | |
CCLEvent * | ccl_user_event_new (CCLContext *ctx, CCLErr **err) |
Create a new user event. More... | |
cl_bool | ccl_user_event_set_status (CCLEvent *evt, cl_int execution_status, CCLErr **err) |
Sets the execution status of a user event object. More... | |
The event wrapper module provides functionality for simple handling of OpenCL event objects.
Typically, event wrappers will not be directly created by client code. They are returned by event producing functions (such as ccl_image_enqueue_write(), which wraps the clEnqueueWriteImage() OpenCL function). As such, and in accordance with the new/destroy rule, regular event wrappers objects should not be destroyed by client code. They are automatically released when the command queue wrapper where the event took place is destroyed. User events (OpenCL >= 1.1), created with the ccl_user_event_new() constructor, are the only exception. These are special events which allow applications to enqueue commands that wait on user-controlled occurrences before the command is executed by the device. These events should be destroyed with ccl_event_destroy().
The event wait list section provides additional information on how to use events to synchronize the execution of OpenCL commands. Events are also used by the profiler module, although indirectly via CCLQueue* wrappers, to profile and benchmark applications.
Information about event objects can be fetched using the respective info macros:
Three additional macros are provided for getting event profiling info. These work in the same way as the regular info macros:
#define ccl_event_get_info | ( | evt, | |
param_name, | |||
err | |||
) |
Get a CCLWrapperInfo event information object.
[in] | evt | The event 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. |
Definition at line 151 of file ccl_event_wrapper.h.
#define ccl_event_get_info | ( | evt, | |
param_name, | |||
err | |||
) |
Get a CCLWrapperInfo event information object.
[in] | evt | The event 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. |
Definition at line 151 of file ccl_event_wrapper.h.
#define ccl_event_get_info_array | ( | evt, | |
param_name, | |||
param_type, | |||
err | |||
) |
Macro which returns an array event 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.
[in] | evt | The event 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. |
Definition at line 191 of file ccl_event_wrapper.h.
#define ccl_event_get_info_array | ( | evt, | |
param_name, | |||
param_type, | |||
err | |||
) |
Macro which returns an array event 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.
[in] | evt | The event 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. |
Definition at line 191 of file ccl_event_wrapper.h.
#define ccl_event_get_info_scalar | ( | evt, | |
param_name, | |||
param_type, | |||
err | |||
) |
Macro which returns a scalar event 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.
[in] | evt | The event 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. |
Definition at line 171 of file ccl_event_wrapper.h.
#define ccl_event_get_info_scalar | ( | evt, | |
param_name, | |||
param_type, | |||
err | |||
) |
Macro which returns a scalar event 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.
[in] | evt | The event 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. |
Definition at line 171 of file ccl_event_wrapper.h.
#define ccl_event_get_profiling_info | ( | evt, | |
param_name, | |||
err | |||
) |
Get a CCLWrapperInfo event profiling information object.
[in] | evt | The event 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. |
Definition at line 206 of file ccl_event_wrapper.h.
#define ccl_event_get_profiling_info | ( | evt, | |
param_name, | |||
err | |||
) |
Get a CCLWrapperInfo event profiling information object.
[in] | evt | The event 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. |
Definition at line 206 of file ccl_event_wrapper.h.
#define ccl_event_get_profiling_info_array | ( | evt, | |
param_name, | |||
param_type, | |||
err | |||
) |
Macro which returns an array event profiling 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.
[in] | evt | The event 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. |
Definition at line 247 of file ccl_event_wrapper.h.
#define ccl_event_get_profiling_info_array | ( | evt, | |
param_name, | |||
param_type, | |||
err | |||
) |
Macro which returns an array event profiling 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.
[in] | evt | The event 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. |
Definition at line 247 of file ccl_event_wrapper.h.
#define ccl_event_get_profiling_info_scalar | ( | evt, | |
param_name, | |||
param_type, | |||
err | |||
) |
Macro which returns a scalar event profiling 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.
[in] | evt | The event 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. |
Definition at line 226 of file ccl_event_wrapper.h.
#define ccl_event_get_profiling_info_scalar | ( | evt, | |
param_name, | |||
param_type, | |||
err | |||
) |
Macro which returns a scalar event profiling 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.
[in] | evt | The event 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. |
Definition at line 226 of file ccl_event_wrapper.h.
#define ccl_event_ref | ( | evt | ) | ccl_wrapper_ref((CCLWrapper*) evt) |
Increase the reference count of the event object.
[in] | evt | The event wrapper object. |
Definition at line 257 of file ccl_event_wrapper.h.
#define ccl_event_ref | ( | evt | ) | ccl_wrapper_ref((CCLWrapper*) evt) |
Increase the reference count of the event object.
[in] | evt | The event wrapper object. |
Definition at line 257 of file ccl_event_wrapper.h.
#define ccl_event_unref | ( | evt | ) | ccl_event_destroy(evt) |
Alias to ccl_event_destroy().
[in] | evt | Event wrapper object to destroy if reference count is 1, otherwise just decrement the reference count. |
Definition at line 266 of file ccl_event_wrapper.h.
#define ccl_event_unref | ( | evt | ) | ccl_event_destroy(evt) |
Alias to ccl_event_destroy().
[in] | evt | Event wrapper object to destroy if reference count is 1, otherwise just decrement the reference count. |
Definition at line 266 of file ccl_event_wrapper.h.
#define ccl_event_unwrap | ( | evt | ) | ((cl_event) ccl_wrapper_unwrap((CCLWrapper*) evt)) |
Get the OpenCL event object.
[in] | evt | The event wrapper object. |
Definition at line 274 of file ccl_event_wrapper.h.
#define ccl_event_unwrap | ( | evt | ) | ((cl_event) ccl_wrapper_unwrap((CCLWrapper*) evt)) |
Get the OpenCL event object.
[in] | evt | The event wrapper object. |
Definition at line 274 of file ccl_event_wrapper.h.
typedef void( * ccl_event_callback)(cl_event event, cl_int event_command_exec_status, void *user_data) |
Prototype for user event callback functions.
[in] | event | The OpenCL event object for which the callback function is invoked. |
[in] | event_command_exec_status | Execution status of command for which this callback function is invoked. |
[in] | user_data | A pointer to user supplied data. |
Definition at line 92 of file ccl_event_wrapper.h.
typedef void( * ccl_event_callback)(cl_event event, cl_int event_command_exec_status, void *user_data) |
Prototype for user event callback functions.
[in] | event | The OpenCL event object for which the callback function is invoked. |
[in] | event_command_exec_status | Execution status of command for which this callback function is invoked. |
[in] | user_data | A pointer to user supplied data. |
Definition at line 92 of file ccl_event_wrapper.h.
void ccl_event_destroy | ( | CCLEvent * | evt | ) |
Decrements the reference count of the event wrapper object.
If it reaches 0, the event wrapper object is destroyed.
[in] | evt | The event wrapper object. |
Definition at line 95 of file ccl_event_wrapper.c.
Get the command type which fired the given event.
[in] | evt | Event wrapper. |
[out] | err | Return location for a CCLErr object, or NULL if error reporting is to be ignored. |
Definition at line 336 of file ccl_event_wrapper.c.
const char * ccl_event_get_final_name | ( | CCLEvent * | evt | ) |
Get the final event name for profiling purposes.
If a name was not explicitly set with ccl_event_set_name(), it will return a name based on the type of command associated with the event.
This is used to distinguish from different event is profiling is to be performed using the profiler module.
[in] | evt | The event wrapper object. |
Definition at line 161 of file ccl_event_wrapper.c.
const char * ccl_event_get_name | ( | CCLEvent * | evt | ) |
Get the event name for profiling purposes.
If not explicitly set with ccl_event_set_name(), it will return NULL.
This is used to distinguish from different event is profiling is to be performed using the profiler module.
[in] | evt | The event wrapper object. |
Definition at line 137 of file ccl_event_wrapper.c.
Get the OpenCL version of the platform associated with this event object.
The version is returned as an integer, in the following format:
[in] | evt | An event wrapper object. |
[out] | err | Return location for a CCLErr object, or NULL if error reporting is to be ignored. |
Definition at line 384 of file ccl_event_wrapper.c.
CCLEvent * ccl_event_new_wrap | ( | cl_event | event | ) |
Get the event wrapper for the given OpenCL event.
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 wrap the OpenCL event directly.
[in] | event | The OpenCL event to be wrapped. |
Definition at line 77 of file ccl_event_wrapper.c.
cl_bool ccl_event_set_callback | ( | CCLEvent * | evt, |
cl_int | command_exec_callback_type, | ||
ccl_event_callback | pfn_notify, | ||
void * | user_data, | ||
CCLErr ** | err | ||
) |
Wrapper for OpenCL clSetEventCallback() function.
[in] | evt | Event wrapper object. |
[in] | command_exec_callback_type | The command execution status for which the callback is registered (CL_SUBMITTED , CL_RUNNING , or CL_COMPLETE ). |
[in] | pfn_notify | The event callback function that can be registered by the application. |
[in] | user_data | Will be passed as the user_data argument when pfn_notify is called. |
[out] | err | Return location for a CCLErr object, or NULL if error reporting is to be ignored. |
CL_TRUE
if operation is successful, or CL_FALSE
otherwise. Definition at line 460 of file ccl_event_wrapper.c.
void ccl_event_set_name | ( | CCLEvent * | evt, |
const char * | name | ||
) |
Set event name for profiling purposes.
This is used to distinguish from different event is profiling is to be performed using the profiler module.
[in] | evt | The event wrapper object. |
[in] | name | Name to associate with event. |
Definition at line 114 of file ccl_event_wrapper.c.
cl_bool ccl_event_wait | ( | CCLEventWaitList * | evt_wait_lst, |
CCLErr ** | err | ||
) |
Waits on the host thread for commands identified by events in the wait list to complete.
This function is a wrapper for the clWaitForEvents() OpenCL function.
[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. |
CL_TRUE
if operation is successful, or CL_FALSE
otherwise. Definition at line 829 of file ccl_event_wrapper.c.
CCLEventWaitList* ccl_event_wait_list_add | ( | CCLEventWaitList * | evt_wait_lst, |
... | |||
) |
Add event wrapper objects to an event wait list (variable argument list version).
[out] | evt_wait_lst | Event wait list. |
[in] | ... | A NULL -terminated list of event wrapper objects. |
Definition at line 722 of file ccl_event_wrapper.c.
CCLEventWaitList* ccl_event_wait_list_add_v | ( | CCLEventWaitList * | evt_wait_lst, |
CCLEvent ** | evts | ||
) |
Add event wrapper objects to an event wait list (array version).
[out] | evt_wait_lst | Event wait list. |
[in] | evts | NULL -terminated array of event wrapper objects. |
Definition at line 768 of file ccl_event_wrapper.c.
void ccl_event_wait_list_clear | ( | CCLEventWaitList * | evt_wait_lst | ) |
Clears an event wait list.
This function will rarely be called from client code because event wait lists are automatically cleared when passed to ccl_*_enqueue_*()
functions.
[out] | evt_wait_lst | Event wait list. |
Definition at line 807 of file ccl_event_wrapper.c.
CCLEvent * ccl_user_event_new | ( | CCLContext * | ctx, |
CCLErr ** | err | ||
) |
Create a new user event.
Wraps the clCreateUserEvent() OpenCL function.
Returned event wrapper should be freed using ccl_event_destroy().
[in] | ctx | Context where to associate the user event. |
[out] | err | Return location for a CCLErr object, or NULL if error reporting is to be ignored. |
Definition at line 552 of file ccl_event_wrapper.c.
Sets the execution status of a user event object.
Wraps the clSetUserEventStatus() OpenCL function.
[in] | evt | Event wrapper object. |
[in] | execution_status | The new execution status to be set, can be CL_COMPLETE or a negative integer value to indicate an error. |
[out] | err | Return location for a CCLErr object, or NULL if error reporting is to be ignored. |
CL_TRUE
if operation is successful, or CL_FALSE
otherwise. Definition at line 641 of file ccl_event_wrapper.c.