Trait CongestionController

pub trait CongestionController:
    'static
    + Clone
    + Send
    + Debug
    + Sealed {
    type PacketInfo: Copy + Send + Sized + Debug;

    // Required methods
    fn congestion_window(&self) -> u32;
    fn bytes_in_flight(&self) -> u32;
    fn is_congestion_limited(&self) -> bool;
    fn requires_fast_retransmission(&self) -> bool;
    fn on_packet_sent<Pub: Publisher>(
        &mut self,
        time_sent: Timestamp,
        sent_bytes: usize,
        app_limited: Option<bool>,
        rtt_estimator: &RttEstimator,
        publisher: &mut Pub,
    ) -> Self::PacketInfo;
    fn on_rtt_update<Pub: Publisher>(
        &mut self,
        time_sent: Timestamp,
        now: Timestamp,
        rtt_estimator: &RttEstimator,
        publisher: &mut Pub,
    );
    fn on_ack<Pub: Publisher>(
        &mut self,
        newest_acked_time_sent: Timestamp,
        bytes_acknowledged: usize,
        newest_acked_packet_info: Self::PacketInfo,
        rtt_estimator: &RttEstimator,
        random_generator: &mut dyn Generator,
        ack_receive_time: Timestamp,
        publisher: &mut Pub,
    );
    fn on_packet_lost<Pub: Publisher>(
        &mut self,
        lost_bytes: u32,
        packet_info: Self::PacketInfo,
        persistent_congestion: bool,
        new_loss_burst: bool,
        random_generator: &mut dyn Generator,
        timestamp: Timestamp,
        publisher: &mut Pub,
    );
    fn on_explicit_congestion<Pub: Publisher>(
        &mut self,
        ce_count: u64,
        event_time: Timestamp,
        publisher: &mut Pub,
    );
    fn on_mtu_update<Pub: Publisher>(
        &mut self,
        max_data_size: u16,
        publisher: &mut Pub,
    );
    fn on_packet_discarded<Pub: Publisher>(
        &mut self,
        bytes_sent: usize,
        publisher: &mut Pub,
    );
    fn earliest_departure_time(&self) -> Option<Timestamp>;

    // Provided method
    fn send_quantum(&self) -> Option<usize> { ... }
}

An algorithm for controlling congestion.

NOTE: This trait is considered unstable and can only be implemented by including the unstable-congestion-controller feature.

Required Associated Types

type PacketInfo: Copy + Send + Sized + Debug

Additional metadata about a packet to track until a sent packet is either acknowledged or declared lost

Required Methods

fn congestion_window(&self) -> u32

Returns the size of the current congestion window in bytes

fn bytes_in_flight(&self) -> u32

Returns the current bytes in flight

fn is_congestion_limited(&self) -> bool

Returns true if the congestion window does not have sufficient space for a packet of max_datagram_size considering the current bytes in flight

fn requires_fast_retransmission(&self) -> bool

Returns true if the current state of the congestion controller requires a packet to be transmitted without respecting the available congestion window

fn on_packet_sent<Pub: Publisher>( &mut self, time_sent: Timestamp, sent_bytes: usize, app_limited: Option<bool>, rtt_estimator: &RttEstimator, publisher: &mut Pub, ) -> Self::PacketInfo

Invoked when a packet is sent

The PacketInfo returned by this method will be passed to on_packet_ack if the packet is acknowledged and the packet was the newest acknowledged in the ACK frame, or to on_packet_lost if the packet was declared lost.

app_limited indicates whether the application has enough data to send to fill the congestion window. This value will be None for Initial and Handshake packets.

Note: Sent bytes may be 0 in the case the packet being sent contains only ACK frames. These pure ACK packets are not congestion-controlled to ensure congestion control does not impede congestion feedback.

fn on_rtt_update<Pub: Publisher>( &mut self, time_sent: Timestamp, now: Timestamp, rtt_estimator: &RttEstimator, publisher: &mut Pub, )

Invoked each time the round trip time is updated, which is whenever the newest acknowledged packet in an ACK frame is newly acknowledged

fn on_ack<Pub: Publisher>( &mut self, newest_acked_time_sent: Timestamp, bytes_acknowledged: usize, newest_acked_packet_info: Self::PacketInfo, rtt_estimator: &RttEstimator, random_generator: &mut dyn Generator, ack_receive_time: Timestamp, publisher: &mut Pub, )

Invoked when an acknowledgement of one or more previously unacknowledged packets is received

Generally the bytes_acknowledged value is aggregated over all newly acknowledged packets, though it is possible this method may be called multiple times for one acknowledgement. In either case, newest_acked_time_sent and newest_acked_packet_info represent the newest acknowledged packet contributing to bytes_acknowledged.

fn on_packet_lost<Pub: Publisher>( &mut self, lost_bytes: u32, packet_info: Self::PacketInfo, persistent_congestion: bool, new_loss_burst: bool, random_generator: &mut dyn Generator, timestamp: Timestamp, publisher: &mut Pub, )

Invoked when a packet is declared lost

new_loss_burst is true if the lost packet is the first in a contiguous series of lost packets. This can be used for measuring or filtering out noise from burst losses.

fn on_explicit_congestion<Pub: Publisher>( &mut self, ce_count: u64, event_time: Timestamp, publisher: &mut Pub, )

Invoked when the Explicit Congestion Notification counter increases.

ce_count represents the incremental number of packets marked with the ECN CE codepoint

fn on_mtu_update<Pub: Publisher>( &mut self, max_data_size: u16, publisher: &mut Pub, )

Invoked when the path maximum transmission unit is updated.

fn on_packet_discarded<Pub: Publisher>( &mut self, bytes_sent: usize, publisher: &mut Pub, )

Invoked for each packet discarded when a packet number space is discarded.

fn earliest_departure_time(&self) -> Option<Timestamp>

Returns the earliest time that a packet may be transmitted.

If the time is in the past or is None, the packet should be transmitted immediately.

Provided Methods

fn send_quantum(&self) -> Option<usize>

The maximum number of bytes for an aggregation of packets scheduled and transmitted together.

If the value is None, the congestion controller does not influence the send aggregation.

The effect of this value is dependent on platform support for GSO (Generic Segmentation Offload) as well as the configured MaxSegments value.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors

impl CongestionController for BbrCongestionController

type PacketInfo = PacketInfo

impl CongestionController for CubicCongestionController

type PacketInfo = ()