mirror of https://gerrit.osmocom.org/libosmocore
[doc] counter.[ch] Add Doxygen API documentation
This adds a more complete set of API documentation for all osmo_counter relatedd functions and definitions. Change-Id: I24283c05620ee86a8beb165af98a85d754549efb
This commit is contained in:
parent
781951bcf9
commit
17bbaa324b
|
@ -3,7 +3,7 @@
|
||||||
/*! \file counter.h
|
/*! \file counter.h
|
||||||
* Common routines regarding counter handling */
|
* Common routines regarding counter handling */
|
||||||
|
|
||||||
/*! structure representing a single counter */
|
/*! Structure representing a single counter */
|
||||||
struct osmo_counter {
|
struct osmo_counter {
|
||||||
struct llist_head list; /*!< internal list head */
|
struct llist_head list; /*!< internal list head */
|
||||||
const char *name; /*!< human-readable name */
|
const char *name; /*!< human-readable name */
|
||||||
|
@ -12,13 +12,15 @@ struct osmo_counter {
|
||||||
unsigned long previous; /*!< previous value */
|
unsigned long previous; /*!< previous value */
|
||||||
};
|
};
|
||||||
|
|
||||||
/*! Decrement counter */
|
/*! Decrement given counter by one
|
||||||
|
* \param[in] ctr Counter that's to be decremented */
|
||||||
static inline void osmo_counter_dec(struct osmo_counter *ctr)
|
static inline void osmo_counter_dec(struct osmo_counter *ctr)
|
||||||
{
|
{
|
||||||
ctr->value--;
|
ctr->value--;
|
||||||
}
|
}
|
||||||
|
|
||||||
/*! Increment counter */
|
/*! Increment counter by one.
|
||||||
|
* \param[in] Counter that's to be incremented */
|
||||||
static inline void osmo_counter_inc(struct osmo_counter *ctr)
|
static inline void osmo_counter_inc(struct osmo_counter *ctr)
|
||||||
{
|
{
|
||||||
ctr->value++;
|
ctr->value++;
|
||||||
|
@ -36,25 +38,12 @@ static inline void osmo_counter_reset(struct osmo_counter *ctr)
|
||||||
ctr->value = 0;
|
ctr->value = 0;
|
||||||
}
|
}
|
||||||
|
|
||||||
/*! Allocate a new counter */
|
|
||||||
struct osmo_counter *osmo_counter_alloc(const char *name);
|
struct osmo_counter *osmo_counter_alloc(const char *name);
|
||||||
|
|
||||||
/*! Free the specified counter
|
|
||||||
* \param[in] ctr Counter
|
|
||||||
*/
|
|
||||||
void osmo_counter_free(struct osmo_counter *ctr);
|
void osmo_counter_free(struct osmo_counter *ctr);
|
||||||
|
|
||||||
/*! Iterate over all counters
|
|
||||||
* \param[in] handle_counter Call-back function, aborts if rc < 0
|
|
||||||
* \param[in] data Private dtata handed through to \a handle_counter
|
|
||||||
*/
|
|
||||||
int osmo_counters_for_each(int (*handle_counter)(struct osmo_counter *, void *), void *data);
|
int osmo_counters_for_each(int (*handle_counter)(struct osmo_counter *, void *), void *data);
|
||||||
|
|
||||||
/*! Resolve counter by human-readable name
|
|
||||||
* \param[in] name human-readable name of counter
|
|
||||||
* \returns pointer to counter (\ref osmo_counter) or NULL otherwise
|
|
||||||
*/
|
|
||||||
struct osmo_counter *osmo_counter_get_by_name(const char *name);
|
struct osmo_counter *osmo_counter_get_by_name(const char *name);
|
||||||
|
|
||||||
/*! Return the counter difference since the last call to this function */
|
|
||||||
int osmo_counter_difference(struct osmo_counter *ctr);
|
int osmo_counter_difference(struct osmo_counter *ctr);
|
||||||
|
|
|
@ -29,8 +29,12 @@
|
||||||
|
|
||||||
static LLIST_HEAD(counters);
|
static LLIST_HEAD(counters);
|
||||||
|
|
||||||
|
/*! Global talloc context for all osmo_counter allocations. */
|
||||||
void *tall_ctr_ctx;
|
void *tall_ctr_ctx;
|
||||||
|
|
||||||
|
/*! Allocate a new counter with given name. Allocates from tall_ctr_ctx
|
||||||
|
* \param[in] name Human-readable string name for the counter
|
||||||
|
* \returns Allocated counter on success; NULL on error */
|
||||||
struct osmo_counter *osmo_counter_alloc(const char *name)
|
struct osmo_counter *osmo_counter_alloc(const char *name)
|
||||||
{
|
{
|
||||||
struct osmo_counter *ctr = talloc_zero(tall_ctr_ctx, struct osmo_counter);
|
struct osmo_counter *ctr = talloc_zero(tall_ctr_ctx, struct osmo_counter);
|
||||||
|
@ -44,12 +48,18 @@ struct osmo_counter *osmo_counter_alloc(const char *name)
|
||||||
return ctr;
|
return ctr;
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/*! Release/Destroy a given counter
|
||||||
|
* \param[in] ctr Counter to be destroyed */
|
||||||
void osmo_counter_free(struct osmo_counter *ctr)
|
void osmo_counter_free(struct osmo_counter *ctr)
|
||||||
{
|
{
|
||||||
llist_del(&ctr->list);
|
llist_del(&ctr->list);
|
||||||
talloc_free(ctr);
|
talloc_free(ctr);
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/*! Iterate over all counters; call \a handle_cunter call-back for each.
|
||||||
|
* \param[in] handle_counter Call-back to be called for each counter; aborts if rc < 0
|
||||||
|
* \param[in] data Opaque data passed through to \a handle_counter function
|
||||||
|
* \returns 0 if all \a handle_counter calls successfull; negative on error */
|
||||||
int osmo_counters_for_each(int (*handle_counter)(struct osmo_counter *, void *),
|
int osmo_counters_for_each(int (*handle_counter)(struct osmo_counter *, void *),
|
||||||
void *data)
|
void *data)
|
||||||
{
|
{
|
||||||
|
@ -65,6 +75,9 @@ int osmo_counters_for_each(int (*handle_counter)(struct osmo_counter *, void *),
|
||||||
return rc;
|
return rc;
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/*! Find a counter by its name.
|
||||||
|
* \param[in] name Name used to look-up/search counter
|
||||||
|
* \returns Counter on success; NULL if not found */
|
||||||
struct osmo_counter *osmo_counter_get_by_name(const char *name)
|
struct osmo_counter *osmo_counter_get_by_name(const char *name)
|
||||||
{
|
{
|
||||||
struct osmo_counter *ctr;
|
struct osmo_counter *ctr;
|
||||||
|
@ -76,6 +89,11 @@ struct osmo_counter *osmo_counter_get_by_name(const char *name)
|
||||||
return NULL;
|
return NULL;
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/*! Compute difference between current and previous counter value.
|
||||||
|
* \param[in] ctr Counter of which the difference is to be computed
|
||||||
|
* \returns Delta value between current counter and previous counter. Please
|
||||||
|
* note that the actual counter values are unsigned long, while the
|
||||||
|
* difference is computed as signed integer! */
|
||||||
int osmo_counter_difference(struct osmo_counter *ctr)
|
int osmo_counter_difference(struct osmo_counter *ctr)
|
||||||
{
|
{
|
||||||
int delta = ctr->value - ctr->previous;
|
int delta = ctr->value - ctr->previous;
|
||||||
|
|
Loading…
Reference in New Issue