## UfoResources

UfoResources — Manage OpenCL resources

## Functions

#define | UFO_RESOURCES_CHECK_CLERR()
#define | UFO_RESOURCES_CHECK_AND_SET()
#define | UFO_RESOURCES_CHECK_SET_AND_RETURN()
UfoResources * | ufo_resources_new ()
void | ufo_resources_add_path ()
gpointer | ufo_resources_get_kernel ()
gpointer | ufo_resources_get_kernel_from_source ()
gpointer | ufo_resources_get_cached_kernel ()
gchar * | ufo_resources_get_kernel_source ()
gpointer | ufo_resources_get_context ()
GList * | ufo_resources_get_cmd_queues ()
GList * | ufo_resources_get_devices ()
GList * | ufo_resources_get_gpu_nodes ()
const gchar * | ufo_resources_clerr ()
GQuark | ufo_resources_error_quark ()

## Properties

UfoDeviceType | device-type | Read / Write / Construct Only
int | platform-index | Read / Write

## Types and Values

#define | UFO_RESOURCES_ERROR
enum | UfoResourcesError
enum | UfoDeviceType
struct | UfoResources
struct | UfoResourcesClass

## Object Hierarchy

        GObject
        ╰── UfoResources

## Implemented Interfaces

UfoResources implements GInitable.

## Description

The UfoResources creates the OpenCL environment and loads OpenCL kernels from disk or directly as a string. By default the kernel search path is in `$datadir/ufo` but can be extended by the `UFO_KERNEL_PATH` environment variable.

## Functions

### UFO_RESOURCES_CHECK_CLERR()

    #define             UFO_RESOURCES_CHECK_CLERR(error)

Check the return value of OpenCL functions and issue a warning with file and line number if an error occurred.

#### Parameters

error | OpenCL error code |

### UFO_RESOURCES_CHECK_AND_SET()

    #define             UFO_RESOURCES_CHECK_AND_SET(error, g_error_loc)

Check `error` and set `g_error_loc` accordingly.

#### Parameters

error | OpenCL error code |
g_error_loc | Return location for a GError or `NULL` |

#### Returns

`TRUE` if no error occurred, `FALSE` otherwise.

### UFO_RESOURCES_CHECK_SET_AND_RETURN()

    #define             UFO_RESOURCES_CHECK_SET_AND_RETURN(error, g_error_loc)

Check `error` and set `g_error_loc` accordingly.

#### Parameters

error | OpenCL error code |
g_error_loc | Return location for a GError or `NULL` |

#### Returns

`TRUE` if no error occurred, `FALSE` otherwise.

### ufo_resources_new ()

    UfoResources *
    ufo_resources_new (GError **error);

Create a new UfoResources instance.

#### Parameters

error | Location of a GError or `NULL` |

#### Returns

A new UfoResources.

[transfer none]

### ufo_resources_add_path ()

    void
    ufo_resources_add_path (UfoResources *resources,
                            const gchar *path);

#### Parameters

resources | A UfoResources object |
path | a path to OpenCL kernel files |

### ufo_resources_get_kernel ()

    gpointer
    ufo_resources_get_kernel (UfoResources *resources,
                              const gchar *filename,
                              const gchar *kernel,
                              const gchar *options,
                              GError **error);

Loads and builds a kernel from a file. The file is searched in the current working directory and all paths added through `ufo_resources_add_path()`. If `kernel` is `NULL`, the first encountered kernel is returned. Options are passed verbatim to the OpenCL compiler and ignored if `NULL`.

#### Parameters

resources | A UfoResources object |
filename | Name of the .cl kernel file |
kernel | Name of a kernel, or `NULL` |
options | Options passed to the OpenCL compiler or `NULL` |
error | Return location for a GError from UfoResourcesError, or `NULL` |

#### Returns

a cl_kernel object that is load from `filename` or `NULL` on error.

[transfer none]

### ufo_resources_get_kernel_from_source ()

    gpointer
    ufo_resources_get_kernel_from_source (UfoResources *resources,
                                          const gchar *source,
                                          const gchar *kernel,
                                          const gchar *options,
                                          GError **error);

Loads and builds a kernel from a string. If `kernel` is `NULL`, the first kernel defined in `source` is used.

#### Parameters

resources | A UfoResources |
source | OpenCL source string |
kernel | Name of a kernel or `NULL` |
options | Options passed to the OpenCL compiler |
error | Return location for a GError from UfoResourcesError, or NULL |

#### Returns

a cl_kernel object that is load from `filename` .

[transfer none]

### ufo_resources_get_cached_kernel ()

    gpointer
    ufo_resources_get_cached_kernel (UfoResources *resources,
                                     const gchar *filename,
                                     const gchar *kernel,
                                     GError **error);

