osmocom
/
libosmocore
mirror of https://gerrit.osmocom.org/libosmocore
11
0
Fork 0
Code Issues Releases Wiki Activity

[doc] stat_item: Complete doxygen documentation for API 

The stat_item code base had some incomplete doxygen documentation
so far.  Let's complete it, and at the same time fix some cosmetic
as well as copy+paste issues in the existing documentation bits.

Change-Id: Ib514c137b40bf7b9791bd74be99af0b65575f2b6
This commit is contained in:
Harald Welte 2017-10-15 19:24:57 +02:00
parent 216338c369
commit 781951bcf9
2 changed files with 89 additions and 42 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

46
include/osmocom/core/stat_item.h
View File

@ -13,32 +13,34 @@ struct osmo_stat_item_desc;
#define OSMO_STAT_ITEM_NOVALUE_ID 0
#define OSMO_STAT_ITEM_NO_UNIT NULL
/*! Individual entry in value FIFO */
struct osmo_stat_item_value {
int32_t id;
int32_t value;
int32_t id; /*!< identifier of value */
int32_t value; /*!< actual value */
};
/*! data we keep for each actual value */
/*! data we keep for each actual item */
struct osmo_stat_item {
/*! back-reference to the item description */
const struct osmo_stat_item_desc *desc;
/*! the index of the freshest value */
int32_t last_value_index;
/*! offset to the freshest value in the value fifo */
/*! offset to the freshest value in the value FIFO */
int16_t last_offs;
/*! value fifo */
/*! value FIFO */
struct osmo_stat_item_value values[0];
};
/*! statistics value description */
/*! Statistics item description */
struct osmo_stat_item_desc {
const char *name; /*!< name of the item */
const char *description;/*!< description of the item */
const char *unit; /*!< unit of a value */
unsigned int num_values;/*!< number of values to store */
int32_t default_value;
unsigned int num_values;/*!< number of values to store in FIFO */
int32_t default_value; /*!< default value */
};
/*! description of a statistics value group */
/*! Description of a statistics item group */
struct osmo_stat_item_group_desc {
/*! The prefix to the name of all values in this group */
const char *group_name_prefix;
@ -46,9 +48,9 @@ struct osmo_stat_item_group_desc {
const char *group_description;
/*! The class to which this group belongs */
int class_id;
/*! The number of values in this group */
/*! The number of values in this group (size of item_desc) */
const unsigned int num_items;
/*! Pointer to array of value names */
/*! Pointer to array of value names, length as per num_items */
const struct osmo_stat_item_desc *item_desc;
};
@ -87,31 +89,13 @@ struct osmo_stat_item_group *osmo_stat_item_get_group_by_name_idx(
const struct osmo_stat_item *osmo_stat_item_get_by_name(
const struct osmo_stat_item_group *statg, const char *name);
/*! Retrieve the next value from the osmo_stat_item object.
* If a new value has been set, it is returned. The idx is used to decide
* which value to return.
* On success, *idx is updated to refer to the next unread value. If
* values have been missed due to FIFO overflow, *idx is incremented by
* (1 + num_lost).
* This way, the osmo_stat_item object can be kept stateless from the reader's
* perspective and therefore be used by several backends simultaneously.
*
* \param val the osmo_stat_item object
* \param idx identifies the next value to be read
* \param value a pointer to store the value
* \returns the increment of the index (0: no value has been read,
* 1: one value has been taken,
* (1+n): n values have been skipped, one has been taken)
*/
int osmo_stat_item_get_next(const struct osmo_stat_item *item, int32_t *idx, int32_t *value);
/*! Get the last (freshest) value */
static int32_t osmo_stat_item_get_last(const struct osmo_stat_item *item);
/*! Skip all values of the item and update idx accordingly */
int osmo_stat_item_discard(const struct osmo_stat_item *item, int32_t *idx);
/*! Skip all values of all items and update idx accordingly */
int osmo_stat_item_discard_all(int32_t *idx);
typedef int (*osmo_stat_item_handler_t)(
@ -119,10 +103,6 @@ typedef int (*osmo_stat_item_handler_t)(
typedef int (*osmo_stat_item_group_handler_t)(struct osmo_stat_item_group *, void *);
/*! Iteate over all items
* \param[in] handle_item Call-back function, aborts if rc < 0
* \param[in] data Private data handed through to \a handle_item
*/
int osmo_stat_item_for_each_item(struct osmo_stat_item_group *statg,
osmo_stat_item_handler_t handle_item, void *data);

85
src/stat_item.c
View File

@ -1,5 +1,5 @@
/*! \file stat_item.c
* utility routines for keeping conters about events and the event rates. */
* utility routines for keeping statistical values */
/*
* (C) 2015 by Sysmocom s.f.m.c. GmbH
* (C) 2009-2010 by Harald Welte <laforge@gnumonks.org>
@ -24,7 +24,31 @@
/*! \addtogroup osmo_stat_item
* @{
* \file stat_item.c */
*
* This osmo_stat_item module adds instrumentation capabilities to
* gather measurement and statistical values in a similar fashion to
* what we have as \ref osmo_counter_group.
*
* As opposed to counters, osmo_stat_item do not increment but consist
* of a configurable-sized FIFO, which can store not only the current
* (most recent) value, but also historic values.
*
* The only supported value type is an int32_t.
*
* Getting values from the osmo_stat_item does not modify its state to
* allow for multiple independent back-ends retrieving values (e.g. VTY
* and statd).
*
* Each value stored in the FIFO of an osmo_stat_item has an associated
* value_id. The value_id is derived from an application-wide globally
* incrementing counter, so (until the counter wraps) more recent
* values will have higher values.
*
* When a new value is set, the oldest value in the FIFO gets silently
* overwritten. Lost values are skipped when getting values from the
* item.
*
*/
#include <stdint.h>
#include <string.h>
@ -35,12 +59,17 @@
#include <osmocom/core/timer.h>
#include <osmocom/core/stat_item.h>
/*! global list of stat_item groups */
static LLIST_HEAD(osmo_stat_item_groups);
/*! counter for assigning globally unique value identifiers */
static int32_t global_value_id = 0;
/*! talloc context from which we allocate */
static void *tall_stat_item_ctx;
/*! Allocate a new group of counters according to description
/*! Allocate a new group of counters according to description.
* Allocate a group of stat items described in \a desc from talloc context \a ctx,
* giving the new group the index \a idx.
* \param[in] ctx \ref talloc context
* \param[in] desc Statistics item group description
* \param[in] idx Index of new stat item group
@ -112,13 +141,19 @@ struct osmo_stat_item_group *osmo_stat_item_group_alloc(void *ctx,
return group;
}
/*! Free the memory for the specified group of counters */
/*! Free the memory for the specified group of stat items */
void osmo_stat_item_group_free(struct osmo_stat_item_group *grp)
{
llist_del(&grp->list);
talloc_free(grp);
}
/*! Set the a given stat_item to the given value.
* This function adds a new value for the given stat_item at the end of
* the FIFO.
* \param[in] item The stat_item whose \a value we want to set
* \param[in] value The numeric value we want to store at end of FIFO
*/
void osmo_stat_item_set(struct osmo_stat_item *item, int32_t value)
{
item->last_offs += 1;
@ -133,6 +168,22 @@ void osmo_stat_item_set(struct osmo_stat_item *item, int32_t value)
item->values[item->last_offs].id = global_value_id;
}
/*! Retrieve the next value from the osmo_stat_item object.
* If a new value has been set, it is returned. The idx is used to decide
* which value to return.
* On success, *idx is updated to refer to the next unread value. If
* values have been missed due to FIFO overflow, *idx is incremented by
* (1 + num_lost).
* This way, the osmo_stat_item object can be kept stateless from the reader's
* perspective and therefore be used by several backends simultaneously.
*
* \param val the osmo_stat_item object
* \param idx identifies the next value to be read
* \param value a pointer to store the value
* \returns the increment of the index (0: no value has been read,
* 1: one value has been taken,
* (1+n): n values have been skipped, one has been taken)
*/
int osmo_stat_item_get_next(const struct osmo_stat_item *item, int32_t *next_idx,
int32_t *value)
{
@ -170,7 +221,7 @@ int osmo_stat_item_get_next(const struct osmo_stat_item *item, int32_t *next_idx
return idx_delta;
}
/*! Skip all values of this item and update idx accordingly */
/*! Skip/discard all values of this item and update \a idx accordingly */
int osmo_stat_item_discard(const struct osmo_stat_item *item, int32_t *idx)
{
int discarded = item->values[item->last_offs].id + 1 - *idx;
@ -179,7 +230,7 @@ int osmo_stat_item_discard(const struct osmo_stat_item *item, int32_t *idx)
return discarded;
}
/*! Skip all values of all items and update idx accordingly */
/*! Skip all values of all items and update \a idx accordingly */
int osmo_stat_item_discard_all(int32_t *idx)
{
int discarded = global_value_id + 1 - *idx;
@ -188,7 +239,8 @@ int osmo_stat_item_discard_all(int32_t *idx)
return discarded;
}
/*! Initialize the stat item module */
/*! Initialize the stat item module. Call this once from your program.
* \param[in] tall_ctx Talloc context from which this module allocates */
int osmo_stat_item_init(void *tall_ctx)
{
tall_stat_item_ctx = tall_ctx;
@ -196,7 +248,10 @@ int osmo_stat_item_init(void *tall_ctx)
return 0;
}
/*! Search for item group based on group name and index */
/*! Search for item group based on group name and index
* \param[in] name Name of stats_item_group we want to find
* \param[in] idx Index of the group we want to find
* \returns pointer to group, if found; NULL otherwise */
struct osmo_stat_item_group *osmo_stat_item_get_group_by_name_idx(
const char *name, const unsigned int idx)
{
@ -213,7 +268,10 @@ struct osmo_stat_item_group *osmo_stat_item_get_group_by_name_idx(
return NULL;
}
/*! Search for item group based on group name */
/*! Search for item based on group + item name
* \param[in] statg group in which to search for the item
* \param[in] name name of item to search within \a statg
* \returns pointer to item, if found; NULL otherwise */
const struct osmo_stat_item *osmo_stat_item_get_by_name(
const struct osmo_stat_item_group *statg, const char *name)
{
@ -233,6 +291,11 @@ const struct osmo_stat_item *osmo_stat_item_get_by_name(
return NULL;
}
/*! Iterate over all items in group, call user-supplied function on each
* \param[in] statg stat_item group over whose items to iterate
* \param[in] handle_item Call-back function, aborts if rc < 0
* \param[in] data Private data handed through to \a handle_item
*/
int osmo_stat_item_for_each_item(struct osmo_stat_item_group *statg,
osmo_stat_item_handler_t handle_item, void *data)
{
@ -249,6 +312,10 @@ int osmo_stat_item_for_each_item(struct osmo_stat_item_group *statg,
return rc;
}
/*! Iterate over all stat_item groups in system, call user-supplied function on each
* \param[in] handle_group Call-back function, aborts if rc < 0
* \param[in] data Private data handed through to \a handle_group
*/
int osmo_stat_item_for_each_group(osmo_stat_item_group_handler_t handle_group, void *data)
{
struct osmo_stat_item_group *statg;