recvmsg

Traits for receiving datagrams reliably, without truncation.

Problem

Unlike a byte stream interface, datagram sockets (most notably UDP) and other packet-based APIs preserve boundaries between different write calls, which is what "message boundary" essentially means. Extracting messages by partial reads is an error-prone task, which is why no such interface is exposed by any OS – instead, all messages received from message IPC channels are full messages rather than chunks of messages, which simplifies things to a great degree and is arguably the only proper way of implementing datagram support.

There is one pecularity related to this design: you can't just use a buffer with arbitrary length to successfully receive a message. With byte streams, that always works – there either is some data which can be written into that buffer or end of file has been reached, aside from the implied error case which is always a possibility for any kind of I/O. With datagrams, however, there might not always be enough space in a buffer to fetch a whole message. If the buffer is too small to fetch part of a message, it is truncated and the message ends up essentially malformed.

Solution

The RecvMsg trait (together with its async counterpart, AsyncRecvMsg) provides an interface that completely prevents truncation.

With the help of MsgBuf, a borrowed buffer can be provided, which can also be subsequently transitioned into an owned buffer as needed. Alternatively, MsgBuf can start off with an already-owned buffer. The inner Vec will then be resized as necessary, with an optional quota preventing a connection from exhausting all memory.

Implementation

There are three features a standard truncating message reception can provide to allow programs to solve the truncation problem: peeking, truncation reporting and exact length querying. The former two are represented by the TruncatingRecvMsg trait, while the last one can be seen as an extension of those and is thus available as TruncatingRecvMsgWithFullSize. Both of those have async counterparts.

RecvMsg or AsyncRecvMsg are then to be implemented in terms of either of those traits using the appropriate helper function from the corresponding module.

Feature flags

• std – std::error::Error on QuotaExceeded. Precludes #![no_std].
• std_net – implementations of traits on types from std::net and std::os::unix::net (Unix domain sockets) on Unix.