uprof

uprof

Synopsis

                    UProfContext;
void                uprof_init                          (int *argc,
                                                         char ***argv);
guint64             uprof_get_system_counter            (void);
guint64             uprof_get_system_counter_hz         (void);
UProfContext *      uprof_context_new                   (const char *name);
UProfContext *      uprof_context_ref                   (UProfContext *context);
void                uprof_context_unref                 (UProfContext *context);
#define             UPROF_STATIC_COUNTER                (COUNTER_SYMBOL,
                                                         NAME,
                                                         DESCRIPTION,
                                                         PRIV)
#define             UPROF_COUNTER                       (COUNTER_SYMBOL,
                                                         NAME,
                                                         DESCRIPTION,
                                                         PRIV)
#define             UPROF_COUNTER_INC                   (CONTEXT,
                                                         COUNTER_SYMBOL)
#define             UPROF_COUNTER_DEC                   (CONTEXT,
                                                         COUNTER_SYMBOL)
#define             UPROF_COUNTER_ZERO                  (CONTEXT,
                                                         COUNTER_SYMBOL)
void                uprof_context_add_counter           (UProfContext *context,
                                                         UProfCounter *counter);
#define             UPROF_STATIC_TIMER                  (TIMER_SYMBOL,
                                                         PARENT,
                                                         NAME,
                                                         DESCRIPTION,
                                                         PRIV)
#define             UPROF_TIMER                         (TIMER_SYMBOL,
                                                         PARENT,
                                                         NAME,
                                                         DESCRIPTION,
                                                         PRIV)
#define             UPROF_TIMER_START                   (CONTEXT,
                                                         TIMER_SYMBOL)
#define             UPROF_TIMER_STOP                    (CONTEXT,
                                                         TIMER_SYMBOL)
#define             UPROF_RECURSIVE_TIMER_START         (CONTEXT,
                                                         TIMER_SYMBOL)
#define             UPROF_RECURSIVE_TIMER_STOP          (CONTEXT,
                                                         TIMER_SYMBOL)
void                uprof_context_add_timer             (UProfContext *context,
                                                         UProfTimer *timer);
void                uprof_context_add_report_message    (UProfContext *context,
                                                         const char *format,
                                                         ...);
void                uprof_context_link                  (UProfContext *context,
                                                         UProfContext *other);
void                uprof_context_unlink                (UProfContext *context,
                                                         UProfContext *other);
void                uprof_context_suspend               (UProfContext *context);
void                uprof_context_resume                (UProfContext *context);
UProfReport *       uprof_report_new                    (const char *name);
UProfReport *       uprof_report_ref                    (UProfReport *report);
void                uprof_report_unref                  (UProfReport *report);
void                uprof_report_add_context            (UProfReport *report,
                                                         UProfContext *context);
void                uprof_report_print                  (UProfReport *report);

Description

Details

UProfContext

typedef struct _UProfContext UProfContext;


uprof_init ()

void                uprof_init                          (int *argc,
                                                         char ***argv);

It will initialise everything needed to operate with UProf and parses any standard command line options. argc and argv are adjusted accordingly so your own code will never see those standard arguments.

argc :

The number of arguments in argv. [inout]

argv :

A pointer to an array of arguments. [array length=argc][inout length=argc][allow-none length=argc]

uprof_get_system_counter ()

guint64             uprof_get_system_counter            (void);

Gives direct access to the counter that uprof is using for timing. On x86 platforms this executes the rdtsc instruction to return a 64bit integer that increases at the CPU or system bus frequency. Other platforms fall back to clock_gettime (CLOCK_MONOTONIC, &ts)

Returns :

a 64bit system counter

uprof_get_system_counter_hz ()

guint64             uprof_get_system_counter_hz         (void);

Allows you to convert elapsed counts into seconds. Be aware that the calculation of the conversion factor is done in a fairly crude way so it may not be very accurate. This usually isn't a big problem though as any inaccuracy will apply consistently to everything in a uprof report so the numbers still tend to end up relatively useful. It may be worth bearing in mind though if comparing different reports.

Returns :

A factor that can be used to convert elapsed counts into seconds.

uprof_context_new ()

UProfContext *      uprof_context_new                   (const char *name);

This creates a new profiling context with a given name. After creating a context you should declare your timers and counters, and once you have accumulated data you can print the results by creating a report via uprof_report_new(), uprof_report_add_context() and uprof_report_print()

