feat(proto): expose max_transmit_segments and max_transmit_datagrams in TransportConfig

Author: poka-IT

noq-proto/src/config/transport.rs

@@ -3,7 +3,7 @@ use std::path::Path;
 use std::{
     fmt,
     net::SocketAddr,
-    num::{NonZeroU8, NonZeroU32},
+    num::{NonZeroU8, NonZeroU32, NonZeroUsize},
     sync::Arc,
 };
 
@@ -59,6 +59,9 @@ pub struct TransportConfig {
 
     pub(crate) enable_segmentation_offload: bool,
 
+    pub(crate) max_transmit_segments: NonZeroUsize,
+    pub(crate) max_transmit_datagrams: NonZeroUsize,
+
     pub(crate) address_discovery_role: address_discovery::Role,
 
     pub(crate) max_concurrent_multipath_paths: Option<NonZeroU32>,
@@ -364,6 +367,39 @@ impl TransportConfig {
         self
     }
 
+    /// Maximum number of UDP segments encoded into a single GSO `sendmsg` batch.
+    ///
+    /// Effective batch size is also bounded by the platform's GSO capabilities (Linux with
+    /// kernel ≥ 4.18 reports up to 64 via `UDP_MAX_SEGMENTS`; macOS reports `BATCH_SIZE`;
+    /// Windows reports up to 512). When GSO is unavailable or disabled this setting has
+    /// no effect, every `Transmit` carries a single datagram.
+    ///
+    /// Defaults to **10**, a conservative compromise tuned for multi-connection workloads.
+    /// Single-connection bulk-transfer workloads on Linux+GSO benefit from raising this
+    /// to 40 (≈ 51 KB per `sendmsg` at MTU 1280, 60 KB at MTU 1500), at the cost of a
+    /// proportional increase in per-`Connection` send-buffer pre-allocation.
+    ///
+    /// Worst-case memory cost: `max_transmit_segments * current_mtu` bytes of pre-allocated
+    /// buffer per active `Connection`.
+    pub fn max_transmit_segments(&mut self, value: NonZeroUsize) -> &mut Self {
+        self.max_transmit_segments = value;
+        self
+    }
+
+    /// Maximum number of datagrams produced in a single `drive_transmit` call.
+    ///
+    /// This caps the amount of CPU spent generating datagrams in one go, allowing other
+    /// tasks (notably ACK reception and timer wakeups) to run. It is intended to be kept
+    /// in lockstep with [`TransportConfig::max_transmit_segments`] (recommended ratio: 2×)
+    /// so a single GSO super-segment can hold a couple of transmit drives back-to-back
+    /// without bouncing to the scheduler.
+    ///
+    /// Defaults to **20**.
+    pub fn max_transmit_datagrams(&mut self, value: NonZeroUsize) -> &mut Self {
+        self.max_transmit_datagrams = value;
+        self
+    }
+
     /// Whether to send observed address reports to peers.
     ///
     /// This will aid peers in inferring their reachable address, which in most NATd networks
@@ -563,6 +599,9 @@ impl Default for TransportConfig {
 
             enable_segmentation_offload: true,
 
+            max_transmit_segments: NonZeroUsize::new(10).expect("nonzero"),
+            max_transmit_datagrams: NonZeroUsize::new(20).expect("nonzero"),
+
             address_discovery_role: address_discovery::Role::default(),
 
             // disabled multipath by default
@@ -608,6 +647,8 @@ impl fmt::Debug for TransportConfig {
                 deterministic_packet_numbers: _,
             congestion_controller_factory: _,
             enable_segmentation_offload,
+            max_transmit_segments,
+            max_transmit_datagrams,
             address_discovery_role,
             max_concurrent_multipath_paths,
             default_path_max_idle_timeout,
@@ -648,6 +689,8 @@ impl fmt::Debug for TransportConfig {
             .field("datagram_send_buffer_size", datagram_send_buffer_size)
             // congestion_controller_factory not debug
             .field("enable_segmentation_offload", enable_segmentation_offload)
+            .field("max_transmit_segments", max_transmit_segments)
+            .field("max_transmit_datagrams", max_transmit_datagrams)
             .field("address_discovery_role", address_discovery_role)
             .field(
                 "max_concurrent_multipath_paths",

noq-proto/src/connection/mod.rs

@@ -6966,6 +6966,20 @@ impl Connection {
             .unwrap_or(INITIAL_MTU)
     }
 
+    /// Maximum number of UDP segments allowed in a single GSO `sendmsg` batch.
+    ///
+    /// See [`TransportConfig::max_transmit_segments`].
+    pub fn max_transmit_segments(&self) -> std::num::NonZeroUsize {
+        self.config.max_transmit_segments
+    }
+
+    /// Maximum number of datagrams produced in a single `poll_transmit` driver iteration.
+    ///
+    /// See [`TransportConfig::max_transmit_datagrams`].
+    pub fn max_transmit_datagrams(&self) -> std::num::NonZeroUsize {
+        self.config.max_transmit_datagrams
+    }
+
     /// Size of non-frame data for a 1-RTT packet
     ///
     /// Quantifies space consumed by the QUIC header and AEAD tag. All other bytes in a packet are

noq-proto/src/tests/mod.rs

@@ -2191,6 +2191,59 @@ fn tail_loss_respect_max_datagrams() {
     assert_eq!(client_stats.udp_tx.ios, client_stats.udp_tx.datagrams);
 }
 
+// Default max_transmit_segments / max_transmit_datagrams must remain backward
+// compatible. The historical compromise was 10 / 20.
+#[test]
+fn default_max_transmit_settings() {
+    let cfg = TransportConfig::default();
+    assert_eq!(
+        cfg.max_transmit_segments.get(),
+        10,
+        "default max_transmit_segments must remain 10 to preserve historical behavior",
+    );
+    assert_eq!(
+        cfg.max_transmit_datagrams.get(),
+        20,
+        "default max_transmit_datagrams must remain 20 to preserve historical behavior",
+    );
+}
+
+// max_transmit_segments setter caps the number of GSO segments emitted in a
+// single Transmit. With a cap of 4, no Transmit returned by poll_transmit may
+// carry more than 4 datagrams.
+#[test]
+fn max_transmit_segments_setter_caps_batch_size() {
+    use std::num::NonZeroUsize;
+    let _guard = subscribe();
+    let client_config = {
+        let mut c_config = client_config();
+        let mut t_config = TransportConfig::default();
+        t_config.max_transmit_segments(NonZeroUsize::new(4).expect("nonzero"));
+        c_config.transport_config(t_config.into());
+        c_config
+    };
+    let mut pair = Pair::default();
+    let (client_ch, _) = pair.connect_with(client_config);
+
+    // Send enough data to require GSO batching.
+    let s = pair.client_streams(client_ch).open(Dir::Uni).unwrap();
+    pair.client_send(client_ch, s)
+        .write(&[42u8; 64 * 1024])
+        .unwrap();
+    pair.drive();
+
+    let stats = pair.client_conn_mut(client_ch).stats();
+    assert!(
+        stats.udp_tx.ios > 0,
+        "expected at least one UDP TX I/O during the transfer",
+    );
+    let segments_per_io = stats.udp_tx.datagrams as f64 / stats.udp_tx.ios as f64;
+    assert!(
+        segments_per_io <= 4.0,
+        "max_transmit_segments(4) should cap GSO batch size, observed average = {segments_per_io}",
+    );
+}
+
 #[test]
 fn datagram_send_recv() {
     let _guard = subscribe();

noq/src/connection.rs

@@ -4,7 +4,6 @@ use std::{
     future::Future,
     io,
     net::{IpAddr, SocketAddr},
-    num::NonZeroUsize,
     pin::Pin,
     sync::{
         Arc, Weak,
@@ -1487,7 +1486,8 @@ impl State {
         let max_datagrams = self
             .sender
             .max_transmit_segments()
-            .min(MAX_TRANSMIT_SEGMENTS);
+            .min(self.inner.max_transmit_segments());
+        let max_transmit_datagrams = self.inner.max_transmit_datagrams().get();
 
         loop {
             // Retry the last transmit, or get a new one.
@@ -1525,7 +1525,7 @@ impl State {
                 Poll::Ready(Ok(())) => {}
             }
 
-            if transmits >= MAX_TRANSMIT_DATAGRAMS {
+            if transmits >= max_transmit_datagrams {
                 // TODO: What isn't ideal here yet is that if we don't poll all
                 // datagrams that could be sent we don't go into the `app_limited`
                 // state and CWND continues to grow until we get here the next time.
@@ -1875,16 +1875,3 @@ pub enum SendDatagramError {
     #[error("connection lost")]
     ConnectionLost(#[from] ConnectionError),
 }
-
-/// The maximum amount of datagrams which will be produced in a single `drive_transmit` call
-///
-/// This limits the amount of CPU resources consumed by datagram generation,
-/// and allows other tasks (like receiving ACKs) to run in between.
-const MAX_TRANSMIT_DATAGRAMS: usize = 20;
-
-/// The maximum amount of datagrams that are sent in a single transmit
-///
-/// This can be lower than the maximum platform capabilities, to avoid excessive
-/// memory allocations when calling `poll_transmit()`. Benchmarks have shown
-/// that numbers around 10 are a good compromise.
-const MAX_TRANSMIT_SEGMENTS: NonZeroUsize = NonZeroUsize::new(10).expect("known");