![]() |
![]() |
![]() |
UProf 0.2.0 Reference Manual | |
---|---|---|---|---|
Top | Description |
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);
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.
|
The number of arguments in argv . inout. |
|
array length=argc) (inout) (allow-none. array length=argc. inout length=argc. allow-none length=argc. |
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 |
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. |
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:
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 ();
|
The top most name to categorize your profiling results |
Returns : |
UProfContext * uprof_context_ref (UProfContext *context);
Take a reference on a uprof context.
|
A UProfContext |
Returns : |
#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.
|
The name of the C symbol to declare |
|
The name of the counter used for reporting |
|
A string describing what the timer represents |
|
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. |
#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.
|
The name of the C symbol to declare |
|
The name of the counter used for reporting |
|
A string describing what the timer represents |
|
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. |
#define UPROF_COUNTER_INC(CONTEXT, COUNTER_SYMBOL)
Increases the count for the given COUNTER_SYMBOL
.
|
A UProfContext |
|
A counter variable |
#define UPROF_COUNTER_DEC(CONTEXT, COUNTER_SYMBOL)
Decreases the count for the given COUNTER_SYMBOL
.
|
A UProfContext |
|
A counter variable |
#define UPROF_COUNTER_ZERO(CONTEXT, COUNTER_SYMBOL)
Resets the count for the given COUNTER_SYMBOL
.
|
A UProfContext |
|
A counter variable |
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.
|
A UProfContext |
|
#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.
|
The name of the C symbol to declare |
|
The name of a parent timer (it should really be the name given to the parent, not the C symbol name for the parent) |
|
The timer name used for reporting |
|
A string describing what the timer represents |
|
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. |
#define UPROF_TIMER(TIMER_SYMBOL, PARENT, NAME, DESCRIPTION, PRIV)
|
|
|
|
|
|
|
|
|
#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.
|
|
|
#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.
|
|
|
#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.
|
|
|
#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.
|
|
|
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.
|
A UProfContext |
|
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.
|
A UProfContext |
|
A printf style format string |
|
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.
|
A UProfContext |
|
A UProf context whos timers and counters you want to be made
available to context .
|
void uprof_context_unlink (UProfContext *context, UProfContext *other);
This removes a link between two contexts that was previously created using
uprof_context_link()
|
A UProfContext |
|
A UProf context whos timers and counters were previously made
available to context .
|
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()
|
A UProfContext |
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()
|
A uprof context |
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()
|
The name of the report |
Returns : |
A new UProfReport object |
UProfReport * uprof_report_ref (UProfReport *report);
Increases the reference count of a UProfReport object.
|
A UProfReport object |
Returns : |
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.
|
A UProfReport object |
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.
|
A UProfReport object |
|
a UProfContext object |