nquic_cc behaviour (nquic v1.0.0)

View Source

Congestion control behaviour and dispatch per RFC 9002 Section 7.

Defines the nquic_cc behaviour that congestion control algorithms must implement. Provides a dispatch layer that wraps the algorithm module and its opaque state. Currently ships with nquic_cc_newreno.

Summary

Types

algorithm()
cc_state()

Callbacks

get_cwnd/1
get_ssthresh/1
init()
on_congestion_event/4
on_idle_reset/1
on_packet_acked/4
on_packet_sent/3
on_persistent_congestion/1
on_spurious_congestion/1

Functions

get_cwnd/1

Get the current congestion window size in bytes.

get_max_datagram_size/1

Get the current maximum datagram size.

get_ssthresh/1

Get the current slow start threshold.

new(Algorithm)

Create a new congestion control state for the given algorithm.

new(Algorithm, Opts)

Create a new congestion control state with options. CUBIC understands slow_start => standard | hystart_plus_plus (RFC 9406). Other algorithms ignore unknown keys.

on_congestion_event/4

Notify the congestion controller of a loss event.

on_idle_reset/1

Reset the congestion controller after an idle period (RFC 9002 Section 7.8). The window collapses to the initial window so the sender does not burst beyond the path's available capacity after a long pause.

on_packet_acked/4

Notify the congestion controller that a packet was acknowledged.

on_packet_sent/3

Notify the congestion controller that a packet was sent.

on_persistent_congestion/1

Notify the congestion controller that persistent congestion has been detected (RFC 9002 Section 7.6). The congestion window must collapse to the minimum window (2 * max_datagram_size).

on_spurious_congestion/1

Notify the congestion controller that the most recent congestion-event reduction was triggered by a spurious loss (RFC 9002 Appendix A.10). Implementations should restore the pre-reduction snapshot of the window state. If no snapshot is available (no rollback pending), this is a no-op.

set_max_datagram_size/2

Set the maximum datagram size for congestion window calculations.

Types

algorithm()

-type algorithm() :: newreno | cubic.

cc_state()

-type cc_state() :: {module(), dynamic()}.

Callbacks

get_cwnd/1

-callback get_cwnd(dynamic()) -> non_neg_integer().

get_ssthresh/1

-callback get_ssthresh(dynamic()) -> non_neg_integer() | undefined.

init()

-callback init() -> dynamic().

on_congestion_event/4

-callback on_congestion_event(dynamic(), non_neg_integer(), non_neg_integer(), non_neg_integer()) ->
                                 dynamic().

on_idle_reset/1

-callback on_idle_reset(dynamic()) -> dynamic().

on_packet_acked/4

-callback on_packet_acked(dynamic(),
                          #sent_packet{packet_number :: nquic_packet_number:t(),
                                       time_sent :: non_neg_integer(),
                                       size :: non_neg_integer(),
                                       ack_eliciting :: boolean(),
                                       in_flight :: boolean(),
                                       frames :: [nquic_frame:t()]},
                          non_neg_integer(),
                          map()) ->
                             dynamic().

on_packet_sent/3

-callback on_packet_sent(dynamic(), non_neg_integer(), non_neg_integer()) -> dynamic().

on_persistent_congestion/1

-callback on_persistent_congestion(dynamic()) -> dynamic().

on_spurious_congestion/1

-callback on_spurious_congestion(dynamic()) -> dynamic().

Functions

get_cwnd/1

-spec get_cwnd(cc_state()) -> non_neg_integer().

Get the current congestion window size in bytes.

get_max_datagram_size/1

-spec get_max_datagram_size({module(), dynamic()}) -> pos_integer().

Get the current maximum datagram size.

get_ssthresh/1

-spec get_ssthresh(cc_state()) -> non_neg_integer() | undefined.

Get the current slow start threshold.

new(Algorithm)

-spec new(algorithm() | dynamic()) -> cc_state().

Create a new congestion control state for the given algorithm.

new(Algorithm, Opts)

-spec new(algorithm() | dynamic(), map()) -> cc_state().

Create a new congestion control state with options. CUBIC understands slow_start => standard | hystart_plus_plus (RFC 9406). Other algorithms ignore unknown keys.

on_congestion_event/4

-spec on_congestion_event(cc_state(), non_neg_integer(), non_neg_integer(), non_neg_integer()) ->
                             cc_state().

Notify the congestion controller of a loss event.

on_idle_reset/1

-spec on_idle_reset(cc_state()) -> cc_state().

Reset the congestion controller after an idle period (RFC 9002 Section 7.8). The window collapses to the initial window so the sender does not burst beyond the path's available capacity after a long pause.

on_packet_acked/4

-spec on_packet_acked(cc_state(),
                      #sent_packet{packet_number :: nquic_packet_number:t(),
                                   time_sent :: non_neg_integer(),
                                   size :: non_neg_integer(),
                                   ack_eliciting :: boolean(),
                                   in_flight :: boolean(),
                                   frames :: [nquic_frame:t()]},
                      non_neg_integer(),
                      map()) ->
                         cc_state().

Notify the congestion controller that a packet was acknowledged.

on_packet_sent/3

-spec on_packet_sent(cc_state(), non_neg_integer(), non_neg_integer()) -> cc_state().

Notify the congestion controller that a packet was sent.

on_persistent_congestion/1

-spec on_persistent_congestion(cc_state()) -> cc_state().

Notify the congestion controller that persistent congestion has been detected (RFC 9002 Section 7.6). The congestion window must collapse to the minimum window (2 * max_datagram_size).

on_spurious_congestion/1

-spec on_spurious_congestion(cc_state()) -> cc_state().

Notify the congestion controller that the most recent congestion-event reduction was triggered by a spurious loss (RFC 9002 Appendix A.10). Implementations should restore the pre-reduction snapshot of the window state. If no snapshot is available (no rollback pending), this is a no-op.

set_max_datagram_size/2

-spec set_max_datagram_size({module(), dynamic()}, pos_integer()) -> {module(), dynamic()}.

Set the maximum datagram size for congestion window calculations.