carb::stats::IStats

Defined in examples/example.stats/include/carb/stats/IStats.h

struct IStats

(Example—not a real interface)

A simple global table of statistics that can be maintained and aggregated. Statistics can be added and removed as needed and new values can be aggregated into existing statistics. Each statistic’s current value can then be retrieved at a later time for display or analysis.

Public Members

StatId (*addStat)(const StatDesc &desc)

Adds a new statistic value to the table.

Thread Safety

This operation is thread safe.

Param desc

[in] The descriptor of the new statistic value to add.

Retval kBadStatId

if the new statistic could not be added or an error occurred.

Return

An identifier for the newly created statistic value if it is successfully added. If this statistic is no longer needed, it can be removed from the table with removeStat().

bool (*removeStat)(StatId stat)

Removes an existing statistic value from the table.

Thread Safety

This operation is thread safe.

Param stat

[in] The identifier of the statistic to be removed. This identifier is acquired from the call to addStat() that originally added it to the table.

Return

true if the statistic is successfully removed from the table.

Return

false if the statistic could not be removed or an error occurred.

bool (*addValue)(StatId stat, const Value &value)

Adds a new value to be accumulated into a given statistic.

Thread Safety

This operation is thread safe.

Param stat

[in] The identifier of the statistic to be removed. This identifier is acquired from the call to addStat() that originally added it to the table.

Param value

[in] The new value to accumulate into the statistic. It is the caller’s responsibility to ensure this new value is appropriate for the given statistic. The new value will be accumulated according to the accumulation method chosen when the statistic was first created.

Return

true if the new value was successfully accumulated into the given statistic.

Return

false if the new value could not be accumulated into the given statistic or the given statistic could not be found.

bool (*getValue)(StatId stat, StatDesc &value)

Retrieves the current accumulated value for a given statistic.

Thread Safety

It is the caller’s responsibility to ensure the given statistic is not removed while the returned value’s strings are being used. Aside from that, this operation is thread safe.

Param stat

[in] The identifier of the statistic to be removed. This identifier is acquired from the call to addStat() that originally added it to the table.

Param value

[out] Receives the new value and information for the given statistic. Note that the string values in this returned object will only be valid until the statistic object is remvoed. It is the caller’s responsibility to ensure the string is either copied as needed or to guarantee the statistic will not be removed while its value is being used.

Return

true if the statistic’s current value is successfully retrieved.

Return

false if the statistic’s value could not be retrieved or the statistic identifier was not valid.