## UfoProfiler

UfoProfiler — Profile different measures

## Functions

void | (*UfoProfilerFunc) ()
UfoProfiler * | ufo_profiler_new ()
void | ufo_profiler_call ()
void | ufo_profiler_call_blocking ()
void | ufo_profiler_register_event ()
void | ufo_profiler_foreach ()
void | ufo_profiler_start ()
void | ufo_profiler_stop ()
void | ufo_profiler_trace_event ()
void | ufo_profiler_enable_tracing ()
GList * | ufo_profiler_get_trace_events ()
gdouble | ufo_profiler_elapsed ()

## Types and Values

struct | UfoProfiler
struct | UfoProfilerClass
enum | UfoTraceEventType
#define | UFO_TRACE_EVENT_TYPE_MASK
#define | UFO_TRACE_EVENT_TIME_MASK
| UfoTraceEvent
enum | UfoProfilerTimer

## Object Hierarchy

        GObject
        ╰── UfoProfiler

## Description

The UfoProfiler provides a drop-in replacement for a manual `clEnqueueNDRangeKernel()` call and tracks any associated events.

Each UfoTaskNode is assigned a profiler with `ufo_task_node_set_profiler()` by the managing UfoBaseScheduler. Task implementations should call `ufo_task_node_get_profiler()` to receive their profiler and make profiled kernel calls with `ufo_profiler_call()`.

## Functions

### UfoProfilerFunc ()

    void
    (*UfoProfilerFunc) (const gchar *kernel,
                        gconstpointer queue,
                        gulong queued,
                        gulong submitted,
                        gulong start,
                        gulong end,
                        gpointer user_data);

Specifies the type of functions passed to `ufo_profiler_foreach()`.

#### Parameters

kernel | Kernel name |
queue | OpenCL command queue |
queued | Queuing timestamp in ns |
submitted | Submit timestamp in ns |
start | Start timestamp in ns |
end | End timestamp in ns |
user_data | User data passed to `ufo_profiler_foreach()`. |

### ufo_profiler_new ()

    UfoProfiler *
    ufo_profiler_new (void);

Create a profiler object.

#### Returns

A new profiler object.

### ufo_profiler_call ()

    void
    ufo_profiler_call (UfoProfiler *profiler,
                       gpointer command_queue,
                       gpointer kernel,
                       guint work_dim,
                       const gsize *global_work_size,
                       const gsize *local_work_size);

Execute the `kernel` using the command queue and execution parameters. The event associated with the `clEnqueueNDRangeKernel()` call is recorded and may be used for profiling purposes later on.

#### Parameters

profiler | A UfoProfiler object. |
command_queue | A `cl_command_queue` |
kernel | A `cl_kernel` |
work_dim | Number of working dimensions. |
global_work_size | Sizes of global dimensions. The array must have at least `work_dim` entries. |
local_work_size | Sizes of local work group dimensions. The array must have at least `work_dim` entries. |

### ufo_profiler_call_blocking ()

    void
    ufo_profiler_call_blocking (UfoProfiler *profiler,
                                gpointer command_queue,
                                gpointer kernel,
                                guint work_dim,
                                const gsize *global_work_size,
                                const gsize *local_work_size);

Execute the `kernel` using the command queue and execution parameters and wait for the kernel to finish. The event associated with the `clEnqueueNDRangeKernel()` call is recorded and may be used for profiling purposes later on.

#### Parameters

profiler | A UfoProfiler object. |
command_queue | A `cl_command_queue` |
kernel | A `cl_kernel` |
work_dim | Number of working dimensions. |
global_work_size | Sizes of global dimensions. The array must have at least `work_dim` entries. |
local_work_size | Sizes of local work group dimensions. The array must have at least `work_dim` entries. |

### ufo_profiler_register_event ()

    void
    ufo_profiler_register_event (UfoProfiler *profiler,
                                 gpointer command_queue,
                                 gpointer kernel,
                                 gpointer event);

Register a kernel execution manually

#### Parameters

profiler | A UfoProfiler object |
command_queue | Queue the OpenCL event was issued with |
kernel | An OpenCL kernel the event stems from |
event | An OpenCL event |

### ufo_profiler_foreach ()

    void
    ufo_profiler_foreach (UfoProfiler *profiler,
                          UfoProfilerFunc func,
                          gpointer user_data);

Iterates through the recorded events and calls `func` on each entry.