For example:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
UProfContext *context;
UProfReport *report;
UPROF_STATIC_TIMER (parent_timer,
                    NULL, // no parent
                    "Parent timer",
                    "An example parent timer",
                    0 // no application private data);
UPROF_STATIC_TIMER (timer,
                    "Parent timer",
                    "Simple timer",
                    "An example timer",
                    0 // no application private data);

uprof_context_init (argc, argv);

context = uprof_context_new ("Test Context");

UPROF_TIMER_START (context, parent_timer);
sleep (1);
UPROF_TIMER_START (context, timer);
sleep (1);
UPROF_TIMER_STOP (context, timer);
UPROF_TIMER_STOP (context, parent_timer);

report = uprof_report_new ("Test Report");
uprof_report_add_context (context);
uprof_report_print ();
uprof_report_unref ();

uprof_context_unref ();

name :

The top most name to categorize your profiling results

Returns :


uprof_context_ref ()

UProfContext *      uprof_context_ref                   (UProfContext *context);

Take a reference on a uprof context.

context :

A UProfContext

Returns :


uprof_context_unref ()

void                uprof_context_unref                 (UProfContext *context);

context :


UPROF_STATIC_COUNTER()

#define             UPROF_STATIC_COUNTER(COUNTER_SYMBOL, NAME, DESCRIPTION, PRIV)

Declares a new static counter structure which can be used with the UPROF_COUNTER_INC(), UPROF_COUNTER_DEC() and UPROF_COUNTER_ZERO() macros.

COUNTER_SYMBOL :

The name of the C symbol to declare

NAME :

The name of the counter used for reporting

DESCRIPTION :

A string describing what the timer represents

PRIV :

Optional private data (unsigned long) which you can access if you are generating a very customized report. For example you might put application specific flags here that affect reporting.

UPROF_COUNTER()

#define             UPROF_COUNTER(COUNTER_SYMBOL, NAME, DESCRIPTION, PRIV)

Declares a new counter structure which can be used with the UPROF_COUNTER_INC(), UPROF_COUNTER_DEC() and UPROF_COUNTER_ZERO() macros. Usually you should use UPROF_STATIC_COUNTER() instead, but this may be useful for special cases where counters are accessed from multiple files.

COUNTER_SYMBOL :

The name of the C symbol to declare

NAME :

The name of the counter used for reporting

DESCRIPTION :

A string describing what the timer represents

PRIV :

Optional private data (unsigned long) which you can access if you are generating a very customized report. For example you might put application specific flags here that affect reporting.

UPROF_COUNTER_INC()

#define             UPROF_COUNTER_INC(CONTEXT, COUNTER_SYMBOL)

Increases the count for the given COUNTER_SYMBOL.

CONTEXT :

A UProfContext

COUNTER_SYMBOL :

A counter variable

UPROF_COUNTER_DEC()

#define             UPROF_COUNTER_DEC(CONTEXT, COUNTER_SYMBOL)

Decreases the count for the given COUNTER_SYMBOL.

CONTEXT :

A UProfContext

COUNTER_SYMBOL :

A counter variable

UPROF_COUNTER_ZERO()

#define             UPROF_COUNTER_ZERO(CONTEXT, COUNTER_SYMBOL)

Resets the count for the given COUNTER_SYMBOL.

CONTEXT :

A UProfContext

COUNTER_SYMBOL :

A counter variable

uprof_context_add_counter ()

void                uprof_context_add_counter           (UProfContext *context,
                                                         UProfCounter *counter);

Declares a new uprof counter and associates it with a context. Normally this API isn't used directly because the UPROF_COUNTER_INC(), UPROF_COUNTER_DEC() and UPROF_COUNTER_ZERO() macros will ensure a counter is added the first time it used.

context :

A UProfContext

counter :


UPROF_STATIC_TIMER()

#define             UPROF_STATIC_TIMER(TIMER_SYMBOL, PARENT, NAME, DESCRIPTION, PRIV)

This can be used to declare a new static timer structure which can then be used with the UPROF_TIMER_START() and UPROF_TIMER_STOP() macros.

TIMER_SYMBOL :

The name of the C symbol to declare

PARENT :

The name of a parent timer (it should really be the name given to the parent, not the C symbol name for the parent)

NAME :

The timer name used for reporting

DESCRIPTION :

A string describing what the timer represents

PRIV :

Optional private data (unsigned long) which you can access if you are generating a very customized report. For example you might put application specific flags here that affect reporting.

UPROF_TIMER()

#define             UPROF_TIMER(TIMER_SYMBOL, PARENT, NAME, DESCRIPTION, PRIV)

TIMER_SYMBOL :

PARENT :

NAME :

DESCRIPTION :

PRIV :


UPROF_TIMER_START()

#define             UPROF_TIMER_START(CONTEXT, TIMER_SYMBOL)

Starts the timer timing. It is an error to try and start a timer that is already timing; if you need to do this you should use UPROF_RECURSIVE_TIMER_START() instead.

CONTEXT :

TIMER_SYMBOL :


UPROF_TIMER_STOP()

#define             UPROF_TIMER_STOP(CONTEXT, TIMER_SYMBOL)

Stops the timer timing. It is an error to try and stop a timer that isn't actually timing. It is also an error to use this macro if the timer was started using UPROF_RECURSIVE_TIMER_START(); you should use UPROF_RECURSIVE_TIMER_STOP() instead.

CONTEXT :

TIMER_SYMBOL :


UPROF_RECURSIVE_TIMER_START()

#define             UPROF_RECURSIVE_TIMER_START(CONTEXT, TIMER_SYMBOL)

Starts the timer timing like UPROF_TIMER_START() but with additional guards to allow the timer to be started multiple times, such that UPROF_RECURSIVE_TIMER_STOP() must be called an equal number of times to actually stop it timing.

CONTEXT :

TIMER_SYMBOL :


UPROF_RECURSIVE_TIMER_STOP()

#define             UPROF_RECURSIVE_TIMER_STOP(CONTEXT, TIMER_SYMBOL)

Stops a recursive timer timing. It is an error to try and stop a timer that isn't actually timing. It is also an error to use this macro if the timer was started using UPROF_TIMER_START(); you should use UPROF_TIMER_STOP() instead.

CONTEXT :

TIMER_SYMBOL :


uprof_context_add_timer ()

void                uprof_context_add_timer             (UProfContext *context,
                                                         UProfTimer *timer);

Declares a new uprof timer and associates it with a context. Normally this API isn't used directly because the UPROF_TIMER_START() and UPROF_RECURSIVE_TIMER_START() macros will ensure a timer is added the first time it used.

context :

A UProfContext

timer :


uprof_context_add_report_message ()

void                uprof_context_add_report_message    (UProfContext *context,
                                                         const char *format,
                                                         ...);

This function queues a message to be output when uprof generates its final report.

context :

A UProfContext

format :

A printf style format string

... :


uprof_context_link ()

void                uprof_context_link                  (UProfContext *context,
                                                         UProfContext *other);

Links two contexts together so the timers and counters of the other context will become in a way part of the first context - at least as far as reporting is concerned. For example calling uprof_context_foreach_counter() would iterate all the counters of other contexts linked to the given context.

This can be useful if you are profiling a library that itself dynamically loads a shared object (DSO), but you can't export a context symbol from the library to the DSO because it happens that this DSO is also used by other libraries or applications which can't provide that symbol.

The intention is to create a context that is owned by the DSO, and when we end up loading the DSO in the library we are profiling we can link that context into the real context.

An example of this is profiling a DRI driver which can be loaded by X clients for direct rendering, or also by the X server for indirect rendering. If you try and export a context variable from the GL driver to the DRI driver there will end up being an unresolved symbol when the X server tries to load the driver.

context :

A UProfContext

other :

A UProf context whos timers and counters you want to be made available to context.

uprof_context_unlink ()

void                uprof_context_unlink                (UProfContext *context,
                                                         UProfContext *other);

This removes a link between two contexts that was previously created using uprof_context_link()

context :

A UProfContext

other :

A UProf context whos timers and counters were previously made available to context.

uprof_context_suspend ()

void                uprof_context_suspend               (UProfContext *context);

Disables all timer and counter accounting for a context and all linked contexts. This can be used to precisely control what you profile. For example in Clutter if we want to focus on input handling we suspend the context early on during library initialization and only resume it while processing input.

You can suspend a context multiple times, and it will only resume with an equal number of calls to uprof_context_resume()

context :

A UProfContext

uprof_context_resume ()

void                uprof_context_resume                (UProfContext *context);

Re-Enables all timer and counter accounting for a context (and all linked contexts) if previously disabled with a call to uprof_context_suspend().

You can suspend a context multiple times, and it will only resume with an equal number of calls to uprof_context_resume()

context :

A uprof context

uprof_report_new ()

UProfReport *       uprof_report_new                    (const char *name);

Creates an object representing a UProf report. You should associate the contexts that you want to generate a report for with this object using uprof_report_add_context() before generating a report via uprof_report_print()

name :

The name of the report

Returns :

A new UProfReport object

uprof_report_ref ()

UProfReport *       uprof_report_ref                    (UProfReport *report);

Increases the reference count of a UProfReport object.

report :

A UProfReport object

Returns :


uprof_report_unref ()

void                uprof_report_unref                  (UProfReport *report);

Decreases the reference count of a UProfReport object. When the reference count reaches 0 its associated resources will be freed.

report :

A UProfReport object

uprof_report_add_context ()

void                uprof_report_add_context            (UProfReport *report,
                                                         UProfContext *context);

Associates a context with a report object so that when the report is generated it will include statistics relating to this context.

report :

A UProfReport object

context :

a UProfContext object

uprof_report_print ()

void                uprof_report_print                  (UProfReport *report);

report :