A connected pair of in-memory ReliableSocket endpoints that forward datagrams to each other.
Writes committed on first() are delivered as reads on second(), and writes committed on second() are delivered as reads on first(). Datagrams are forwarded without copying by transferring ownership of the underlying Buf from the writer's reservation to the reader's queue.
The underlying socket endpoints are reference-counted and allocated from the provided Allocator. Copies of the ReliableSocket handles returned by first() and second() may outlive the ForwardingSocketPair object itself; the shared state is automatically destroyed and deallocated once all handles and futures for both endpoints have been released.
Closing one socket (or dropping all handles to it) prevents further writes in both directions. Datagrams that were already committed before the socket closed can still be read by the peer, after which the peer socket also closes. Calling Close() on the ForwardingSocketPair closes both endpoints immediately and discards any unread datagrams.
Memory and locking
Each write reservation allocates its buffer from the pair's allocator. The buffer is freed when the reader releases the received ConstBuf, or when the reservation is canceled or fails to commit. Both sockets in a pair share one pw::sync::InterruptSpinLock, and the allocator is called while that lock is held, so it must not block (for example, it must not be guarded by a pw::sync::Mutex).
If the allocator cannot provide a write buffer, TryReserveWrite returns std::nullopt and ReserveWrite remains pending. Pending reservations are only retried when write capacity is released (the peer reads a datagram, or a reservation is canceled or fails to commit), not when unrelated memory is freed. Size the allocator to hold queue_depth maximum-size datagrams in each direction to avoid stalls.