This module offers a mechanism for selecting OpenCL devices, mainly for context creation, although its functionality can be used for other purposes. More...

Collaboration diagram for Device selector:

Modules
	Dependent filters
	Dependent filters perform device selection based on the characteristics of all devices present in the list passed to them.

	Independent filters
	Independent filters perform device selection based on per-device characteristics.

Typedefs
typedef CCLDevSelDevices(*	ccl_devsel_dep )(CCLDevSelDevices devices, void data, CCLErr *err)
	Dependent filter function: Abstract function for filtering several OpenCL devices depending on the available device choices. More...

typedef CCLDevSelDevices(*	ccl_devsel_dep )(CCLDevSelDevices devices, void data, CCLErr *err)
	Dependent filter function: Abstract function for filtering several OpenCL devices depending on the available device choices. More...

typedef cl_bool(*	ccl_devsel_indep )(CCLDevice device, void data, CCLErr **err)
	Independent filter function: Abstract function for filtering one OpenCL device at a time. More...

typedef cl_bool(*	ccl_devsel_indep )(CCLDevice device, void data, CCLErr **err)
	Independent filter function: Abstract function for filtering one OpenCL device at a time. More...

typedef GPtrArray *	CCLDevSelDevices
	An object containing device wrappers. More...

typedef GPtrArray *	CCLDevSelDevices
	An object containing device wrappers. More...

typedef GPtrArray *	CCLDevSelFilters
	A set of independent and dependent device filters. More...

typedef GPtrArray *	CCLDevSelFilters
	A set of independent and dependent device filters. More...

typedef enum ccl_devsel_filter_type	CCLDevSelFilterType
	Filter type.

typedef enum ccl_devsel_filter_type	CCLDevSelFilterType
	Filter type.

Enumerations
enum	ccl_devsel_filter_type { CCL_DEVSEL_INDEP, CCL_DEVSEL_DEP, CCL_DEVSEL_INDEP, CCL_DEVSEL_DEP }
	Filter type. More...

enum	ccl_devsel_filter_type { CCL_DEVSEL_INDEP, CCL_DEVSEL_DEP, CCL_DEVSEL_INDEP, CCL_DEVSEL_DEP }
	Filter type. More...

Functions
void	ccl_devsel_add_dep_filter (CCLDevSelFilters filters, ccl_devsel_dep filter, void data)
	Add a dependent filter to the filter set. More...

void	ccl_devsel_add_indep_filter (CCLDevSelFilters filters, ccl_devsel_indep filter, void data)
	Add an independent filter to the filter set. More...

void	ccl_devsel_devices_destroy (CCLDevSelDevices devices)
	Destroy an object containing device wrappers. More...

CCLDevSelDevices	ccl_devsel_devices_new (CCLErr **err)
	Create and return an object with device wrappers for all OpenCL devices present in the system. More...

gchar **	ccl_devsel_get_device_strings (CCLErr **err)
	Returns a NULL-terminated array of strings, each one containing the name and vendor of each device in the system. More...

void	ccl_devsel_print_device_strings (CCLErr **err)
	Print to stdout a device description string for each device in the system. More...

CCLDevSelDevices	ccl_devsel_select (CCLDevSelFilters filters, CCLErr *err)
	Select one or more OpenCL devices based on the provided filters. More...

Detailed Description

This module offers a mechanism for selecting OpenCL devices, mainly for context creation, although its functionality can be used for other purposes.

The ccl_context_new_from_filters_full() context wrapper constructor (and the ccl_context_new_from_filters() macro) accepts a CCLDevSelFilters object containing a set of filters. These filters define which devices can be used in the context. Instances of CCLDevSelFilters must be initialized to NULL:

    /* cf4ocl objects. */
    CCLContext* ctx;
    CCLDevSelFilters filters = NULL;
    CCLDevSelDevices devices;

Filters can then be added to the CCLDevSelFilters object with the ccl_devsel_add_dep_filter() and ccl_devsel_add_indep_filter() functions, which add dependent or independent filters, respectively. Filters are processed in the order in which they are added. The next example shows how to add an independent and a dependent filter to the CCLDevSelFilters object:

    /* Add independent filter which accepts CPU devices. */
    ccl_devsel_add_indep_filter(&filters, ccl_devsel_indep_type_cpu, NULL);
    /* Add "same platform" dependent filter. This filter should always be added
     * (usually in last position) for context creation, because all devices in a
     * context must belong to the same platform. */
    ccl_devsel_add_dep_filter(&filters, ccl_devsel_dep_platform, NULL);

At this stage, the most common use for the CCLDevSelFilters object is to pass it to a context wrapper constructor:

/* Create context wrapper, which must have at least one device. */

ctx = ccl_context_new_from_filters(&filters, &err);

/* Free context. */

ccl_context_destroy(ctx);

However, the CCLDevSelFilters object can also be used for explicit device selection:

/* Perform device selection. */

devices = ccl_devsel_select(&filters, &err);