#### Parameters

profiler | A UfoProfiler object |
func | The function to be called for an entry. | [scope call]
user_data | User parameters |

### ufo_profiler_start ()

    void
    ufo_profiler_start (UfoProfiler *profiler,
                        UfoProfilerTimer timer);

Start `timer` . The timer is not reset but accumulates the time elapsed between `ufo_profiler_start()` and `ufo_profiler_stop()` calls.

#### Parameters

profiler | A UfoProfiler object |
timer | Which timer to start |

### ufo_profiler_stop ()

    void
    ufo_profiler_stop (UfoProfiler *profiler,
                       UfoProfilerTimer timer);

Stop `timer` . The timer is not reset but accumulates the time elapsed between `ufo_profiler_start()` and `ufo_profiler_stop()` calls.

#### Parameters

profiler | A UfoProfiler object |
timer | Which timer to stop |

### ufo_profiler_trace_event ()

    void
    ufo_profiler_trace_event (UfoProfiler *profiler,
                              UfoTraceEventType type);

Register a new trace event. The given event type, the thread id and the global time is stored when this function is called.

#### Parameters

profiler | A UfoProfiler object |
type | trav event type |

### ufo_profiler_enable_tracing ()

    void
    ufo_profiler_enable_tracing (UfoProfiler *profiler,
                                 gboolean enable);

Enable or disable tracing of `profiler` . Calls to `ufo_profiler_trace_event()` will be ignored if tracing is disabled.

#### Parameters

profiler | A UfoProfiler object |
enable | `TRUE` if tracing should be enabled |

### ufo_profiler_get_trace_events ()

    GList *
    ufo_profiler_get_trace_events (UfoProfiler *profiler);

Get all events recorded with `profiler` .

[skip]

#### Parameters

profiler | A UfoProfiler object. |

#### Returns

A list with UfoTraceEvent objects.

[element-type UfoTraceEvent]

### ufo_profiler_elapsed ()

    gdouble
    ufo_profiler_elapsed (UfoProfiler *profiler,
                          UfoProfilerTimer timer);

Get the elapsed time in seconds for `timer` .

#### Parameters

profiler | A UfoProfiler object |
timer | Which timer to start |

#### Returns

Elapsed time in seconds.

## Types and Values

### struct UfoProfiler

    struct UfoProfiler;

The UfoProfiler collects and records OpenCL events and stores them in a convenient format on disk or prints summaries on screen.

### struct UfoProfilerClass

    struct UfoProfilerClass {
    };

UfoProfiler class

### enum UfoTraceEventType

#### Members

UFO_TRACE_EVENT_PROCESS | A process event |
UFO_TRACE_EVENT_GENERATE | A generate event |
UFO_TRACE_EVENT_BEGIN | Beginning of an event |
UFO_TRACE_EVENT_END | End of an event |

### UFO_TRACE_EVENT_TYPE_MASK

    #define UFO_TRACE_EVENT_TYPE_MASK   (UFO_TRACE_EVENT_PROCESS | UFO_TRACE_EVENT_GENERATE)

### UFO_TRACE_EVENT_TIME_MASK

    #define UFO_TRACE_EVENT_TIME_MASK   (UFO_TRACE_EVENT_BEGIN | UFO_TRACE_EVENT_END)

### UfoTraceEvent

    typedef struct {
        UfoTraceEventType type;
        gpointer     thread_id;
        gdouble      timestamp;
    } UfoTraceEvent;

#### Members

UfoTraceEventType `type`; | Type of the event |
gpointer `thread_id`; | ID of thread in which the event was issued |
gdouble `timestamp`; | Arbitrary timestamp of the event |

### enum UfoProfilerTimer

Use these values to select a specific timer when calling `ufo_profiler_start()`, `ufo_profiler_stop()` and `ufo_profiler_elapsed()`.

#### Members

UFO_PROFILER_TIMER_IO | Select I/O timer |
UFO_PROFILER_TIMER_CPU | Select CPU timer |
UFO_PROFILER_TIMER_GPU | Select GPU timer |
UFO_PROFILER_TIMER_FETCH | Select timer that measures the synchronization time to fetch data from the queues. |
UFO_PROFILER_TIMER_RELEASE | Select timer that measures the synchronization time to push data to the queues. |
UFO_PROFILER_TIMER_LAST | Auxiliary value, do not use. |