Configuration for osmo_time_cc. More...

#include <time_cc.h>

Data Fields
uint64_t	gran_usec
	Granularity in microseconds: nr of microseconds that one rate_ctr increment represents. More...

uint64_t	round_threshold_usec
	Nr of microseconds above n * gran_usec at which to trigger a counter increment. More...

uint64_t	forget_sum_usec
	Forget counted sub-gran time after the flag was false for this long. More...

struct rate_ctr *	rate_ctr
	Rate counter to report to, or NULL to not use it. More...

int	T_gran
	Update gran_usec from this T timer value, or zero to not use any T timer. More...

int	T_round_threshold
	Update round_threshold_usec from this T timer value, or zero to not use any T timer. More...

int	T_forget_sum
	Update forget_sum_usec from this T timer value, or zero to not use any T timer. More...

struct osmo_tdef *	T_defs
	Look up T_gran and T_forget_sum in this list of timers, or NULL to not use any T timers. More...

Detailed Description

Configuration for osmo_time_cc.

Report the cumulative counter of time for which a flag is true as rate counter. For example, for each second that the flag is true, increment a rate counter.

The flag to be monitored is reported by osmo_time_cc_set_flag().

The granularity defines how much time one rate counter increment represents: the default configuration is gran_usec = 1000000, i.e. one rate counter increment represents one second.

Reporting as rate counter is configurable by round_threshold_usec and forget_sum_usec, examples:

round_threshold_usec:

To get "ceil()" behavior, set round_threshold_usec = 1. This increments the rate counter for each gran_usec period where the flag was seen true, even if it was true for only a very short fraction of a gran_usec period.
To get "round()" behavior, set round_threshold_usec = half of gran_usec. The rate counter increments when the flag has been true for 0.5 of a gran_usec (and then again at 1.5 * gran_usec) of 'true' flag. round_threshold_usec = 0 is a special value that means to use half of gran_usec.
To get "floor()" behavior, set round_threshold_usec >= gran_usec. The rate counter increments when reaching full gran_usec periods of the flag being true.

forget_sum_usec: This is a tradeoff between the accuracy of the reported rate counter and making sure that the events reported are not irrelevantly long ago.

To keep sub-granularity-period surplus time forever, set forget_sum_usec = 0.
To keep surplus time for up to a minute, set forget_sum_usec = 60000000 (60 seconds).
To get rid of "leftover" time (almost) immediately after the flag goes false, set forget_sum_usec = 1.
If gran_usec is set to one second and forget_sum_usec is set to one minute, the reported rate counter has a possible inaccuracy of 1/60th, but makes sure that no timings older than a minute affect the current reports.

Reporting modes in detail:

The rate_ctr increments when the cumulative counter passes round_threshold_usec (default: half of gran_usec).

                   sum ^
                       |                                          ________
                       |                                         /
                       |                                        /
                       |                                       /
              3*gran --+--------------------------------------+
                       |                                     /:
                       |                                    / :
                       | - - - - - - - - - - - - - - - - - /  :
                       |                                  /.  :
                       |                                 / .  :
              2*gran --+--------------------------------+  .  :
                       |                               /:  .  :
                       |                              / :  .  :
                       | - - - - - - - - - -_________/  :  .  :
                       |                   /         .  :  .  :
                       |                  /          .  :  .  :
              1*gran --+-----------------+           .  :  .  :
                       |                /:           .  :  .  :
                       |               / :           .  :  .  :
                       | - - - - - - -/  :           .  :  .  :
                       |             /.  :           .  :  .  :
                       | ....-------' .  :           .  :  .  :
                    0  +------------------------------------------------------------------------> elapsed time
                                      .  :           .  :  .  :
                          _   _      _______         ____________
              flag:    __| |_| |____| .  :  |_______|.  :  .  :  |__________
                       f t f t f    t .  :  f       t.  :  .  :  f

round_threshold_usec : . : . : . : = 1 usec: 0 1 . :2 . :3 . :4 = "ceil()" = 0 == gran_usec/2: 0 1 : 2 : 3 : = "round()" >= gran_usec: 0 1 2 3 = "floor()"

Field Documentation

◆ forget_sum_usec

uint64_t osmo_time_cc_cfg::forget_sum_usec

Forget counted sub-gran time after the flag was false for this long.

◆ gran_usec

uint64_t osmo_time_cc_cfg::gran_usec

Granularity in microseconds: nr of microseconds that one rate_ctr increment represents.

A typical value is gran_usec = 1000000, meaning one rate counter increment represents one second. When zero, use 1000000.

◆ rate_ctr

struct rate_ctr* osmo_time_cc_cfg::rate_ctr

Rate counter to report to, or NULL to not use it.

◆ round_threshold_usec

uint64_t osmo_time_cc_cfg::round_threshold_usec

Nr of microseconds above n * gran_usec at which to trigger a counter increment.

When zero, use half a gran_usec.

◆ T_defs

struct osmo_tdef* osmo_time_cc_cfg::T_defs

Look up T_gran and T_forget_sum in this list of timers, or NULL to not use any T timers.

◆ T_forget_sum

int osmo_time_cc_cfg::T_forget_sum

Update forget_sum_usec from this T timer value, or zero to not use any T timer.

◆ T_gran

int osmo_time_cc_cfg::T_gran

Update gran_usec from this T timer value, or zero to not use any T timer.

◆ T_round_threshold

int osmo_time_cc_cfg::T_round_threshold

Update round_threshold_usec from this T timer value, or zero to not use any T timer.

The documentation for this struct was generated from the following file:

include/osmocom/core/time_cc.h

Data Fields