The CCLDevSelDevices object represented by devices is just a GLib pointer array, so we have direct access to the list of device wrappers and its size. For example, let us list the filtered devices by name:

        /* List selected devices. */
        if (devices->len > 0) {
            printf("%d devices were accepted by the filters:\n", devices->len);
            for (unsigned int i = 0; i < devices->len; ++i) {
                dev_name = ccl_device_get_info_array(
                    devices->pdata[i], CL_DEVICE_NAME, char*, &err);

                printf("\t%d - %s\n", i + 1, dev_name);
            } /* For */
        } /* If */
        /* Free array object containing device wrappers. */
        ccl_devsel_devices_destroy(devices);

CCLDevSelFilters objects are automatically freed and reset to NULL when passed to context wrapper constructors or to the ccl_devsel_select() function.

See the complete example here.

The device selector module provides two additional helper functions which return and print a list of all OpenCL devices available in the system, respectively:

Finally, the device selector module also offers the ccl_devsel_devices_new() function, which returns a CCLDevSelDevices object containing device wrappers for all OpenCL devices in the system. This array should not be modified directly, and when no longer required, should be freed with ccl_devsel_devices_destroy().

Typedef Documentation

typedef CCLDevSelDevices(* ccl_devsel_dep)(CCLDevSelDevices devices, void *data, CCLErr **err)

Dependent filter function: Abstract function for filtering several OpenCL devices depending on the available device choices.

Parameters

[in]	devices	OpenCL devices to filter.
[in]	data	Filter data, implementation dependent.
[out]	err	Return location for a CCLErr object, or `NULL` if error reporting is to be ignored.

Returns: The OpenCL devices which were accepted by the filter.

Definition at line 181 of file ccl_device_selector.h.

typedef CCLDevSelDevices(* ccl_devsel_dep)(CCLDevSelDevices devices, void *data, CCLErr **err)

Dependent filter function: Abstract function for filtering several OpenCL devices depending on the available device choices.

Parameters

[in]	devices	OpenCL devices to filter.
[in]	data	Filter data, implementation dependent.
[out]	err	Return location for a CCLErr object, or `NULL` if error reporting is to be ignored.

Returns: The OpenCL devices which were accepted by the filter.

Definition at line 181 of file ccl_device_selector.h.

typedef cl_bool(* ccl_devsel_indep)(CCLDevice *device, void *data, CCLErr **err)

Independent filter function: Abstract function for filtering one OpenCL device at a time.

Parameters

[in]	device	OpenCL device to filter.
[in]	data	Filter data, implementation dependent.
[out]	err	Return location for a CCLErr object, or `NULL` if error reporting is to be ignored.

Returns: CL_TRUE if filter accepts device, CL_FALSE otherwise.

Definition at line 168 of file ccl_device_selector.h.

typedef cl_bool(* ccl_devsel_indep)(CCLDevice *device, void *data, CCLErr **err)

Independent filter function: Abstract function for filtering one OpenCL device at a time.

Parameters

[in]	device	OpenCL device to filter.
[in]	data	Filter data, implementation dependent.
[out]	err	Return location for a CCLErr object, or `NULL` if error reporting is to be ignored.

Returns: CL_TRUE if filter accepts device, CL_FALSE otherwise.

Definition at line 168 of file ccl_device_selector.h.

typedef GPtrArray* CCLDevSelDevices

An object containing device wrappers.

Objects of this type are mostly used between filtering steps, and client code will rarely access it directly. CCLDevSelDevices objects are in practice GLib's pointer arrays, and contain two fields:

void** pdata;

unsigned int len;

The pdata field is the array itself, while len specifies the length of the array. For example, the following code fetches the device wrapper at index 0:

CCLDeviceWrapper* dev;

CCLDevSelDevice devices;

dev = (CCLDeviceWrapper*) devices->pdata[0];

Objects of this type will rarely be manipulated directly in client code, unless if low-level management of device selection is required.

Definition at line 156 of file ccl_device_selector.h.

typedef GPtrArray* CCLDevSelDevices

An object containing device wrappers.

Objects of this type are mostly used between filtering steps, and client code will rarely access it directly. CCLDevSelDevices objects are in practice GLib's pointer arrays, and contain two fields:

void** pdata;

unsigned int len;

The pdata field is the array itself, while len specifies the length of the array. For example, the following code fetches the device wrapper at index 0:

CCLDeviceWrapper* dev;

CCLDevSelDevice devices;

dev = (CCLDeviceWrapper*) devices->pdata[0];

Objects of this type will rarely be manipulated directly in client code, unless if low-level management of device selection is required.

Definition at line 156 of file ccl_device_selector.h.

typedef GPtrArray* CCLDevSelFilters

A set of independent and dependent device filters.

Use the ccl_devsel_add_indep_filter() function to add independent filters and the ccl_devsel_add_dep_filter() function to add dependent device filters.

This object should be initialized to NULL:

CCLDevSelFilters filters = NULL;

And its location should be passed to the ccl_devsel_add_*_filter() functions:

