Top | ![]() |
![]() |
![]() |
![]() |
UProfContext * | uprof_context_new () |
UProfContext * | uprof_context_ref () |
void | uprof_context_unref () |
const char * | uprof_context_get_name () |
void | uprof_context_add_counter () |
void | uprof_context_add_timer () |
void | uprof_context_add_report_message () |
void | uprof_context_link () |
void | uprof_context_unlink () |
void | uprof_context_suspend () |
void | uprof_context_resume () |
void | (*UProfCounterResultCallback) () |
void | uprof_context_foreach_counter () |
UProfCounterResult * | uprof_context_get_counter_result () |
void | (*UProfTimerResultCallback) () |
void | uprof_context_foreach_timer () |
UProfTimerResult * | uprof_context_get_timer_result () |
void | (*UProfMessageCallback) () |
void | uprof_context_foreach_message () |
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.
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 (); |
UProfContext *
uprof_context_ref (UProfContext *context
);
Take a reference on a uprof context.
const char *
uprof_context_get_name (UProfContext *context
);
Returns the name of the given context
. See uprof_context_new()
.
Since: 0.4
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.
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.
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.
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.
void uprof_context_unlink (UProfContext *context
,UProfContext *other
);
This removes a link between two contexts that was previously created using
uprof_context_link()
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()
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()
void (*UProfCounterResultCallback) (UProfCounterResult *counter
,gpointer data
);
void uprof_context_foreach_counter (UProfContext *context
,GCompareDataFunc sort_compare_func
,UProfCounterResultCallback callback
,gpointer data
);
UProfCounterResult * uprof_context_get_counter_result (UProfContext *context
,const char *name
);
void (*UProfTimerResultCallback) (UProfTimerResult *timer
,gpointer data
);
void uprof_context_foreach_timer (UProfContext *context
,GCompareDataFunc sort_compare_func
,UProfTimerResultCallback callback
,gpointer data
);
UProfTimerResult * uprof_context_get_timer_result (UProfContext *context
,const char *name
);
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.
message |
The message currently being iterated. |
|
user_data |
The private data set with
|
Since: 0.4
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.
context |
||
callback |
A UProfMessageCallback to call for each message |
|
user_data |
Private data to pass to the callback. |
Since: 0.4
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()
.