kcp_io/core/
config.rs

1//! KCP protocol configuration parameters and presets.
2//!
3//! This module defines [`KcpConfig`], which controls the behavior of the KCP
4//! protocol engine including nodelay mode, update interval, retransmission
5//! strategy, window sizes, MTU, and stream mode.
6
7/// KCP protocol configuration parameters.
8///
9/// Controls the behavior of the underlying KCP engine. Use the provided presets
10/// ([`default()`](KcpConfig::default), [`fast()`](KcpConfig::fast),
11/// [`normal()`](KcpConfig::normal)) or customize individual fields.
12///
13/// # Example
14///
15/// ```
16/// use kcp_io::core::KcpConfig;
17///
18/// // Use a preset
19/// let config = KcpConfig::fast();
20///
21/// // Customize from a preset
22/// let config = KcpConfig {
23///     mtu: 1200,
24///     snd_wnd: 256,
25///     rcv_wnd: 256,
26///     ..KcpConfig::fast()
27/// };
28/// ```
29#[derive(Debug, Clone)]
30pub struct KcpConfig {
31    /// Enable nodelay mode. When `true`, KCP disables the wait-to-send delay
32    /// and sends packets as soon as possible, reducing latency.
33    pub nodelay: bool,
34    /// Internal update interval in milliseconds. Lower values reduce latency
35    /// but increase CPU usage. Typical range: 10–100 ms.
36    pub interval: u32,
37    /// Fast retransmit trigger count. When an out-of-order ACK is received
38    /// this many times, KCP immediately retransmits the packet without waiting
39    /// for a timeout. Set to 0 to disable fast retransmit.
40    pub resend: i32,
41    /// Disable congestion control. When `true`, KCP ignores the congestion
42    /// window and sends at full speed (uses `nocwnd` mode). Useful for
43    /// low-latency scenarios where bandwidth is not a concern.
44    pub nc: bool,
45    /// Maximum Transmission Unit in bytes. This is the maximum size of a single
46    /// KCP output packet (including the 24-byte KCP header). Must account for
47    /// UDP header overhead (28 bytes for IPv4). Default: 1400.
48    pub mtu: u32,
49    /// Send window size (number of packets). Larger values allow higher
50    /// throughput but consume more memory. Default: 32.
51    pub snd_wnd: u32,
52    /// Receive window size (number of packets). Should generally be >= `snd_wnd`.
53    /// Larger values allow higher throughput. Default: 128.
54    pub rcv_wnd: u32,
55    /// Enable stream mode. When `true`, KCP operates like a byte stream (similar
56    /// to TCP), merging small packets and splitting large ones. When `false`
57    /// (default), KCP preserves message boundaries.
58    pub stream_mode: bool,
59}
60
61impl Default for KcpConfig {
62    /// Returns a conservative default configuration.
63    ///
64    /// - nodelay: `false`
65    /// - interval: `100` ms
66    /// - resend: `0` (no fast retransmit)
67    /// - nc: `false` (congestion control enabled)
68    /// - mtu: `1400`
69    /// - snd_wnd: `32`, rcv_wnd: `128`
70    /// - stream_mode: `false`
71    fn default() -> Self {
72        Self {
73            nodelay: false,
74            interval: 100,
75            resend: 0,
76            nc: false,
77            mtu: 1400,
78            snd_wnd: 32,
79            rcv_wnd: 128,
80            stream_mode: false,
81        }
82    }
83}
84
85impl KcpConfig {
86    /// Returns a low-latency (fast) configuration preset.
87    ///
88    /// Optimized for minimal latency at the cost of higher bandwidth usage.
89    ///
90    /// - nodelay: `true`
91    /// - interval: `10` ms
92    /// - resend: `2` (fast retransmit after 2 out-of-order ACKs)
93    /// - nc: `true` (congestion control disabled)
94    /// - mtu: `1400`
95    /// - snd_wnd: `128`, rcv_wnd: `128`
96    /// - stream_mode: `false`
97    pub fn fast() -> Self {
98        Self {
99            nodelay: true,
100            interval: 10,
101            resend: 2,
102            nc: true,
103            mtu: 1400,
104            snd_wnd: 128,
105            rcv_wnd: 128,
106            stream_mode: false,
107        }
108    }
109
110    /// Returns a balanced (normal) configuration preset.
111    ///
112    /// Balances latency and bandwidth usage. Good for most use cases.
113    ///
114    /// - nodelay: `true`
115    /// - interval: `40` ms
116    /// - resend: `2`
117    /// - nc: `false` (congestion control enabled)
118    /// - mtu: `1400`
119    /// - snd_wnd: `64`, rcv_wnd: `128`
120    /// - stream_mode: `false`
121    pub fn normal() -> Self {
122        Self {
123            nodelay: true,
124            interval: 40,
125            resend: 2,
126            nc: false,
127            mtu: 1400,
128            snd_wnd: 64,
129            rcv_wnd: 128,
130            stream_mode: false,
131        }
132    }
133}
kcp_io/core/config.rs

kcp_io/core/
config.rs
