Messaging and Lifecycle EN

English · 简体中文

Messaging and connection lifecycle

Message boundaries and format

send() sends one application message; recv() returns one complete message. Applications do not need TCP-style byte-stream framing. Outgoing data must currently be nonempty and begin with 0xfe. Receive APIs do not expose raw RakNet frames, reliability metadata or channel metadata.

For a custom protocol, an envelope such as 0xfe | type | request_id | payload is possible. Serialization, length checks and business fields remain the application's responsibility.

Common APIs

API	Purpose
RaknetListener::bind(&SocketAddr)	Create a listener
listener.listen().await	Start listening; finish builder configuration first
listener.accept().await?	Accept a session
RaknetSocket::connect(&SocketAddr)	Connect with the default RakNet version
connect_with_version(&SocketAddr, version)	Specify a RakNet version
send(&[u8], Reliability)	Send a borrowed payload
send_with_order_channel(..., u8)	Select an ordering/sequencing channel; default is 0
recv().await?	Receive a Vec<u8> message
send_bytes(Bytes, Reliability) / recv_bytes()	Use immutable shared buffers
flush().await?	Wait for the send queue to empty and reliable frames to be acknowledged
close().await?	Close the connection
mtu() / raknet_version()	Inspect negotiated settings

Successful send() means the sending path accepted and processed the message. It does not mean the remote business operation has executed. flush() only concerns transport confirmation. Design an application response for persistence or operation success; the quick-start echo is one such response.

Sustained sends and backpressure

When the send queue fills, sending asynchronously waits for capacity. At most 64 reliable frames are in flight, including fragments. Ordinary bursts have a 256 KiB queue high-water mark, including frame overhead.

Keep receiving while sending continuously. Avoid two endpoints that only send and stop reading. Do not spawn an unbounded task per message: a bounded library queue does not bound pending work in your application. Use bounded application queues, concurrency limits and timeouts. Cancellation cannot retract messages already queued or transmitted.

Large messages and receive limits

Resource	Current limit
Large outgoing ReliableOrdered message	65,536 fragments; 64 MiB budget including 128 B per-frame overhead
Reliable receive reordering	65,536 reliable indices
Ordered message buffering	64 MiB of data
Fragment reassembly	1,024 groups, 65,536 fragments per group; total 64 MiB budget including overhead
Stalled fragment group	Connection closes after 60 s without progress

A large message may enter an empty send queue, but it still obeys the total budget. 64 MiB is neither an exact application payload limit nor a total process memory limit. Application data, runtime state and reassembly consume additional memory. Invalid or excessive receive state closes the connection instead of silently discarding already acknowledged data.

Large messages share the flight window and can block later messages on their channel. For file transfer, application chunks and separate queues can give real-time messages processing opportunities.

Shutdown

Call close() when finished and handle its result. Dropping the connection object also triggers a close notification. If the application needs transport confirmation first, call flush(). Keep business-level timeouts for network outages and peer exits.

Socket API source · Batch APIs

For binary layouts, index semantics, fragmentation limits and retry algorithms, see the RakNet protocol reference.

Blocking API · API index · Errors and deadlines