1QUIC Statistics Manager
2=======================
3
4The statistics manager keeps track of RTT statistics for use by the QUIC
5implementation.
6
7It provides the following interface:
8
9Instantiation
10-------------
11
12The QUIC statistics manager is instantiated as follows:
13
14```c
15typedef struct ossl_statm_st {
16    ...
17} OSSL_STATM;
18
19int ossl_statm_init(OSSL_STATM *statm);
20
21void ossl_statm_destroy(OSSL_STATM *statm);
22```
23
24The structure is defined in headers, so it may be initialised without needing
25its own memory allocation. However, other code should not examine the fields of
26`OSSL_STATM` directly.
27
28Get RTT Info
29------------
30
31The current RTT info is retrieved using the function `ossl_statm_get_rtt_info`,
32which fills an `OSSL_RTT_INFO` structure:
33
34```c
35typedef struct ossl_rtt_info_st {
36    /* As defined in RFC 9002. */
37    OSSL_TIME smoothed_rtt, latest_rtt, rtt_variance, min_rtt,
38              max_ack_delay;
39} OSSL_RTT_INFO;
40
41void ossl_statm_get_rtt_info(OSSL_STATM *statm, OSSL_RTT_INFO *rtt_info);
42```
43
44Update RTT
45----------
46
47New RTT samples are provided using the  `ossl_statm_update_rtt` function:
48
49  - `ack_delay`. This is the ACK Delay value; see RFC 9000.
50
51  - `override_latest_rtt` provides a new latest RTT sample. If it is
52    `OSSL_TIME_ZERO`, the existing Latest RTT value is used when updating the
53    RTT.
54
55The maximum ACK delay configured using `ossl_statm_set_max_ack_delay` is not
56enforced automatically on the `ack_delay` argument as the circumstances where
57this should be enforced are context sensitive. It is the caller's responsibility
58to retrieve the value and enforce the maximum ACK delay if appropriate.
59
60```c
61void ossl_statm_update_rtt(OSSL_STATM *statm,
62                           OSSL_TIME ack_delay,
63                           OSSL_TIME override_latest_rtt);
64```
65
66Set Max. Ack Delay
67------------------
68
69Sets the maximum ACK delay field reported by `OSSL_RTT_INFO`.
70
71```c
72void ossl_statm_set_max_ack_delay(OSSL_STATM *statm, OSSL_TIME max_ack_delay);
73```
74