/*! \file time_cc.h
 * Report the cumulative counter of time for which a flag is true as rate counter.
 */
/* Copyright (C) 2021 by sysmocom - s.f.m.c. GmbH <info@sysmocom.de>
 *
 * All Rights Reserved
 *
 * Author: Neels Hofmeyr <nhofmeyr@sysmocom.de>
 *
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU Affero General Public License as published by
 * the Free Software Foundation; either version 3 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU Affero General Public License for more details.
 *
 * You should have received a copy of the GNU Affero General Public License
 * along with this program.  If not, see <http://www.gnu.org/licenses/>.
 *
 */
#pragma once

#include <stdint.h>

#include <osmocom/core/timer.h>

/*! \defgroup time_cc  Cumulative counter of time as rate counter.
 * @{
 * \file time_cc.h
 */

struct osmo_tdef;
struct rate_ctr;

/*! 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()"
 *
 */
struct osmo_time_cc_cfg {
	/*! 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. */
	uint64_t gran_usec;
	/*! Nr of microseconds above n * gran_usec at which to trigger a counter increment. When zero, use half a
	 * gran_usec. */
	uint64_t round_threshold_usec;
	/*! Forget counted sub-gran time after the flag was false for this long. */
	uint64_t forget_sum_usec;
	/*! Rate counter to report to, or NULL to not use it. */
	struct rate_ctr *rate_ctr;

	/*! Update gran_usec from this T timer value, or zero to not use any T timer. */
	int T_gran;
	/*! Update round_threshold_usec from this T timer value, or zero to not use any T timer. */
	int T_round_threshold;
	/*! Update forget_sum_usec from this T timer value, or zero to not use any T timer. */
	int T_forget_sum;
	/*! Look up T_gran and T_forget_sum in this list of timers, or NULL to not use any T timers. */
	struct osmo_tdef *T_defs;
};

/*! Report the cumulative counter of time for which a flag is true as rate counter.
 * See also osmo_time_cc_cfg for details on configuring.
 *
 * Usage:
 *
 *     struct my_obj {
 *             struct osmo_time_cc flag_cc;
 *     };
 *
 *     void my_obj_init(struct my_obj *my_obj)
 *     {
 *             osmo_time_cc_init(&my_obj->flag_cc);
 *             my_obj->flag_cc.cfg = (struct osmo_time_cc_cfg){
 *                             .gran_usec = 1000000,
 *                             .forget_sum_usec = 60000000,
 *                             .rate_ctr = rate_ctr_group_get_ctr(my_ctrg, MY_CTR_IDX),
 *                     };
 *             // optional: set initial flag state, default is 'false':
 *             // osmo_time_cc_set_flag(&my_obj->flag_cc, false);
 *     }
 *
 *     void my_obj_event(struct my_obj *my_obj, bool flag)
 *     {
 *             osmo_time_cc_set_flag(&my_obj->flag_cc, flag);
 *     }
 *
 *     void my_obj_destruct(struct my_obj *my_obj)
 *     {
 *             osmo_time_cc_cleanup(&my_obj->flag_cc);
 *     }
 */
struct osmo_time_cc {
	struct osmo_time_cc_cfg cfg;

	bool flag_state;

	/*! Overall cumulative sum. Does not get reset for the entire lifetime of an osmo_time_cc.
	 * (Informational only, not used by the osmo_time_cc implementation.) */
	uint64_t total_sum;

	struct osmo_timer_list timer;

	/*! CLOCK_MONOTONIC reading in microseconds, at the time when the osmo_time_cc instance started counting. */
	uint64_t start_time;
	/*! CLOCK_MONOTONIC reading in microseconds, at the time when the osmo_time_cc last evaluated the flag state and
	 * possibly added to the cumulated sum. */
	uint64_t last_counted_time;

	/*! Internal cumulative counter of time that flag_state was true. It may get reset to zero regularly, depending
	 * on cfg.forget_sum_usec. This is the basis for incrementing cfg.rate_ctr. */
	uint64_t sum;
	/*! The amount of time that already reported cfg.rate_ctr increments account for. This may be ahead of or behind
	 * 'sum', depending on cfg.round_threshold_usec. */
	uint64_t reported_sum;
};

void osmo_time_cc_init(struct osmo_time_cc *tc);
void osmo_time_cc_set_flag(struct osmo_time_cc *tc, bool flag);
void osmo_time_cc_cleanup(struct osmo_time_cc *tc);

/*! @} */