Blocking API

English · 简体中文

同步 blocking API

从 1.3.0 起提供，复用异步协议实现，没有另一套 RakNet 协议栈。

客户端

[dependencies]
rust-raknet = { version = "1.4.0", features = ["blocking"] }

use rust_raknet::{blocking::RaknetRuntime, Reliability};
use std::time::Duration;

fn main() -> rust_raknet::blocking::Result<()> {
    let runtime = RaknetRuntime::new()?;
    let address = "127.0.0.1:19132".parse().unwrap();
    let socket = runtime.connect_timeout(&address, Duration::from_secs(10))?;
    socket.send_timeout(&[0xfe, 1, 2, 3], Reliability::ReliableOrdered,
                        Duration::from_secs(2))?;
    let reply = socket.recv_timeout(Duration::from_secs(2))?;
    println!("Echo: {reply:?}");
    socket.flush_timeout(Duration::from_secs(2))?;
    socket.close()
}

连接到异步回显服务端。两端应处于同一隔离网络，消息仍须包含 0xfe 前缀。

服务端与运行时

use rust_raknet::{blocking::RaknetRuntime, Reliability};
fn main() -> rust_raknet::blocking::Result<()> {
    let runtime = RaknetRuntime::new()?;
    let address = "127.0.0.1:19132".parse().unwrap();
    let mut listener = runtime.bind(&address)?;
    listener.listen()?;
    let socket = listener.accept()?;
    let message = socket.recv()?;
    socket.send(&message, Reliability::ReliableOrdered)?;
    socket.flush()?;
    socket.close()?;
    listener.close()
}

示例只处理一条连接。多连接服务应持续 accept，把会话交给数量受限的工作线程；不要在 accept 循环里等待慢连接。

• RaknetRuntime::new() 启动一个网络 worker；with_worker_threads(NonZeroUsize) 指定数量。
• clone runtime 共享线程，socket 保持其存活；没有全局运行时，也不会每次 send 创建运行时。应用调用间隙，网络 worker 仍持续收包、确认和重传。
• 在 Tokio 运行时内部创建 runtime 或进行阻塞操作会返回 Error::AsyncContext；此时直接使用异步 API。必要时可以在数量受限的 spawn_blocking 工作中创建和使用同步接口。
• 接收共享一个串行消费者，并发 recv 是争抢消息，不是广播。有顺序依赖的并发发送应由应用在同一通道上串行化。
• 阻塞接收会暂停调用线程。游戏引擎可用独立网络线程和有界消息队列桥接；库没有 Sans-I/O、try_recv 或 Bevy 插件。

超时与清理

connect、ping、accept、借用/拥有所有权发送、借用批量发送、借用/拥有所有权接收、借用批量接收以及 flush 提供超时方法。并非每个通道和批量方法都有 timeout 变体，完整列表见 API 索引。

超时只取消等待，不撤回已接纳的消息。批量调用可能已经发出前缀，盲目重试会重复业务消息。flush 等待传输 ACK，不是业务处理完成。优雅退出时先停生产者，限时 flush，再 close；最后一个 runtime owner 被丢弃时停止后台任务，不保证优雅交付。

可以同时启用 blocking、send-policy 和 recovery-policy。同步策略 setter/getter 返回 blocking::Result；send_options() 返回 Result<Option<SendOptions>>。

API 文档 · 独立 blocking benchmark