uprof-report

uprof-report

Synopsis

UProfReport *       uprof_report_new                    (const char *name);
UProfReport *       uprof_report_ref                    (UProfReport *report);
void                uprof_report_unref                  (UProfReport *report);
const char *        uprof_report_get_name               (UProfReport *report);
void                uprof_report_add_context            (UProfReport *report,
                                                         UProfContext *context);
char *              (*UProfStatisticAttributeCallback)  (UProfReport *report,
                                                         const char *statistic_name,
                                                         const char *attribute_name,
                                                         gpointer user_data);
void                uprof_report_add_statistic          (UProfReport *report,
                                                         const char *name,
                                                         const char *description);
void                uprof_report_add_statistic_attribute
                                                        (UProfReport *report,
                                                         const char *statistic_name,
                                                         const char *attribute_name,
                                                         const char *attribute_name_formatted,
                                                         const char *attribute_description,
                                                         UProfAttributeType type,
                                                         UProfStatisticAttributeCallback callback,
                                                         gpointer user_data);
char *              (*UProfCountersAttributeCallback)   (UProfReport *report,
                                                         UProfCounterResult *result,
                                                         void *user_data);
void                uprof_report_add_counters_attribute (UProfReport *report,
                                                         const char *name,
                                                         const char *name_formatted,
                                                         const char *description,
                                                         UProfAttributeType type,
                                                         UProfCountersAttributeCallback callback,
                                                         void *user_data);
void                uprof_report_remove_counters_attribute
                                                        (UProfReport *report,
                                                         const char *attribute_name);
char *              (*UProfTimersAttributeCallback)     (UProfReport *report,
                                                         UProfTimerResult *result,
                                                         void *user_data);
void                uprof_report_add_timers_attribute   (UProfReport *report,
                                                         const char *name,
                                                         const char *name_formatted,
                                                         const char *description,
                                                         UProfAttributeType type,
                                                         UProfTimersAttributeCallback callback,
                                                         void *user_data);
void                uprof_report_remove_timers_attribute
                                                        (UProfReport *report,
                                                         const char *attribute_name);
void                uprof_report_print                  (UProfReport *report);

Description

Details

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

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

const char *        uprof_report_get_name               (UProfReport *report);

Returns the name of the given report. See uprof_report_new().

report :

A UProfReport object

Returns :

The name of the given report.

Since 0.4


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

UProfStatisticAttributeCallback ()

char *              (*UProfStatisticAttributeCallback)  (UProfReport *report,
                                                         const char *statistic_name,
                                                         const char *attribute_name,
                                                         gpointer user_data);

Is a callback prototype used with uprof_report_add_statistic_attribute() for functions that calculate the value of a statistic attribute when generating a report.

report :

A UProfReport

statistic_name :

The statistic whos attribute value is being updated.

attribute_name :

The attribute whos value needs to be calculated.

user_data :

The private data passed to uprof_report_add_statistic_attribute()

Since 0.4


uprof_report_add_statistic ()

void                uprof_report_add_statistic          (UProfReport *report,
                                                         const char *name,
                                                         const char *description);

Adds a custom statistic to generated reports. The statistic must have a unique name such as "Average FPS" and you can define associated values with that statistic using uprof_report_add_statistic_attribute().

A custom statistic can be removed using uprof_report_remove_statistic() and if you give uprof_report_add_statistic() a name that already exists then the associated name_formatted and description will be updated.

report :

A UProfReport

name :

The name of the statistic

description :

A more detailed explanation of what the statistic shows

Since 0.4


uprof_report_add_statistic_attribute ()

void                uprof_report_add_statistic_attribute
                                                        (UProfReport *report,
                                                         const char *statistic_name,
                                                         const char *attribute_name,
                                                         const char *attribute_name_formatted,
                                                         const char *attribute_description,
                                                         UProfAttributeType type,
                                                         UProfStatisticAttributeCallback callback,
                                                         gpointer user_data);

Adds an attribute to a custom report statisitic. (See uprof_report_add_statistic()) This will add a new column to a text formatted report. The name_formatted argument will define the header for the new column and the callback will be called when generating a report to define the current value. The attribute_name is always unique for any particular statistic_name so if you give a pre-existing attribute_name then that will replace the corresponding attribute_name_formatted, attribute_description, type, callback and user_data.

report :

A UProfReport

statistic_name :

The name of the statistic which you want to add an attribute for.

attribute_name :

The name of the attribute

attribute_name_formatted :

The name formatted for the column header of a text report (possibly wrapped with newline characters)

attribute_description :

A more detailed explanation of what the attribute shows

type :

A UProfAttributeType detailing the attribute's value type.

