Describe the meaning of `error_code` in `io_result`

[akrzemi1]

task<> coro(any_stream& s)
{
  auto [ec, n] = co_await s.read_some(buf); // may throw
  // ...
}

Calling and co_awaiting on a stream operation may:

• either throw, for instance upon allocator failure (not necessarily OOM: wg21.link/P1404),
• or return a non-zero error_code, for instance upon expected EOF.

The exception path is clear: the programmer is not expecting this: their code is not prepared, so it has to be skipped: stack unwinding.
The non-zero error_code is tricky. Does it represent an error? What does _error_even mean?

The only practical or relevant meaning is "what does the function guarantee?"or in other words "what is the postcondition?" Whatever is guaranteed, the caller may take it for granted and is relieved of thinking about what happens if the guarantee is not fulfilled.

So, the question for co_await s.read_some(buf) is: do you guarantee that the buffer will be filled, or do I need to be prepared for the situation where it is not? The answer is probably "no guarantee, be prepared!" But if so, then:

1. The library should document it clearly.
2. It should consistently stick to this view: a non-zero error_code is a success, irregular but success, that is, no precondition failure. In that case when_all/when_any should also recognize a non-zero error_code as success: the caller of the algorithm will determine what to do with the irregular successes.

When doing (for whatever reason):

co_await when_any(
  stream1.read_some(buf1),
  stream2.read_some(buf2),
);  

You should get the first that returns even with a non-zero ec; even if the other one would have returned with a zero ec. Because this is the contract of stream1.read_some(buf1): getting a non-zero ec is success.

[akrzemi1]

See also wg21.link/p4007r0, section 3.

[vinniefalco]

I thought this explained it?
https://develop.capy.cpp.al/capy/8.design/8c.ReadStream.html

[akrzemi1]

That definition is backwards. The point of the specification (one of) is to define what is considered "success". Whereas here phrase "on success" looks like the user is assumed to know what success is already.

In the world that makes sense to me, where all "irregular" I/O situations are considered (complicated) success, the specification would be:

Attempts to read up to buffer_size(buffers) bytes from the stream.

Returns:

• When buffer_size(buffers) == 0: [{}, 0], otherwise
• Upon any irregular I/O situation: [ec, 0], where ec != 0 , otherwise
• [{}, n], where n represents the number of read bytes and 0 < n && n <= buffer_size(buffers).

"Irregular I/O situations" should be listed in one place, eof being one of them.

[akrzemi1]

Interestingly, the specification in https://develop.capy.cpp.al/capy/8.design/8c.ReadStream.html means that either ec or n in [ec, n] is zero. Is that so?