libosmocore 1.13.1.1-afb4 Osmocom core library

Data Fields
osmo_time_cc_cfg Struct Reference
Cumulative counter of time as rate counter.

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