openssl/doc/designs/quic-design/quic-statm.md

QUIC Statistics Manager

The statistics manager keeps track of RTT statistics for use by the QUIC implementation.

It provides the following interface:

Instantiation

The QUIC statistics manager is instantiated as follows:

typedef struct ossl_statm_st {
    ...
} OSSL_STATM;

int ossl_statm_init(OSSL_STATM *statm);

void ossl_statm_destroy(OSSL_STATM *statm);

The structure is defined in headers, so it may be initialised without needing its own memory allocation. However, other code should not examine the fields of OSSL_STATM directly.

Get RTT Info

The current RTT info is retrieved using the function ossl_statm_get_rtt_info, which fills an OSSL_RTT_INFO structure:

typedef struct ossl_rtt_info_st {
    /* As defined in RFC 9002. */
    OSSL_TIME smoothed_rtt, latest_rtt, rtt_variance, min_rtt,
              max_ack_delay;
} OSSL_RTT_INFO;

void ossl_statm_get_rtt_info(OSSL_STATM *statm, OSSL_RTT_INFO *rtt_info);

Update RTT

New RTT samples are provided using the ossl_statm_update_rtt function:

• ack_delay. This is the ACK Delay value; see RFC 9000.

• override_latest_rtt provides a new latest RTT sample. If it is OSSL_TIME_ZERO, the existing Latest RTT value is used when updating the RTT.

The maximum ACK delay configured using ossl_statm_set_max_ack_delay is not enforced automatically on the ack_delay argument as the circumstances where this should be enforced are context sensitive. It is the caller's responsibility to retrieve the value and enforce the maximum ACK delay if appropriate.

void ossl_statm_update_rtt(OSSL_STATM *statm,
                           OSSL_TIME ack_delay,
                           OSSL_TIME override_latest_rtt);

Set Max. Ack Delay

Sets the maximum ACK delay field reported by OSSL_RTT_INFO.

void ossl_statm_set_max_ack_delay(OSSL_STATM *statm, OSSL_TIME max_ack_delay);