ccl_devsel_add_indep_filter(&filters, ccl_devsel_indep_type_cpu, NULL);

Filters are processed in the order they are added to the set.

Definition at line 201 of file ccl_device_selector.h.

typedef GPtrArray* CCLDevSelFilters

A set of independent and dependent device filters.

Use the ccl_devsel_add_indep_filter() function to add independent filters and the ccl_devsel_add_dep_filter() function to add dependent device filters.

This object should be initialized to NULL:

CCLDevSelFilters filters = NULL;

And its location should be passed to the ccl_devsel_add_*_filter() functions:

ccl_devsel_add_indep_filter(&filters, ccl_devsel_indep_type_cpu, NULL);

Filters are processed in the order they are added to the set.

Definition at line 201 of file ccl_device_selector.h.

Enumeration Type Documentation

enum ccl_devsel_filter_type

Filter type.

Enumerator
CCL_DEVSEL_INDEP	Independent filter, filters one device at a time.
CCL_DEVSEL_DEP	Dependent filter, filters devices depending on the currently available device choices.
CCL_DEVSEL_INDEP	Independent filter, filters one device at a time.
CCL_DEVSEL_DEP	Dependent filter, filters devices depending on the currently available device choices.

Definition at line 118 of file ccl_device_selector.h.

enum ccl_devsel_filter_type

Filter type.

Enumerator
CCL_DEVSEL_INDEP	Independent filter, filters one device at a time.
CCL_DEVSEL_DEP	Dependent filter, filters devices depending on the currently available device choices.
CCL_DEVSEL_INDEP	Independent filter, filters one device at a time.
CCL_DEVSEL_DEP	Dependent filter, filters devices depending on the currently available device choices.

Definition at line 118 of file ccl_device_selector.h.

Function Documentation

void ccl_devsel_add_dep_filter	(	CCLDevSelFilters *	filters,
		ccl_devsel_dep	filter,
		void *	data
	)

Add a dependent filter to the filter set.

Parameters

[in]	filters	The filter set.
[in]	filter	Indendent filter function.
[in]	data	Filter data.

Examples:: device_filter.c.

Definition at line 563 of file ccl_device_selector.c.

void ccl_devsel_add_indep_filter	(	CCLDevSelFilters *	filters,
		ccl_devsel_indep	filter,
		void *	data
	)

Add an independent filter to the filter set.

Parameters

[in]	filters	The filter set.
[in]	filter	Indendent filter function.
[in]	data	Filter data.

Examples:: device_filter.c.

Definition at line 548 of file ccl_device_selector.c.

void ccl_devsel_devices_destroy ( CCLDevSelDevices devices )

Destroy an object containing device wrappers.

This function will rarely be used in client code, unless in cases where low-level management of device selection is required.

Parameters

[in] devices Object containing device wrappers.

Returns: Always returns NULL.

Examples:: device_filter.c.

Definition at line 434 of file ccl_device_selector.c.

CCLDevSelDevices ccl_devsel_devices_new ( CCLErr ** err )

Create and return an object with device wrappers for all OpenCL devices present in the system.

See CCLDevSelDevices for information on how to access individual device wrappers within the object.

Parameters

[out] err Return location for a CCLErr object, or NULL if error reporting is to be ignored.

Returns: An object containing device wrappers for all OpenCL devices present in the system, or NULL if an error occurs. The object should be freed with ccl_devsel_devices_destroy().

See also: CCLDevSelDevices

Definition at line 330 of file ccl_device_selector.c.

gchar ** ccl_devsel_get_device_strings ( CCLErr ** err )

Returns a NULL-terminated array of strings, each one containing the name and vendor of each device in the system.

The array of strings should be freed with the ccl_strv_clear() function.

Parameters

[out] err Return location for a CCLErr object, or NULL if error reporting is to be ignored.

Returns: A NULL-terminated array of strings, each one containing the name and vendor of each device in the system. The array of strings should be freed with the ccl_strv_clear() function. If an error occurs, NULL is returned.

Definition at line 451 of file ccl_device_selector.c.

void ccl_devsel_print_device_strings ( CCLErr ** err )

Print to stdout a device description string for each device in the system.

Parameters

[out] err Return location for a CCLErr object, or NULL if error reporting is to be ignored.

Definition at line 504 of file ccl_device_selector.c.

CCLDevSelDevices ccl_devsel_select	(	CCLDevSelFilters *	filters,
		CCLErr **	err
	)

Select one or more OpenCL devices based on the provided filters.

This function is internally used by the ccl_context_new_from_filters_full() function for selecting context devices. Clients should not need to use it frequently.

Parameters

[in]	filters	Filters used to select device(s).
[out]	err	Return location for a CCLErr object, or `NULL` if error reporting is to be ignored.

Returns: One or more OpenCL devices selected based on the provided filters.

Examples:: device_filter.c.

Definition at line 583 of file ccl_device_selector.c.

Modules

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

Enumeration Type Documentation

Function Documentation