Configuration Reference

English · 简体中文

配置参数完整参考

对应 1.4.0，逐项列出公开调优参数、默认值、单位、校验及作用范围。应用运行时和benchmark命令行选项不是库参数。监听器构建选项在listen前设置，socket策略在connect/accept后应用；这些策略不与对端协商。

参数／接口	默认值／允许范围	详细作用及性能影响
bind address	explicit SocketAddr	指定IPv4/IPv6和UDP端口；0让系统分配端口，使用local_addr()读取。通配监听影响可达范围，不提供身份认证。
connect_with_version(..., raknet_version)	default 10; listener accepts 10/11	RakNet离线握手版本，不是业务或游戏版本；监听器支持10/11，不匹配可能拒绝握手。
requested_mtu / maximum_mtu	default 1400 B; 61–1492 B	名义MTU，协商取较小值；预留28 B IPv4/UDP头部，不是路径MTU发现。大值可减少开销但可能导致路径分片/丢包，小值增加帧开销；用socket.mtu()读取协商值。
bind_with_receive_buffer_size(..., size)	NonZeroUsize, ≤ i32::MAX B	每socket接收缓冲请求，系统可能限制实际值，设置失败返回SocketError。bind()尽力请求2 MiB，from_std()保留原设置；大缓冲可吸收突发，但不能解决应用停止读取。
bind_with_socket_shards(..., count)	Linux; NonZeroUsize 1–64; default 1	Linux固定SO_REUSEPORT接收组，1走普通bind。共享GUID、MOTD和accept队列；不会把单对端分散到所有分片，应结合运行时线程和流量分布选择。
with_accept_backlog(backlog)	NonZeroUsize; default 128	必须listen前设置，否则panic。限制等待accept的连接，不是活跃连接总数；满时离线握手等待重试，大队列会保留更多待接收会话。
with_idle_maintenance(enabled) / set_idle_maintenance(enabled)	false	监听器选项作用于新accept连接，socket setter只改该连接。安静500 ms且队列空时暂停周期维护，新工作唤醒；可减少空闲CPU但改变调度。监听器选项必须listen前设置。
with_receive_batching(enabled)	Linux; false	Linux，listen前设置，所有分片每次最多接收16个已就绪数据报，不等待凑满；分别评估繁忙吞吐和稀疏延迟。
SendOptions::with_in_flight_limits(frames, bytes)	64 frames / 64 MiB; frames 1–4096; bytes 2048 B–64 MiB	两项共同限制未确认可靠在途数据；分片和合包成员分别计帧，字节含编码帧开销。小窗口可能限制高RTT吞吐，大窗口可能增加瓶颈排队。
SendOptions::with_queue_budgets(reliable, unreliable)	256 KiB / 64 KiB; each ≥2048 B; sum ≤64 MiB	可靠软预算包含在途数据；单次较大可靠发送/批量可超软预算，但须保留不可靠预留。不可靠有独立待发预算。计费字节不是RSS，也不是带宽比例保证。
SendOptions::with_flush_budget(bytes)	256 KiB; 2048 B–64 MiB	每次调度flush的编码帧字节预算，必须容纳连接MTU，不兼容配置应用时失败。小预算可能把工作延后至下次send、ACK或维护；没有等待凑包的定时器。
set_send_options(options)	unconfigured until called; feature send-policy	需send-policy，connect/accept后应用。构建器校验范围，setter检查MTU；降低限制保留已有队列/在途数据。Default预设会启用策略，不等于关闭；没有恢复未配置状态的接口。getter可读取全部设置。
RecoveryOptions::deadline_driven	false; feature recovery-policy	按最早重传期限唤醒；设置探测会隐含启用，即使请求字段为false。不降低RTO估算。
RecoveryOptions::tail_probe_min_delay	None; Option	重放一个符合条件的完整尾部数据报。等待至少max(1 ms,配置下限,ceil(1.5×SRTT))，毫秒精度；需要启用后的有效RTT、无待发数据、无重传历史。回退和性能取舍见恢复指南。
RecoveryOptions::reset_backoff_on_progress	false; feature recovery-policy	新的明确RTT反馈将已有重试计数限制为最多1；重传ACK不符合条件，不取消Karn采样排除。
set_recovery_options(options)	all off by default	connect/accept后应用，getter返回请求设置。Default关闭运行时选项，但编译后的计时修正仍在；已发探测保留回退期限。
send(..., reliability)	explicit; five modes	逐消息选择五种交付语义；载荷以0xfe开头。只有ReliableOrdered自动分片大消息，其他模式必须容纳于MTU。
send_*_with_order_channel(..., order_channel)	default 0; u8 0–255	默认0，库接口接受u8范围0–255，对端可能更窄；独立有序/顺序过滤流，无序模式不在线上编码通道。减少跨流等待，不隔离网络拥塞。
send_batch / send_bytes_batch messages	ready input; no collection timer	传入已就绪消息，不等待凑包。小ReliableOrdered消息可在MTU内最多8帧合包，其他模式单独发送；真实丢包反馈/超时关闭该连接后续合包，普通send不等待批量。
recv_batch / recv_bytes_batch limit	0 returns immediately; work capped at 64	0立即返回；先等首条，再排空已就绪消息至min(limit,64)，先清空output；不等待凑满。大值增加单次连续业务处理量。
set_full_motd(motd)	default generated MCPE-format string	离线pong广告内容，监听分片共享；须满足离线响应编码约束，不改变握手版本或接纳策略。
set_motd(name, max_connection, protocol, version, game_type, port)	explicit advertised fields	生成MCPE格式MOTD；max_connection仅广告显示，不执行活跃连接限额。protocol/version是业务元数据，不是RakNet握手版本。
set_loss_rate(stage)	disabled initially; stage 0–10, larger values clamp to 10	初始关闭，测试用本端发送随机丢包，以10%为步长，0不丢、10全丢，更大值按10处理；不是广域网仿真或拥塞控制，只在隔离测试环境使用。
enable_raknet_log(flag)	0; bit mask 1 debug / 2 errors / 4 info	进程级日志开关：1调试、2错误、4信息，可组合，如6输出错误和信息；调试格式化/输出可能影响吞吐与延迟。

