Home | History | Annotate | Line # | Download | only in quic-design 
      1 QUIC Statistics Manager
      2 =======================
      3 
      4 The statistics manager keeps track of RTT statistics for use by the QUIC
      5 implementation.
      6 
      7 It provides the following interface:
      8 
      9 Instantiation
     10 -------------
     11 
     12 The QUIC statistics manager is instantiated as follows:
     13 
     14 ```c
     15 typedef struct ossl_statm_st {
     16     ...
     17 } OSSL_STATM;
     18 
     19 int ossl_statm_init(OSSL_STATM *statm);
     20 
     21 void ossl_statm_destroy(OSSL_STATM *statm);
     22 ```
     23 
     24 The structure is defined in headers, so it may be initialised without needing
     25 its own memory allocation. However, other code should not examine the fields of
     26 `OSSL_STATM` directly.
     27 
     28 Get RTT Info
     29 ------------
     30 
     31 The current RTT info is retrieved using the function `ossl_statm_get_rtt_info`,
     32 which fills an `OSSL_RTT_INFO` structure:
     33 
     34 ```c
     35 typedef 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 
     41 void ossl_statm_get_rtt_info(OSSL_STATM *statm, OSSL_RTT_INFO *rtt_info);
     42 ```
     43 
     44 Update RTT
     45 ----------
     46 
     47 New 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 
     55 The maximum ACK delay configured using `ossl_statm_set_max_ack_delay` is not
     56 enforced automatically on the `ack_delay` argument as the circumstances where
     57 this should be enforced are context sensitive. It is the caller's responsibility
     58 to retrieve the value and enforce the maximum ACK delay if appropriate.
     59 
     60 ```c
     61 void ossl_statm_update_rtt(OSSL_STATM *statm,
     62                            OSSL_TIME ack_delay,
     63                            OSSL_TIME override_latest_rtt);
     64 ```
     65 
     66 Set Max. Ack Delay
     67 ------------------
     68 
     69 Sets the maximum ACK delay field reported by `OSSL_RTT_INFO`.
     70 
     71 ```c
     72 void ossl_statm_set_max_ack_delay(OSSL_STATM *statm, OSSL_TIME max_ack_delay);
     73 ```
     74