Loads a and builds a kernel from a file. The file is searched in the current working directory and all paths added through `ufo_resources_add_path()`. If `kernel` is `NULL`, the first encountered kernel is returned. The kernel object is cached and should not be used by two threads concurrently.

#### Parameters

resources | A UfoResources object |
filename | Name of the .cl kernel file |
kernel | Name of a kernel, or `NULL` |
error | Return location for a GError from UfoResourcesError, or `NULL` |

#### Returns

a cl_kernel object that is load from `filename` or `NULL` on error.

[transfer none]

### ufo_resources_get_kernel_source ()

    gchar *
    ufo_resources_get_kernel_source (UfoResources *resources,
                                     const gchar *filename,
                                     GError **error);

Loads a file present in the kernel PATH search list. The file is searched in the current working directory and all paths added through `ufo_resources_add_path()`.

#### Parameters

resources | A UfoResources object |
filename | Name of the .cl kernel file |
error | Return location for a GError from UfoResourcesError, or `NULL` |

#### Returns

a string (gchar*) load from `filename` or `NULL` on error, user is responsible for `free()` it after using it.

[transfer none]

### ufo_resources_get_context ()

    gpointer
    ufo_resources_get_context (UfoResources *resources);

Returns the OpenCL context object that is used by the resource resources. This context can be used to initialize othe third-party libraries.

#### Parameters

resources | A UfoResources |

#### Returns

A cl_context object.

### ufo_resources_get_cmd_queues ()

    GList *
    ufo_resources_get_cmd_queues (UfoResources *resources);

Get all command queues managed by `resources` .

[skip]

#### Parameters

resources | A UfoResources |

#### Returns

List with cl_command_queue objects. Free with `g_list_free()` but not its elements.

[transfer container][element-type gpointer]

### ufo_resources_get_devices ()

    GList *
    ufo_resources_get_devices (UfoResources *resources);

Get all devices queues managed by `resources` .

[skip]

#### Parameters

resources | A UfoResources |

#### Returns

List with cl_device_id objects. Free with `g_list_free()` but not its elements.

[element-type gpointer][transfer container]

### ufo_resources_get_gpu_nodes ()

    GList *
    ufo_resources_get_gpu_nodes (UfoResources *resources);

Get all UfoGpuNode objects managed by `resources` .

#### Parameters

resources | A UfoResources |

#### Returns

List with UfoGpuNode objects. Free with `g_list_free()` but not its elements.

[transfer container][element-type Ufo.GpuNode]

### ufo_resources_clerr ()

    const gchar *
    ufo_resources_clerr (int error);

Get a human-readable string representation of `error` .

#### Parameters

error | An OpenCL error code |

#### Returns

A static string of `error` .

[transfer none]

### ufo_resources_error_quark ()

    GQuark
    ufo_resources_error_quark (void);

## Types and Values

### UFO_RESOURCES_ERROR

    #define UFO_RESOURCES_ERROR             ufo_resources_error_quark()

### enum UfoResourcesError

OpenCL related errors.

#### Members

UFO_RESOURCES_ERROR_GENERAL | General resource problems |
UFO_RESOURCES_ERROR_LOAD_PROGRAM | Could not load the OpenCL file |
UFO_RESOURCES_ERROR_CREATE_PROGRAM | Could not create a program from the sources |
UFO_RESOURCES_ERROR_BUILD_PROGRAM | Could not build program from sources |
UFO_RESOURCES_ERROR_CREATE_KERNEL | Could not create kernel |

### enum UfoDeviceType

Types of OpenCL devices to query for. See UfoResources:"device-type".

#### Members

UFO_DEVICE_CPU | Only CPU devices |
UFO_DEVICE_GPU | Only GPU devices |
UFO_DEVICE_ACC | Only accelerator devices such as Xeon Phi |
UFO_DEVICE_ALL | All devices |

### struct UfoResources

    struct UfoResources;

Manages OpenCL resources. The contents of the UfoResources structure are private and should only be accessed via the provided API.

### struct UfoResourcesClass

    struct UfoResourcesClass {
    };

UfoResources class

## Property Details

### The `“device-type”` property

      “device-type”              UfoDeviceType

Type of the devices that should be used exclusively for computation.

See: UfoDeviceType for the device classes.

Owner: UfoResources

Flags: Read / Write / Construct Only

Default value: UFO_DEVICE_GPU

### The `“platform-index”` property

      “platform-index”           int

Platform index, -1 denotes any platform.

Owner: UfoResources

Flags: Read / Write

Allowed values: [-1,16]

Default value: 0