编译功能和外部控制

• send-policy提供SendOptions及setter/getter；仅编译不自动配置全部连接，调用setter才应用策略。
• recovery-policy提供RecoveryOptions及setter/getter。选项默认关闭，但编译后即包含时间戳修正；需要同时启用时设置 features = ["send-policy", "recovery-policy"]。
• Tokio线程数由应用运行时的Builder::worker_threads或应用环境设置，不是库字段；更多线程可能增加争用，需和socket分片共同评估。
• 业务队列、活跃连接接纳、业务超时由应用管理。取消send后，已入队可靠消息仍可能继续交付；取消flush不等于关闭连接。

固定实现限制不是运行时参数

基础RTO 50–12,000 ms、周期维护50 ms、接收不活跃超时60 s以及消息/帧计费、重组限制等都是内部约束，没有公开setter。应用改变公开utils常量不会重新配置已编译库。协议参考和消息限制详细说明；发送/恢复选项及MOTD人数都不能替代这些限制。低层RaknetSocket::from接受已协商MTU/版本和分发通道，常规使用connect/accept，不绕过握手。

恢复策略 · 发送策略 · 配置示例

blocking 运行时与操作超时

参数／API	默认／值域	范围与性能影响
RaknetRuntime::with_worker_threads(workers)	NonZeroUsize；new() 为 1 worker	共享 Tokio runtime；更多 worker 可能增加连接并行度，也可能增加调度与竞争。clone runtime，不要每条消息创建 runtime。
同步 *_timeout(..., duration)	显式 Duration；无 timeout 方法没有调用者截止时间	此次等待的期限，不是 RTO、拥塞控制或回滚；零可能立即超时，已经入队的消息可能继续交付。
异步 tokio::time::timeout(duration, future)	应用指定	外层 Elapsed 错误，不修改传输重试定时器。

blocking 只公开同步适配器，不自动开启发送/恢复策略、消息合并或 Linux 收包优化。监听器配置仍须遵守 Linux 限制及 listen 前设置要求。运行时创建和阻塞等待禁止嵌套 Tokio 上下文。

同步指南 · 功能组合 · 超时语义