uprof-report

uprof-report

Functions

Description

Functions

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

Parameters

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.

Parameters

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.

Parameters

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

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

report

A UProfReport

 

name

The name of the statistic

 

name_formatted

The name formatted for the left hand table cell entry in a text report (possibly wrapped with newline characters)

 

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 .

Parameters

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

Parameters

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

Parameters

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

Parameters

report

A UProfReport

 

id

The custom report column you want to remove

 

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

Parameters

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

Parameters

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

Parameters

report

A UProfReport

 

id

The custom report column you want to remove

 

uprof_report_print ()

void
uprof_report_print (UProfReport *report);

Types and Values