Re: [boost] [system] remarks and feedback

From: Christopher Kohlhoff (chris_at_[hidden])
Date: 2006-06-28 10:00:24

I'm thinking it might be helpful in the discussion for me to try
to document in precise terms what asio would need from
error_code and how it would be used.

What's needed from error_code
=============================

Testing for equality:

  Given
    error_code ec1(value1, category1);
    error_code ec2(value1, category1);
    error_code ec3(value2, category1);
  Then
    ec1 == ec2 evaluates to true
    ec1 == ec3 evaluates to false

What asio will say
================== 

(For the sake of brevity I will only discuss a couple of error
codes, but others will follow the same pattern.)

There will be an error_code object:

  namespace boost { namespace asio { namespace error {
    extern error_code connection_reset;
  }}}

On non-POSIX implementations, the initialisation of
connection_reset is implementation-defined.

On POSIX implementations, the initialisation of connection_reset
shall be:

  error_code connection_reset(ECONNRESET, from_errno);

such that both of the following expressions shall evaluate to
true:

  connection_reset == error_code(ECONNRESET, from_errno)
  connection_reset.errno_value() == ECONNRESET

In the following code, sock is a variable with the type
boost::asio::ip::tcp::socket.

  char buf[128];
  error_code ec;
  sock.receive(boost::asio::buffer(buf), ec);

If an error occurs during the socket receive() such that the
connection was reset by the peer (and this condition is reported
to asio by a unique system error code), the following expression
shall evaluate to true on all implementations (POSIX and
non-POSIX):

  ec == boost::asio::error::connection_reset

Furthermore, on POSIX implementations the following expressions
shall evaluate to true:

  ec == error_code(ECONNRESET, from_errno)
  ec.errno_value() == ECONNRESET

There will be an error_code object:

  namespace boost { namespace asio { namespace error {
    extern error_code name_not_found;
  }}}

On non-POSIX implementations, the initialisation of
name_not_found is implementation-defined.

On POSIX implementations, the initialisation of name_not_found
shall be:

  ??? // Needs error category support. From
      // the getaddrinfo error EAI_NONAME.

In the following code, resolver is a variable with the type
boost::asio::ip::tcp::resolver.

  boost::asio::ip::tcp::resolver::query query("foo", "bar");
  error_code ec;
  resolver.resolve(query, ec);

If an error occurs during name resolution such that the host is
not found, the following expression shall evaluate to true on
all implementations (POSIX and non-POSIX):

  ec == boost::asio::error::name_not_found

Furthermore, on POSIX implementations the following expressions
shall evaluate to true:

  ??? // Again, needs error category support.

That's all I can think of for now.

Cheers,
Chris