callback :

A UProfStatisticAttributeCallback to be called when generating a report to define the current value for the attribute.

user_data :

A pointer to any private data that will be passed to the given callback.

Since 0.4


UProfCountersAttributeCallback ()

char *              (*UProfCountersAttributeCallback)   (UProfReport *report,
                                                         UProfCounterResult *result,
                                                         void *user_data);

Use this prototype for the custom attribute callbacks. The string values that you return in your callback may be wrapped across multiple lines and uprof should still tabulate the report correctly. The

result :

The current counter being reported

user_data :

The private data previously passed to uprof_report_add_counters_attribute()

uprof_report_add_counters_attribute ()

void                uprof_report_add_counters_attribute (UProfReport *report,
                                                         const char *name,
                                                         const char *name_formatted,
                                                         const char *description,
                                                         UProfAttributeType type,
                                                         UProfCountersAttributeCallback callback,
                                                         void *user_data);

Adds a custom attribute/column to reports of counter statistics. The attribute name can be wrapped with newline characters and the callback functions will be called once for each counter result reported while using uprof_report_print()

The string values that you return in your callback may be wrapped across multiple lines and uprof should still tabulate the report correctly. The values should be freeable with g_free().

For example:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
static char *double_count_cb (UProfCounterResult *counter, void *user_data)
{
  int count = uprof_counter_result_get_count (counter);
  return g_strdup_printf ("%d", count * 2);
}

*snip*

report = uprof_report_new ();
report = uprof_report_new ("Simple report");
uprof_report_add_counters_attribute (report,
                                     "Double count",
                                     "Double\ncount",
                                     "The count doubled",
                                     UPROF_ATTRIBUTE_TYPE_INT,
                                     double_count_cb, NULL);
uprof_report_add_context (report, context);
uprof_report_print (report);
uprof_report_unref (report);

report :

A UProfReport

name :

The name of the attribute

name_formatted :

The name formatted for the column header of a text report (possibly wrapped with newline characters)

description :

A more detailed explanation of what the attribute shows

type :

A UProfAttributeType detailing the attributes value type.

callback :

A function called for each counter being reported

user_data :

Private data passed back to your callback

Since 0.4


uprof_report_remove_counters_attribute ()

void                uprof_report_remove_counters_attribute
                                                        (UProfReport *report,
                                                         const char *attribute_name);

Removes the custom counters attribute from future reports generated with uprof_report_print().

report :

A UProfReport

UProfTimersAttributeCallback ()

char *              (*UProfTimersAttributeCallback)     (UProfReport *report,
                                                         UProfTimerResult *result,
                                                         void *user_data);

Use this prototype for the custom attribute callbacks. The string values that you return in your callback may be wrapped across multiple lines and uprof should still tabulate the report correctly. The

result :

The current timer being reported

user_data :

The private data previously passed to uprof_report_add_timers_attribute()

uprof_report_add_timers_attribute ()

void                uprof_report_add_timers_attribute   (UProfReport *report,
                                                         const char *name,
                                                         const char *name_formatted,
                                                         const char *description,
                                                         UProfAttributeType type,
                                                         UProfTimersAttributeCallback callback,
                                                         void *user_data);

Adds a custom attribute/column to reports of timer statistics. The attribute name can be wrapped with newline characters and the callback functions will be called once for each timer result reported while using uprof_report_print()

The string values that you return in your callback may be wrapped across multiple lines and uprof should still tabulate the report correctly. The values should be freeable with g_free().

For example:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
static char *half_time_cb (UProfTimerResult *timer, void *user_data)
{
  gulong msecs = uprof_timer_result_get_total_msecs (timer);
  return g_strdup_printf ("%lu", msecs/2);
}

*snip*

report = uprof_report_new ();
report = uprof_report_new ("Simple report");
uprof_report_add_timers_attribute (report, "Half\ntime",
                                   half_time_cb, NULL);
uprof_report_add_context (report, context);
uprof_report_print (report);
uprof_report_unref (report);

report :

A UProfReport

name :

The name of the attribute

name_formatted :

The name formatted for the column header of a text report (possibly wrapped with newline characters)

description :

A more detailed explanation of what the attribute shows

type :

A UProfAttributeType detailing the attributes value type.

callback :

A function called for each timer being reported

user_data :

Private data passed back to your callback

Since 0.4


uprof_report_remove_timers_attribute ()

void                uprof_report_remove_timers_attribute
                                                        (UProfReport *report,
                                                         const char *attribute_name);

Removes the custom timers attribute from future reports generated with uprof_report_print().

report :

A UProfReport

uprof_report_print ()

void                uprof_report_print                  (UProfReport *report);