uprof-context

uprof-context — Group counters and timers by application/library domains

Functions

Types and Values

Description

All statistics tracked by UProf are associated with a named context which usually corresponds to a single application or library.

Contexts can be linked together at runtime if you want to report relationships between the statistics between different libraries and applications and because this is linking mechanism is done at runtime it avoids the awkwardness of having to export special profiling symbols from your libraries.

A typical application would declare a single uprof context symbol that is visible accross the whole application. So in a header you could have:

1
UProfContext *_my_uprof_context;

And then after initializing uprof via uprof_init() you could do:

1
_my_uprof_context = uprof_context ("My Application");

If you have a library that is mainloop based and you allow your library to be a slave of an external mainloop then you should also link your context to the shared mainloop. For example the Clutter library can either create and manage its own mainloop or it can be integrated with a mainloop created by an application. Linking to the shared mainloop context can be done like this:

1
2
_my_uprof_context = uprof_context ("My Application");
uprof_context_link (_my_uprof_context, uprof_get_mainloop_context ());

At this point you can then start to declare counters and timers somthing like:

1
2
3
4
5
UPROF_STATIC_COUNTER (loop_counter,
                      "Loop counter",
                      "A Counter for a loop",
                      0 //no application private data);
UPROF_COUNTER_INC (_my_uprof_context, loop_counter);

See UPROF_STATIC_COUNTER() and UPROF_STATIC_TIMER() for more details.

Functions

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 ();

Parameters

name

The top most name to categorize your profiling results

 

uprof_context_ref ()

UProfContext *
uprof_context_ref (UProfContext *context);

Take a reference on a uprof context.

Parameters

context

A UProfContext

 

uprof_context_unref ()

void
uprof_context_unref (UProfContext *context);

uprof_context_get_name ()

const char *
uprof_context_get_name (UProfContext *context);

Returns the name of the given context . See uprof_context_new().

Parameters

context

A UProfContext

 

Returns

The name of the given context .

Since: 0.4


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.

Parameters

context

A UProfContext

 

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.

Parameters

context

A UProfContext

 

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.

Parameters

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.

One example for linking contexts is for mainloop based libraries that can optionally run under the control of an external mainloop. In this case where it can't be predetermined who will own the mainloop UProf provides a shared context just for the purpose of tracking mainloop statistics which by convention everyone should use. If you need to track mainloop statistics you should link UProf's mainloop context into your own. See uprof_get_mainloop_context() for more details.

Another case where linking contexts can be useful is 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 idea is that the DSO can create its own UProf context without depending on a symbol being exported from the library and then that library can get a handle on the statistics collected by that library at runtime via UProf and link the DSO context into the library's context for reporting.

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.

Parameters

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()

Parameters

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()

Parameters

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()

Parameters

context

A uprof context

 

UProfCounterResultCallback ()

void
(*UProfCounterResultCallback) (UProfCounterResult *counter,
                               gpointer data);

uprof_context_foreach_counter ()

void
uprof_context_foreach_counter (UProfContext *context,
                               GCompareDataFunc sort_compare_func,
                               UProfCounterResultCallback callback,
                               gpointer data);

uprof_context_get_counter_result ()

UProfCounterResult *
uprof_context_get_counter_result (UProfContext *context,
                                  const char *name);

UProfTimerResultCallback ()

void
(*UProfTimerResultCallback) (UProfTimerResult *timer,
                             gpointer data);

uprof_context_foreach_timer ()

void
uprof_context_foreach_timer (UProfContext *context,
                             GCompareDataFunc sort_compare_func,
                             UProfTimerResultCallback callback,
                             gpointer data);

uprof_context_get_timer_result ()

UProfTimerResult *
uprof_context_get_timer_result (UProfContext *context,
                                const char *name);

UProfMessageCallback ()

void
(*UProfMessageCallback) (const char *message,
                         gpointer user_data);

A callback prototype used with uprof_context_foreach_message() to iterate all the messages associated with a UProfContext.

Parameters

message

The message currently being iterated.

 

user_data

The private data set with uprof_context_foreach_message().

 

Since: 0.4


uprof_context_foreach_message ()

void
uprof_context_foreach_message (UProfContext *context,
                               UProfMessageCallback callback,
                               gpointer user_data);

Iterates all the messages associated with the given context and calls the callback for each one.

Parameters

context

A UProfContext

 

callback

A UProfMessageCallback to call for each message

 

user_data

Private data to pass to the callback.

 

Since: 0.4

Types and Values

UProfContext

typedef struct {
} UProfContext;

An opaque, ref counted type used to track a group of statistics under a given name. A new context is created via uprof_context_new() and freed using uprof_context_unref().