[MERGED] libosmocore[master]: [doc] rate_ctr: Extend Doxygen API documentation with human-...

This is merely a historical archive of years 2008-2021, before the migration to mailman3.

A maintained and still updated list archive can be found at https://lists.osmocom.org/hyperkitty/list/gerrit-log@lists.osmocom.org/.

Harald Welte gerrit-no-reply at lists.osmocom.org
Mon Oct 16 13:19:10 UTC 2017


Harald Welte has submitted this change and it was merged.

Change subject: [doc] rate_ctr: Extend Doxygen API documentation with human-readable text on its use
......................................................................


[doc] rate_ctr: Extend Doxygen API documentation with human-readable text on its use

Change-Id: If9abd46e1b0ebb6114522418fd3b45c1d802968a
---
M src/rate_ctr.c
1 file changed, 35 insertions(+), 2 deletions(-)

Approvals:
  Harald Welte: Looks good to me, approved
  Jenkins Builder: Verified



diff --git a/src/rate_ctr.c b/src/rate_ctr.c
index 2985bbb..a04a776 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 @@
 	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 @@
 /*! 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)
 {

-- 
To view, visit https://gerrit.osmocom.org/4283
To unsubscribe, visit https://gerrit.osmocom.org/settings

Gerrit-MessageType: merged
Gerrit-Change-Id: If9abd46e1b0ebb6114522418fd3b45c1d802968a
Gerrit-PatchSet: 1
Gerrit-Project: libosmocore
Gerrit-Branch: master
Gerrit-Owner: Harald Welte <laforge at gnumonks.org>
Gerrit-Reviewer: Harald Welte <laforge at gnumonks.org>
Gerrit-Reviewer: Jenkins Builder



More information about the gerrit-log mailing list