OutboundQueue.hpp File Reference

Per-client outbound message queue with replace-on-stale semantics. More...

#include <SDL3/SDL_stdinc.h>
#include <SDL3_net/SDL_net.h>
#include <cstdint>
#include <deque>
#include <vector>

Include dependency graph for OutboundQueue.hpp:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
struct	OutboundEntry
	Bytes already framed (4-byte length prefix + payload) ready for the wire. More...
class	OutboundQueue
	Per-connection outbound message queue. More...

Detailed Description

Per-client outbound message queue with replace-on-stale semantics.

SDL3_net's NET_WriteToStreamSocket is already non-blocking and internally queues bytes that don't immediately go to the kernel — but that queue grows unbounded for slow clients, and once a snapshot is in it we lose all ability to supersede it with a fresher one. With 100 connected bots and the server producing ~20 KB of registry snapshot every tick, a slow drainer ends up with dozens of stale snapshots stacked behind the first one in flight. Each one bytes-equivalent of data the client still has to receive and decode before reaching the state we actually want them at.

This class sits one layer above the SDL_net send queue and bounds it:

• replace-on-stale: enqueueing a packet with a non-zero replaceKey removes any previously queued entry with the same key before pushing. Snapshots use replaceKey = PacketType::UPDATE_REGISTRY, so a slow client only ever has one snapshot pending — always the freshest.
• max-age culling: optional. Entries older than maxAgeMs are dropped on flush. Reliable-style messages (events) opt out by using replaceKey == 0, which marks them as "must ship".

Phase-3 staging: this is intentionally a small, single-threaded wrapper around a std::deque. Stage 3b moves the flush onto a dedicated network thread and makes the enqueue cross-thread via an SPSC ring; the public API here doesn't need to change.