summaryrefslogtreecommitdiffstats
path: root/include
diff options
context:
space:
mode:
authorHarald Welte <laforge@gnumonks.org>2017-10-15 19:24:57 +0200
committerHarald Welte <laforge@gnumonks.org>2017-10-16 14:18:50 +0200
commit781951bcf9864ae06741a0d76d3807e332a8faf9 (patch)
treebed269b6a8df1d307672ae770c70f6f1983cf03f /include
parent216338c369fcfc6f2b90f6bf784288258c9b5603 (diff)
[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
Diffstat (limited to 'include')
-rw-r--r--include/osmocom/core/stat_item.h46
1 files changed, 13 insertions, 33 deletions
diff --git a/include/osmocom/core/stat_item.h b/include/osmocom/core/stat_item.h
index 4cee8a8b..260ffb1c 100644
--- a/include/osmocom/core/stat_item.h
+++ b/include/osmocom/core/stat_item.h
@@ -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);