summaryrefslogtreecommitdiffstats
path: root/src
diff options
context:
space:
mode:
authorHarald Welte <laforge@gnumonks.org>2017-10-16 14:09:16 +0200
committerHarald Welte <laforge@gnumonks.org>2017-10-16 14:19:03 +0200
commit53de0d31698e8c598e36ccad9d864c450da343b9 (patch)
treee47308540f9f8b73be9bec8517ca773d33c45ed6 /src
parentf01b2383b1d9bbc8e17e0c5e8c6b1309b456f41f (diff)
[doc] rate_ctr: Extend Doxygen API documentation with human-readable text on its use
Change-Id: If9abd46e1b0ebb6114522418fd3b45c1d802968a
Diffstat (limited to 'src')
-rw-r--r--src/rate_ctr.c37
1 files changed, 35 insertions, 2 deletions
diff --git a/src/rate_ctr.c b/src/rate_ctr.c
index 2985bbb0..a04a7760 100644
--- a/src/rate_ctr.c
+++ b/src/rate_ctr.c
@@ -22,6 +22,37 @@
* @{
* Counters about events and their event rates.
*
+ * As \ref osmo_counter and \ref osmo_stat_item are concerned only with
+ * a single given value that may be increased/decreased, or the difference
+ * to one given previous value, this module adds some support for keeping
+ * long term information about a given event rate.
+ *
+ * A \ref rate_ctr keeps information on the amount of events per second,
+ * per minute, per hour and per day.
+ *
+ * \ref rate_ctr come in groups: An application describes a group of counters
+ * with their names and identities once in a (typically const) \ref
+ * rate_ctr_group_desc.
+ *
+ * As objects (such as e.g. a subscriber or a PDP context) are
+ * allocated dynamically at runtime, the application calls \ref
+ * rate_ctr_group_alloc with a refernce to the \ref
+ * rate_ctr_group_desc, which causes the library to allocate one set of
+ * \ref rate_ctr: One for each in the group.
+ *
+ * The application then uses functions like \ref rate_ctr_add or \ref
+ * rate_ctr_inc to increment the value as certain events (e.g. location
+ * update) happens.
+ *
+ * The library internally keeps a timer once per second which iterates
+ * over all registered counters and which updates the per-second,
+ * per-minute, per-hour and per-day averages based on the current
+ * value.
+ *
+ * The counters can be reported using \ref stats or by VTY
+ * introspection, as well as by any application-specific code accessing
+ * the \ref rate_ctr.intv array directly.
+ *
* \file rate_ctr.c */
#include <stdint.h>
@@ -140,7 +171,9 @@ static void rate_ctr_timer_cb(void *data)
osmo_timer_schedule(&rate_ctr_timer, 1, 0);
}
-/*! Initialize the counter module */
+/*! Initialize the counter module. Call this once from your application.
+ * \param[in] tall_ctx Talloc context from which rate_ctr_group will be allocated
+ * \returns 0 on success; negative on error */
int rate_ctr_init(void *tall_ctx)
{
tall_rate_ctr_ctx = tall_ctx;
@@ -173,7 +206,7 @@ struct rate_ctr_group *rate_ctr_get_group_by_name_idx(const char *name, const un
/*! Search for counter based on group + name
* \param[in] ctrg pointer to \ref rate_ctr_group
* \param[in] name name of counter inside group
- * \returns \ref rate_ctr or NULL in caes of error
+ * \returns \ref rate_ctr or NULL in case of error
*/
const struct rate_ctr *rate_ctr_get_by_name(const struct rate_ctr_group *ctrg, const char *name)
{