Docs on what result of .receive_packet means

[deontologician]

Returns a Result<Option<P>, Error>, but the docs are a bit terse

https://docs.rs/protocol/3.1.4/protocol/wire/stream/struct.Connection.html#method.receive_packet

Attempts to receive a packet

• Is this a non-blocking call?
• What does Ok(None) mean here? Is it an error? If this is non-blocking, does it mean try again later?

[garlic-hub]

Alright I had to figure this out from source code.

The library internally uses the std::io::Read trait which provides no guarantees on whether the read will block or not. It depends on what you provide the constructor so you can make it blocking or non-blocking.

The return values took a bit to understand how it all works. Ok(None) can mean different things. If the internal call to read() provides only part of a parcel the method will return Ok(None) because it doesn't have enough data to fully construct the parcel yet. This means you need to call Ok(None) at least twice. This is further exasperated by the fact that the send_packet() method calls write twice, once for a size header and again for the parcel itself. This is annoying because write not buffered for TcpStream. That can manifest in the receive_packet reading the header data only, returning Ok(None) because it needs more data, then when you call receive_packet again it will be able to read the rest of the parcel and actually construct something to return an Ok(Some()). The library does not use EOF as a sign to return Err though because it pushes parcels into a queue to serve you as you call receive_packet. This happens when it gets multiple parcels worth of data with one call to read(). So in effect if you get multiple Ok(None) in a row that means either connection is EOF or you just need to keep waiting for data depending on blocking or not.