Behavior of SocketImpl::receiveBytes in case of timeout

[nlw0]

I'm trying to understand the exact behavior intended for this function:

poco/Net/include/Poco/Net/SocketImpl.h

Lines 224 to 231 in 3f76ad6

	virtual int receiveBytes(Poco::Buffer<char>& buffer, int flags = 0, const Poco::Timespan& timeout = 100000);
	/// Receives data from the socket and stores it in the buffer.
	/// If needed, the buffer will be resized to accomodate the
	/// data. Note that this function may impose additional
	/// performance penalties due to the check for the available
	/// amount of data.
	///
	/// Returns the number of bytes received.

Does it simply return 0 in case of a timeout? Is it intended as a polling function?

Similar functions throw a TimeoutException in case of timeout, and this limit would be set by setReceiveTimeout. This method here takes a separate timeout parameter, though, with a default value, and it might seem at first that it would supersede the socket timeout attribute, but it's not exactly that. First of all, there's still a timeout test happening inside the function body. But like I mentioned before, the behavior seems to be returning 0 in case the parameter-passed timeout is reached.

Is this by design, should I make a patch to update the documentation?

And in this case, how would I obtain the behavior of receiving a TimeoutException if I'm using a Poco::Buffer<char>& instead of a SocketBufVec& or a void * buffer, int length to store the output? This seems like an inconsistent behavior depending only on the choice of the output data structure.

[matejk]

Good observation! Let me explain the behavior:

How receiveBytes(Buffer<char>&, int, Timespan) works:

int SocketImpl::receiveBytes(Poco::Buffer<char>& buffer, int flags, const Poco::Timespan& timeout)
{
    int rc = 0;
    if (poll(timeout, SELECT_READ))  // 1. First polls with provided timeout
    {
        // 2. Only enters here if data is available
        int avail = available();
        if (buffer.size() < avail) buffer.resize(avail);
        rc = ::recv(_sockfd, buffer.begin(), buffer.size(), flags);
        // ... error handling, may throw TimeoutException from recv()
    }
    return rc;  // Returns 0 if poll() timed out
}

Two-level timeout behavior:

1. Parameter timeout (Timespan timeout = 100000): Controls the poll() call. If no data is available within this time, returns 0 (no exception).
2. Socket receive timeout (setReceiveTimeout()): Controls the ::recv() call itself. If ::recv() times out (which can happen in edge cases), throws TimeoutException.

Comparison with other overloads:

Overload	Timeout Source	Timeout Behavior
receiveBytes(void*, int, int)	Socket receive timeout	Throws TimeoutException
receiveBytes(Buffer<char>&, int, Timespan)	Parameter + socket	Returns 0 on poll timeout, throws on recv timeout
receiveBytes(SocketBufVec&, int)	Socket receive timeout	Throws TimeoutException

Is this by design?

Yes, this appears intentional. The Buffer<char>& overload is designed for polling-style usage where you want to check if data is available without blocking indefinitely. The function:

1. Auto-resizes the buffer based on available() bytes
2. Returns 0 if no data arrives within the timeout (non-exceptional case)

How to get TimeoutException behavior with Buffer<char>&?

Option 1: Use a very large timeout and rely on socket timeout:

socket.setReceiveTimeout(Poco::Timespan(5, 0));  // 5 seconds
int n = socket.receiveBytes(buffer, 0, Poco::Timespan(60, 0));  // 60s poll
// Socket timeout will fire first and throw TimeoutException

Option 2: Check return value and throw manually:

int n = socket.receiveBytes(buffer, 0, Poco::Timespan(5, 0));
if (n == 0 && /* expected data */) {
    throw Poco::TimeoutException();
}

Option 3: Use the void* overload:

char buf[4096];
int n = socket.receiveBytes(buf, sizeof(buf));  // Throws on timeout
buffer.assign(buf, n);

Documentation improvement?

Yes, the documentation could be clearer. A PR to improve the docstring would be welcome:

/// Receives data from the socket and stores it in the buffer.
/// Uses poll() to wait for data availability up to the specified timeout.
/// Returns 0 if no data is available within the timeout (does not throw).
/// May throw TimeoutException if the socket's receive timeout expires during recv().
/// ...