Thinking Asynchronously in C++

System error support in C++0x - part 5

2010-04-14T13:30:00.004+10:00

Creating your own error conditions

User-extensibility in the <system_error> facility is not limited to error codes: error_condition permits the same customisation.

Why create custom error conditions?

To answer this question, let's revisit the distinction between error_code and error_condition:

class error_code - represents a specific error value returned by an operation (such as a system call).
class error_condition - something that you want to test for and, potentially, react to in your code.

This suggests some use cases for custom error conditions:

Abstraction of OS-specific errors.
Let's say you're writing a portable wrapper around getaddrinfo(). Two interesting error conditions are the tentative "the name does not resolve at this time, try again later", and the authoritative "the name does not resolve". The getaddrinfo() function reports these errors as follows:
- On POSIX platforms, the errors are EAI_AGAIN and EAI_NONAME, respectively. The error values are in a distinct "namespace" to errno values. This means you will have to implement a new error_category to capture the errors.
- On Windows, the errors are WSAEAI_AGAIN and WSAEAI_NONAME. Although the names are similar to the POSIX errors, they share the GetLastError "namespace". Consequently, you may want to reuse std::system_category() to capture and represent getaddrinfo() errors on this platform.
To avoid discarding information, you want to preserve the original OS-specific error code while providing two error conditions (called name_not_found_try_again and name_not_found, say) that API users can test against.
Giving context-specific meaning to generic error codes.
Most POSIX system calls use errno to report errors. Rather than define new errors for each function, the same errors are reused and you may have to look at the corresponding man page to determine the meaning. If you implement your own abstractions on top of these system calls, this context is lost to the user.
For example, say you want to implement a simple database where each entry is stored in a separate flat file. When you try to read an entry, the database calls open() to access the file. This function sets errno to ENOENT if the file does not exist.
As the database's storage mechanism is abstracted from the user, it could be surprising to ask them to test for no_such_file_or_directory. Instead, you can create your own context-specific error condition, no_such_entry, which is equivalent to ENOENT.
Testing for a set of related errors.
As your codebase grows, you might find the same set of errors are checked again and again. Perhaps you need to respond to low system resources:
- not_enough_memory
- resource_unavailable_try_again
- too_many_files_open
- too_many_files_open_in_system
- ...
in several places, but the subsequent action differs at each point of use. This shows that there is a more general condition, "the system resources are low", that you want to test for and react to in your code.
A custom error condition, low_system_resources, can be defined so that its equivalence is based on a combination of other error conditions. This allows you to write each test as:
```
if (ec == low_system_resources)
  ...
```
and so eliminate the repetition of individual tests.

The definition of custom error conditions is similar to the method for error_codes, as you will see in the steps below.

Step 1: define the error values

You need to create an enum for the error values, similar to std::errc:

enum class api_error
{
  low_system_resources = 1,
  ...
  name_not_found,
  ...
  no_such_entry
};

The actual values you use are not important, but you must ensure that they are distinct and non-zero.

Step 2: define an `error_category` class

An error_condition object consists of both an error value and a category. To create a new category, you must derive a class from error_category:

class api_category_impl
  : public std::error_category
{
public:
  virtual const char* name() const;
  virtual std::string message(int ev) const;
  virtual bool equivalent(
      const std::error_code& code,
      int condition) const;
};

Step 3: give the category a human-readable name

The error_category::name() virtual function must return a string identifying the category:

const char* api_category_impl::name() const
{
  return "api";
}

Step 4: convert error conditions to strings

The error_category::message() function converts an error value into a string that describes the error:

std::string api_category_impl::message(int ev) const
{
  switch (ev)
  {
  case api_error::low_system_resources:
    return "Low system resources";
  ...
  }
}

However, depending on your use case, it may be unlikely that you'll ever call error_condition::message(). In that case, you can take a shortcut and simply write:

std::string api_category_impl::message(int ev) const
{
  return "api error";
}

Step 5: implement error equivalence

The error_category::equivalent() virtual function is used to define equivalence between error codes and conditions. In fact, there are two overloads of the error_category::equivalent() function. The first:

virtual bool equivalent(int code,
    const error_condition& condition) const;

is used to establish equivalence between error_codes in the current category with arbitrary error_conditions. The second overload:

virtual bool equivalent(
    const error_code& code,
    int condition) const;

defines equivalence between error_conditions in the current category with error_codes from any category. Since you are creating custom error conditions, it is the second overload that you must override.

Defining equivalence is simple: return true if you want an error_code to be equivalent to your condition, otherwise return false.

If your intent is to abstract OS-specific errors, you might implement error_category::equivalent() like this:

bool api_category_impl::equivalent(
    const std::error_code& code,
    int condition) const
{
  switch (condition)
  {
  ...
  case api_error::name_not_found:
#if defined(_WIN32)
    return code == std::error_code(
        WSAEAI_NONAME, system_category());
#else
    return code = std::error_code(
        EAI_NONAME, getaddrinfo_category());
#endif
  ...
  default:
    return false;
  }
}

(Obviously getaddrinfo_category() needs to be defined somewhere too.)

The tests can be as complex as you like, and can even reuse other error_condition constants. You may want to do this if you're creating a context-specific error condition, or testing for a set of related errors:

bool api_category_impl::equivalent(
    const std::error_code& code,
    int condition) const
{
  switch (condition)
  {
  case api_error::low_system_resources:
    return code == std::errc::not_enough_memory
      || code == std::errc::resource_unavailable_try_again
      || code == std::errc::too_many_files_open
      || code == std::errc::too_many_files_open_in_system;
  ...
  case api_error::no_such_entry:
    return code == std::errc::no_such_file_or_directory;
  default:
    return false;
  }
}

Step 6: uniquely identify the category

You should provide a function to return a reference to a category object:

const std::error_category& api_category();

such that it always returns a reference to the same object. As with custom error codes, you can use a global:

api_category_impl api_category_instance;

const std::error_category& api_category()
{
  return api_category_instance;
}

or you can make use of C++0x's thread-safe static variables:

const std::error_category& api_category()
{
  static api_category_impl instance;
  return instance;
}

Step 7: construct an `error_condition` from the `enum`

The <system_error> implementation requires a function called make_error_condition() to associate an error value with a category:

std::error_condition make_error_condition(api_error e)
{
  return std::error_condition(
      static_cast<int>(e),
      api_category());
}

For completeness, you should also provide the equivalent function for construction of an error_code. I'll leave that as an exercise for the reader.

Step 8: register for implicit conversion to `error_condition`

Finally, for the api_error enumerators to be usable as error_condition constants, enable the conversion constructor using the is_error_condition_enum type trait:

namespace std
{
  template <>
  struct is_error_condition_enum<api_error>
    : public true_type {};
}

Using the error conditions

The api_error enumerators can now be used as error_condition constants, just as you may use those defined in std::errc:

std::error_code ec;
load_resource("http://some/url", ec);
if (ec == api_error::low_system_resources)
  ...

As I've said several times before, the original error code is retained and no information is lost. It doesn't matter whether that error code came from the operating system or from an HTTP library with its own error category. Your custom error conditions can work equally well with either.

Next, in what will probably be the final instalment, I'll discuss how to design APIs that use the <system_error> facility.

System error support in C++0x - part 4

2010-04-12T17:18:00.002+10:00

[ part 1, part 2, part 3 ]

Creating your own error codes

As I stated in part 1, one of the principles behind the <system_error> facility is user-extensibility. This means that you can use the mechanism just described to define your own error codes.

In this section, I'll outline what you need to do. As a basis for a worked example, I will assume you're writing an HTTP library and need errors that correspond to the HTTP response codes.

Step 1: define the error values

You first need to define the set of error values. If you're using C++0x, you can use an enum class, similar to std::errc:

enum class http_error
{
  continue_request = 100,
  switching_protocols = 101,
  ok = 200,
  ...
  gateway_timeout = 504,
  version_not_supported = 505
};

The errors are assigned values according to the HTTP response codes. The importance of this will become obvious when it comes to using the error codes. Whatever values you choose, errors should have non-zero values. As you may recall, the <system_error> facility uses a convention where zero means success.

You can use regular (that is, C++03-compatible) enums by dropping the class keyword:

enum http_error
{
  ...
};

Note: C++0x's enum class differs from enum in that the former encloses enumerator names in the class scope. To access an enumerator you must prefix the class name, as in http_error::ok. You can approximate this behaviour by wrapping the plain enum in a namespace:

namespace http_error
{
  enum http_error_t
  {
    ...
  };
}

For the remainder of this example I will assume the use of enum class. Applying the namespace-wrapping approach is left as an exercise for the reader.

Step 2: define an `error_category` class

An error_code object consists of both an error value and a category. The error category determines whether a value of 100 means http_error::continue_request, std::errc::network_down (ENETDOWN on Linux), or something else entirely.

To create a new category, you must derive a class from error_category:

class http_category_impl
  : public std::error_category
{
public:
  virtual const char* name() const;
  virtual std::string message(int ev) const;
};

For the moment, this class will implement only error_category's pure virtual functions.

Step 3: give the category a human-readable name

The error_category::name() virtual function must return a string identifying the category:

const char* http_category_impl::name() const
{
  return "http";
}

This name does not need to be universally unique, as it is really only used when writing an error code to a std::ostream. However, it would certainly be desirable to make it unique within a given program.

Step 4: convert error codes to strings

The error_category::message() function converts an error value into a string that describes the error:

std::string http_category_impl::message(int ev) const
{
  switch (ev)
  {
  case http_error::continue_request:
    return "Continue";
  case http_error::switching_protocols:
    return "Switching protocols";
  case http_error::ok:
    return "OK";
  ...
  case http_error::gateway_timeout:
    return "Gateway time-out";
  case http_error::version_not_supported:
    return "HTTP version not supported";
  default:
    return "Unknown HTTP error";
  }
}

When you call the error_code::message() member function, the error_code in turn calls the above virtual function to obtain the error message.

It's important to remember that these error messages must stand alone; they may be written (to a log file, say) at a point in the program when no additional context is available. If you are wrapping an existing API that uses error messages with "inserts", you'll have to create your own messages. For example, if an HTTP API uses the message string "HTTP version %d.%d not supported", the equivalent stand-alone message would be "HTTP version not supported".

The <system_error> facility provides no assistance when it comes to localisation of these messages. It is likely that the messages emitted by your standard library's error categories will be based on the current locale. If localisation is a requirement in your program, I recommend using the same approach. (Some history: The LWG was aware of the need for localisation, but there was no design before the group that satisfactorily reconciled localisation with user-extensibility. Rather than engage in some design-by-committee, the LWG opted to say nothing in the standard about localisation of the error messages.)

Step 5: uniquely identify the category

The identity of an error_category-derived object is determined by its address. This means that when you write:

const std::error_category& cat1 = ...;
const std::error_category& cat2 = ...;
if (cat1 == cat2)
  ...

the if condition is evaluated as if you had written:

if (&cat1 == &cat2)
  ...

Following the example set by the standard library, you should provide a function to return a reference to a category object:

const std::error_category& http_category();

This function must always return a reference to the same object. One way to do that is to define a global object in a source file and return a reference to that:

http_category_impl http_category_instance;

const std::error_category& http_category()
{
  return http_category_instance;
}

However, using a global does introduce issues to do with order of initialisation across modules. An alternative approach is to use a locally scoped static variable:

const std::error_category& http_category()
{
  static http_category_impl instance;
  return instance;
}

In this case, the category object is initialised on first use. C++0x also guarantees that the initialisation is thread-safe. (C++03 makes no such guarantee.)

History: In the early design stages, we considered using an integer or string to identify an error_code's category. The main issue with that approach was ensuring uniqueness in conjunction with user extensibility. If a category was identified by integer or string, what was to stop collisions between two unrelated libraries? Using object identity leverages the linker in preventing different categories from having the same identity. Furthermore, storing a pointer to a base class allows us to make error_codes polymorphic while keeping them as copyable value types.

Step 6: construct an `error_code` from the `enum`

As I showed in part 3, the <system_error> implementation requires a function called make_error_code() to associate an error value with a category. For the HTTP errors, you would write this function as follows:

std::error_code make_error_code(http_error e)
{
  return std::error_code(
      static_cast<int>(e),
      http_category());
}

For completeness, you should also provide the equivalent function for construction of an error_condition:

std::error_condition make_error_condition(http_error e)
{
  return std::error_condition(
      static_cast<int>(e),
      http_category());
}

Since the <system_error> implementation finds these functions using argument-dependent lookup, you should put them in the same namespace as the http_error type.

Step 7: register for implicit conversion to `error_code`

For the http_error enumerators to be usable as error_code constants, enable the conversion constructor using the is_error_code_enum type trait:

namespace std
{
  template <>
  struct is_error_code_enum<http_error>
    : public true_type {};
}

Step 8 (optional): assign default error conditions

Some of the errors you define may have a similar meaning to the standard's errc error conditions. For example, the HTTP response code 403 Forbidden means basically the same thing as std::errc::permission_denied.

The error_category::default_error_condition() virtual function lets you define an error_condition that is equivalent to a given error code. (See part 2 for the definition of equivalence.) For the HTTP errors, you can write:

class http_category_impl
  : std::error_category
{
public:
  ...
  virtual std::error_condition
    default_error_condition(int ev) const;
};
...
std::error_condition
  http_category_impl::default_error_condition(
    int ev) const
{
  switch (ev)
  {
  case http_error::forbidden:
    return std::errc::permission_denied;
  default:
    return std::error_condition(ev, *this);
  }
}

If you choose not to override this virtual function, an error_code's default error_condition is one with the same error value and category. This is the behaviour of the default: case shown above.

Using the error codes

You can now use the http_error enumerators as error_code constants, both when setting an error:

void server_side_http_handler(
    ...,
    std::error_code& ec)
{
  ...
  ec = http_error::ok;
}

and when testing for one:

std::error_code ec;
load_resource("http://some/url", ec);
if (ec == http_error::ok)
  ...

Since the error values are based on the HTTP response codes, we can also set an error_code directly from the response:

std::string load_resource(
    const std::string& url,
    std::error_code& ec)
{
  // send request ...

  // receive response ...

  int response_code;
  parse_response(..., &response_code);
  ec.assign(response_code, http_category());

  // ...
}

You can also use this technique when wrapping the errors produced by an existing library.

Finally, if you defined an equivalence relationship in step 8, you can write:

std::error_code ec;
data = load_resource("http://some/url", ec);
if (ec == std::errc::permission_denied)
  ...

without needing to know the exact source of the error condition. As explained in part 2, the original error code (e.g. http_error::forbidden) is retained so that no information is lost.

In the next part, I'll show how to create and use custom error_conditions.

System error support in C++0x - part 3

2010-04-09T08:00:00.004+10:00

[ part 1, part 2 ]

Enumerators as class constants

As we have seen, the <system_error> header defines enum class errc:

enum class errc
{
  address_family_not_supported,
  address_in_use,
  ...
  value_too_large,
  wrong_protocol_type,
};

the enumerators of which are placeholders for error_condition constants:

std::error_code ec;
create_directory("/some/path", ec);
if (ec == std::errc::file_exists)
  ...

Obviously, this is because there's an implicit conversion from errc to error_condition using a single-argument constructor. Simple. Right?

It's not quite that simple

There's a few reasons why there's a bit more to it than that:

The enumerator provides an error value, but to construct an error_condition we need to know the category too. The <system_error> facility uses categories to support multiple error sources, and a category is an attribute of both error_code and error_condition.
The facility should be user-extensible. That is, users (as well as future extensions to the standard library) need to be able to define their own placeholders.
The facility should support placeholders for either error_code or error_condition. Although enum class errc provides placeholders for error_condition constants, other use cases may require constants of type error_code.
Finally, it should allow explicit conversion from an enumerator to error_code or error_condition. Portable programs may need to create error codes that are derived from the std::errc::* enumerators.

So, while it's true that the line:

if (ec == std::errc::file_exists)

implicitly converts from errc to error_condition, there are a few more steps involved.

Step 1: determine whether the `enum` is an error code or condition

Two type traits are used to register enum types with the facility:

template <class T>
struct is_error_code_enum
  : public false_type {};

template <class T>
struct is_error_condition_enum
  : public false_type {};

If a type is registered using is_error_code_enum<> then it may be implicitly converted to an error_code. Similarly, if a type is registered using is_error_condition_enum<>, it can be implicitly converted to error_condition. By default, types are registered for neither conversion (hence the use of false_type above), but enum class errc is registered as follows:

template <>
struct is_error_condition_enum<errc>
  : true_type {};

The implicit conversion is accomplished by conditionally enabled conversion constructors. This is probably implemented using SFINAE, but for simplicity you need only think of it as:

class error_condition
{
  ...
  // Only available if registered
  // using is_error_condition_enum<>.
  template <class ErrorConditionEnum>
  error_condition(ErrorConditionEnum e);
  ...
};

class error_code
{
  ...
  // Only available if registered
  // using is_error_code_enum<>.
  template <class ErrorCodeEnum>
  error_code(ErrorCodeEnum e);
  ...
};

Therefore, when we write:

if (ec == std::errc::file_exists)

the compiler has to choose between these two overloads:

bool operator==(
    const error_code& a,
    const error_code& b);

bool operator==(
    const error_code& a,
    const error_condition& b);

It chooses the latter because the error_condition conversion constructor is available, but the error_code one is not.

Step 2: associate the value with an error category

An error_condition object contains two attributes: value and category. Now that we're in the constructor, these need to be initialised correctly.

This is accomplished by having the constructor call the function make_error_condition(). To enable user-extensibility, this function is located using argument-dependent lookup. Of course, since errc is in namespace std, its make_error_condition() is found there too.

The implementation of make_error_condition() is simply:

error_condition make_error_condition(errc e)
{
  return error_condition(
      static_cast<int>(e),
      generic_category());
}

As you can see, this function uses the two-argument error_condition constructor to explicitly specify both the error value and category.

If we were in the error_code conversion constructor (for an appropriately registered enum type), the function called would be make_error_code(). In other respects, the construction of error_code and error_condition is the same.

Explicit conversion to `error_code` or `error_condition`

Although error_code is primarily intended for use with OS-specific errors, portable code may want to construct an error_code from an errc enumerator. For this reason, both make_error_code(errc) and make_error_condition(errc) are provided. Portable code can use these as follows:

void do_foo(std::error_code& ec)
{
#if defined(_WIN32)
  // Windows implementation ...
#elif defined(linux)
  // Linux implementation ...
#else
  // do_foo not supported on this platform
  ec = make_error_code(std::errc::not_supported);
#endif
}

Some history

The original <system_error> proposal defined error_code constants as objects:

extern error_code address_family_not_supported;
extern error_code address_in_use;
...
extern error_code value_too_large;
extern error_code wrong_protocol_type;

The LWG was concerned about the size overhead of so many global objects, and an alternative approach was requested. We researched the possibility of using constexpr, but that was ultimately found to be incompatible with some other aspects of the <system_error> facility. This left conversion from enum as the best available design.

Next, I'll start showing how you can extend the facility to add your own error codes and conditions.

System error support in C++0x - part 2

2010-04-08T07:13:00.002+10:00

[ part 1 ]

`error_code` vs `error_condition`

Of the 1000+ pages of C++0x draft, the casual reader is bound to notice one thing: error_code and error_condition look virtually identical! What's going on? Is it a copy/paste error?

It's what you do with it that counts

Let's review the descriptions I gave in part 1:

class error_code - represents a specific error value returned by an operation (such as a system call).
class error_condition - something that you want to test for and, potentially, react to in your code.

The classes are distinct types because they're intended for different uses. As an example, consider a hypothetical function called create_directory():

void create_directory(
    const std::string& pathname,
    std::error_code& ec);

which you call like this:

std::error_code ec;
create_directory("/some/path", ec);

The operation can fail for a variety of reasons, such as:

Insufficient permission.
The directory already exists.
The path is too long.
The parent path doesn't exist.

Whatever the reason for failure, after create_directory() returns, the error_code object ec will contain the OS-specific error code. On the other hand, if the call was successful then ec contains a zero value. This follows the tradition (used by errno and GetLastError()) of having 0 indicate success and non-zero indicate failure.

If you're only interested in whether the operation succeeded or failed, you can use the fact that error_code is convertible-to-bool:

std::error_code ec;
create_directory("/some/path", ec);
if (!ec)
{
  // Success.
}
else
{
  // Failure.
}

However, let's say you're interested in checking for the "directory already exists" error. If that's the error then our hypothetical caller can continue running. Let's have a crack at it:

std::error_code ec;
create_directory("/some/path", ec);
if (ec.value() == EEXIST) // No!
  ...

This code is wrong. You might get away with it on POSIX platforms, but don't forget that ec will contain the OS-specific error. On Windows, the error is likely to be ERROR_ALREADY_EXISTS. (Worse, the code doesn't check the error code's category, but we'll cover that later.)

Rule of thumb: If you're calling error_code::value() then you're doing it wrong.

So here you have an OS-specific error code (EEXIST or ERROR_ALREADY_EXISTS) that you want to check against an error condition ("directory already exists"). Yep, that's right, you need an error_condition.

Comparing `error_code`s and `error_condition`s

Here is what happens when you compare error_code and error_condition objects (i.e. when you use operator== or operator!=):

error_code against error_code - checks for exact match.
error_condition against error_condition - checks for exact match.
error_code against error_condition - checks for equivalence.

I hope that it's now obvious that you should be comparing your OS-specific error code ec against an error_condition object that represents "directory already exists". C++0x provides one for exactly that: std::errc::file_exists. This means you should write:

std::error_code ec;
create_directory("/some/path", ec);
if (ec == std::errc::file_exists)
  ...

This works because the library implementor has defined the equivalence between the error codes EEXIST or ERROR_ALREADY_EXISTS and the error condition std::errc::file_exists. In a future instalment I'll show how you can add your own error codes and conditions with the appropriate equivalence definitions.

(Note that, to be precise, std::errc::file_exists is an enumerator of enum class errc. For now you should think of the std::errc::* enumerators as placeholders for error_condition constants. In a later part I'll explain how that works.)

How to know what conditions you can test for

Some of the new library functions in C++0x have "Error conditions" clauses. These clauses list the error_condition constants and the conditions under which equivalent error codes will be generated.

A bit of history

The original error_code class was proposed for TR2 as a helper component for the filesystem and networking libraries. In that design, an error_code constant is implemented so that it matches the OS-specific error, where possible. When a match is not possible, or where there are multiple matches, the library implementation translates from the OS-specific error to the standard error_code, after performing the underlying operation.

In email-based design discussions I learnt the value of preserving the original error code. Subsequently, a generic_error class was prototyped but did not satisfy. A satisfactory solution was found in renaming generic_error to error_condition. In my experience, naming is one of the Hardest Problems in Computer Science, and a good name will get you most of the way there.

Next up, a look at the mechanism that makes enum class errc work as error_condition placeholders.

System error support in C++0x - part 1

2010-04-07T14:45:00.005+10:00

Among the many new library features in C++0x is a little header called <system_error>. It provides a selection of utilities for managing, well, system errors. The principal components defined in the header are:

class error_category
class error_code
class error_condition
class system_error
enum class errc

I had a hand in the design of this facility, so in this series of posts I will try to capture the rationale, history, and intended uses of the various components.

Where to get it

A complete implementation, and one that supports C++03, is included in Boost. I'd guess that, at this point in time, it is probably the best tested implementation in terms of portability. Of course, you have to spell things starting with boost::system:: rather than std::.

An implementation is included with GCC 4.4 and later. However, you must compile your program with the -std=c++0x option in order to use it.

Finally, Microsoft Visual Studio 2010 will ship with an implementation of the classes. The main limitation is that the system_category() does not represent Win32 errors as was intended. More on what that means later.

(Note that these are just the implementations that I am aware of. There may be others.)

Overview

Here are the types and classes defined by <system_error>, in a nutshell:

class error_category - intended as a base class, an error_category is used to define sources of errors or categories of error codes and conditions.
class error_code - represents a specific error value returned by an operation (such as a system call).
class error_condition - something that you want to test for and, potentially, react to in your code.
class system_error - an exception used to wrap error_codes when an error is to be reported via throw/catch.
enum class errc - a set of generic error condition values, derived from POSIX.
is_error_code_enum<>, is_error_condition_enum<>, make_error_code, make_error_condition - a mechanism for converting enum class error values into error_codes or error_conditions.
generic_category() - returns a category object used to classify the errc-based error codes and conditions.
system_category() - returns a category object used for error codes that originate from the operating system.

Principles

This section lists some of the guiding principles I had in mind in designing the facility. (I cannot speak for the others involved.) As with most software projects, some were goals at the outset and some were picked up along the way.

Not all errors are exceptional

Simply put, exceptions are not always the right way to handle errors. (In some circles this is a controversial statement, although I really don't understand why.)

In network programming, for example, there are commonly encountered errors such as:

You were unable to connect to a remote IP address.
Your connection dropped out.
You tried to open an IPv6 socket but no IPv6 network interfaces are available.

Sure, these might be exceptional conditions, but equally they may be handled as part of normal control flow. If you reasonably expect it to happen, it's not exceptional. Respectively:

The IP address is one of a list of addresses corresponding to a host name. You want to try connecting to the next address in the list.
The network is unreliable. You want to try to reestablish the connection and only give up after N failures.
Your program can drop back to using an IPv4 socket.

Another requirement, in the case of Asio, was a way to pass the result of an asynchronous operation to its completion handler. In this case, I want the operation's error code to be an argument to the handler callback. (An alternative approach is to provide a means to rethrow an exception inside the handler, such as .NET's BeginXYZ/EndXYZ asynchronous pattern. In my opinion, that design adds complexity and makes the API more error-prone.)

Last, but not least, some domains will be unable or unwilling to use exceptions due to code size and performance constraints.

In short: be pragmatic, not dogmatic. Use whatever error mechanism suits best in terms of clarity, correctness, constraints, and, yes, even personal taste. Often the right place to make the decision between exception and error code is at the point of use. That means a system error facility should support both.

Errors come from multiple sources

The C++03 standard recognises errno as a source of error codes. This is used by the stdio functions, some math functions, and so forth.

On POSIX platforms, many system operations do use errno to propagate errors. POSIX defines additional errno error codes to cover these cases.

Windows, on the other hand, does not make use of errno beyond the standard C library. Windows API calls typically report their errors via GetLastError.

When one considers network programming, the getaddrinfo family of functions uses its own set of error codes (EAI_...) on POSIX, but shares the GetLastError() "namespace" on Windows. Programs that integrate other libraries (for SSL, regular expressions, or whatever) will encounter other categories of error code.

Programs should be able to manage these error codes in a consistent manner. I'm especially concerned with enabling composition of operations to create higher-level abstractions. Combining system calls, getaddrinfo, SSL and regular expressions into one API should not force the user of that API to deal with an explosion of error code types. The addition of a new error source to the implementation of that API should not change the interface.

Be user-extensible

Users of the standard library need to be able to add their own error sources. This ability may just be used to integrate a third-party library, but is also tied in with the desire to create higher-level abstractions. When developing a protocol implementation such as HTTP, I want to be able to add a set of error codes corresponding to the errors defined in the RFC.

Preserve the original error code

This was not one of my original goals: my thinking was that the standard would provide a set of well-known error codes. If a system operation returned an error, it was the responsibility of the library to translate the error into a well-known code (if such a mapping made sense).

Fortunately, someone showed me the error of my ways. Translating an error code discards information: the error returned by the underlying system call is lost. This may not be a big deal in terms of program control flow, but it matters a lot for program supportability. There is no doubt that programmers will use a standardised error code object for logging and tracing, and the original error may be vital in diagnosing problems.

This final principle segues nicely into my topic for part 2: error_code vs error_condition. Stay tuned.

Bind illustrated

2010-04-06T16:24:00.004+10:00

Asynchronous operations in Asio all expect a function object argument, the completion handler, which they invoke when the asynchronous operation completes. The signature of the handler depends on the type of operation. For example, a handler posted using io_service::post() must have the signature:

void handler();

while an asynchronous wait operation expects:

void handler(error_code ec);

and asynchronous read/write operations want:

void handler(error_code ec, size_t length);

Non-trivial applications will need to pass some context to the completion handler, such as a this pointer. One way to do this is to use a function object adapter like boost::bind, std::tr1::bind or (as of C++0x) std::bind.

Unfortunately, for many C++ programmers, bind represents a little bit of magic. This is not helped by the impenetrable compiler errors that confront you when you use it incorrectly. And, in my experience, the underlying concept (where some function arguments are bound up-front, while others are delayed until the point of call) can present quite a steep learning curve.

I have put together some diagrams to help explain how bind works. For clarity, I have taken a few liberties with C++ syntax (e.g. omitting the parameter types on the function call operator) and (over-)simplified bind's implementation. Finally, the examples are limited to those likely to be useful with Asio. Comments and suggestions welcome.

bind can be used to adapt a user-supplied function expecting one argument into a function object that takes zero arguments. The bound value (123 in this example) is stored in a function object and is automatically passed to the user-supplied function as required:

[ click images for full size ]

Binding an argument can be used to turn a class member function into a zero-argument function object. As you know, non-static member functions have an implicit this parameter. This means that an appropriate pointer needs to be bound into the function object:

Alternatively, the implicit this can be made explicit by adapting a member function into a function object taking one argument:

Function objects will often use both bound arguments and arguments supplied at the point of use. This can be done using member functions:

or non-member functions:

Sometimes the function object's point of use will supply arguments which are not required to call the target function. bind will automatically discard these surplus arguments:

The surplus argument(s) need not be the at the end of the function object signature:

Finally, bind allows you to the reorder arguments to adapt the target function to the necessary function object signature:

Timeouts by analogy

2010-04-05T22:07:00.002+10:00

Most networking-enabled applications have to deal with timeouts. Read or write operations may continue indefinitely, and programs need a way to determine when to tear down connections, resend requests, or take whatever other measures are necessary.

Asio includes the deadline_timer class for managing timeouts. This class aims to provide a minimal interface for scheduling events. Of course, minimalism gives little in the way of design guidance, so some users struggle in finding an elegant way to incorporate timers and timeouts into their programs.

From the minimalist perspective of Asio, there's no one true right way to do it. (Perhaps there's no better proof of that than my design preferences having changed over the years.) Yet that answer doesn't get programs written, so in this post I will try to present a simple mental model for managing timers.

Parking meters

High-traffic, commercial areas near where I live have limited on-street parking. The street parking that is available is metered. It's the usual drill:

Park your vehicle.

Feed some coins into the parking meter (or, as is more likely these days, swipe your credit card or send an SMS).

Go do whatever you came to do.

Make sure you return to your vehicle before the meter expires.

If you don't get back in time, you'd better hope your vehicle hasn't had a visit from the parking inspector. A visit means a ticket under the wipers and a nasty fine due.

Parking meters are a good analogy for reasoning about timeouts because it's easy to identify the two actors:

The driver of the vehicle.

The parking inspector.

The driver performs the following steps:

Feeds the meter.

Leaves the vehicle to run some errands.

Returns to the vehicle.

If no ticket has been issued, repeats from step 1.

If a fine has been issued, goes home.

The parking inspector's job is simple:

Checks whether the meter has expired.

If the meter has expired, writes up a ticket.

If the meter has not expired, notes how much time is remaining.

Goes off for a walk until the remaining time has elapsed.

Using the analogy to inform program design

Hopefully you've already guessed how these actors map to networked applications:

The driver represents your protocol handling code.

The parking inspector corresponds to your timeout management logic.

Let's take a look at how this works in a very simple use case.

// The "driver" actor.
void session::handle_read(error_code ec, size_t length)
{
  // On entering this function we have returned to the vehicle.

  if (!ec)
  {
    // Phew, no ticket. Feed the meter.
    my_timer.expires_from_now(seconds(5));

    // Process incoming data.
    // ...

    // Run some more errands.
    my_socket.async_read_some(buffer(my_buffer),
        bind(&session::handle_read, this, _1, _2));
  }
  else
  {
    // We got a ticket. Go home.
  }
}

// The "parking inspector" actor.
void session::handle_timeout(error_code ec)
{
  // On entering this function we are checking the meter.

  // Has the meter expired?
  if (my_timer.expires_from_now() < seconds(0))
  {
    // Write up a ticket.
    my_socket.close();
  }
  else
  {
    // Note remaining time and go for a walk.
    my_timer.async_wait(
        bind(&session::handle_timeout, this, _1));
  }
}

It's important to remember that the driver may need to run multiple errands each time they leave the vehicle. In protocol terms, you might have a fixed-length header followed by a variable-length body. You only want to "feed the meter" once you have received a complete message:

// First part of the "driver" actor.
void session::handle_read_header(error_code ec)
{
  // We're not back at the vehicle yet.

  if (!ec)
  {
    // Process header.
    // ...

    // Run some more errands.
    async_read(my_socket, buffer(my_body),
        bind(&session::handle_read_body, this, _1));
  }
}

// Second part of the "driver" actor.
void session::handle_read_body(error_code ec)
{
  // On entering this function we have returned to the vehicle.

  if (!ec)
  {
    // Phew, no ticket. Feed the meter.
    my_timer.expires_from_now(seconds(5));

    // Process complete message.
    // ...

    // Run some more errands.
    async_read(my_socket, buffer(my_header),
        bind(&session::handle_read_header, this, _1));
  }
  else
  {
    // We got a ticket. Go home.
  }
}

There are many variations on this theme. For example, you may feed the meter between consecutive errands, varying the amount of money inserted (i.e. setting different length timeouts) depending on which errand comes next. In protocol terms, that might mean allowing up to 30 seconds between messages, but only a further 5 seconds is permitted once the message header has been received.

As I indicated earlier, there's no single right way to manage timeouts. In fact, there are many different facets to this problem that are probably worth exploring in their own right. However, I think that the approach shown here is probably suited to most applications and I would recommend it as a starting point when designing your timeout handling.

A potted guide to stackless coroutines

2010-03-31T11:40:00.012+11:00

Keen-eyed Asio users may have noticed that Boost 1.42 includes a new example, HTTP Server 4, that shows how to use stackless coroutines in conjunction with asynchronous operations. This follows on from the coroutines I explored in the previous three posts, but with a few improvements. In particular:

the pesky entry pseudo-keyword is gone; and
a new fork pseudo-keyword has been added.

The result bears a passing resemblance to C#'s yield and friends. This post aims to document my stackless coroutine API, but before launching into a long and wordy explanation, here's a little picture to liven things up:

[ Click image for full size. This image was generated from this source code using asioviz. ]

class coroutine

Every coroutine needs to store its current state somewhere. For that we have a class called coroutine:

class coroutine
{
public:
  coroutine();
  bool is_child() const;
  bool is_parent() const;
  bool is_complete() const;
};

Coroutines are copy-constructible and assignable, and the space overhead is a single int. They can be used as a base class:

class session : coroutine
{
  ...
};

or as a data member:

class session
{
  ...
  coroutine coro_;
};

or even bound in as a function argument using bind() (see previous post). It doesn't really matter as long as you maintain a copy of the object for as long as you want to keep the coroutine alive.

reenter

The reenter macro is used to define the body of a coroutine. It takes a single argument: a pointer or reference to a coroutine object. For example, if the base class is a coroutine object you may write:

reenter (this)
{
  ... coroutine body ...
}

and if a data member or other variable you can write:

reenter (coro_)
{
  ... coroutine body ...
}

When reenter is executed at runtime, control jumps to the location of the last yield or fork.

The coroutine body may also be a single statement. This lets you save a few keystrokes by writing things like:

reenter (this) for (;;)
{
  ...
}

Limitation: The reenter macro is implemented using a switch. This means that you must take care when using local variables within the coroutine body. The local variable is not allowed in a position where reentering the coroutine could bypass the variable definition.

yield statement

This form of the yield keyword is often used with asynchronous operations:

yield socket_->async_read_some(buffer(*buffer_), *this);

This divides into four logical steps:

yield saves the current state of the coroutine.
The statement initiates the asynchronous operation.
The resume point is defined immediately following the statement.
Control is transferred to the end of the coroutine body.

When the asynchronous operation completes, the function object is invoked and reenter causes control to transfer to the resume point. It is important to remember to carry the coroutine state forward with the asynchronous operation. In the above snippet, the current class is a function object object with a coroutine object as base class or data member.

The statement may also be a compound statement, and this permits us to define local variables with limited scope:

yield
{
  mutable_buffers_1 b = buffer(*buffer_);
  socket_->async_read_some(b, *this);
}

yield return expression ;

This form of yield is often used in generators or coroutine-based parsers. For example, the function object:

struct interleave : coroutine
{
  istream& is1;
  istream& is2;
  char operator()(char c)
  {
    reenter (this) for (;;)
    {
      yield return is1.get();
      yield return is2.get();
    }
  }
};

defines a trivial coroutine that interleaves the characters from two input streams.

This type of yield divides into three logical steps:

yield saves the current state of the coroutine.
The resume point is defined immediately following the semicolon.
The value of the expression is returned from the function.

yield ;

This form of yield is equivalent to the following steps:

yield saves the current state of the coroutine.
The resume point is defined immediately following the semicolon.
Control is transferred to the end of the coroutine body.

This form might be applied when coroutines are used for cooperative threading and scheduling is explicitly managed. For example:

struct task : coroutine
{
  ...
  void operator()()
  {
    reenter (this)
    {
      while (... not finished ...)
      {
        ... do something ...
        yield;
        ... do some more ...
        yield;
      }
    }
  }
  ...
};
...
task t1, t2;
for (;;)
{
  t1();
  t2();
}

yield break ;

The final form of yield is adopted from C# and is used to explicitly terminate the coroutine. This form is comprised of two steps:

yield sets the coroutine state to indicate termination.
Control is transferred to the end of the coroutine body.

Once terminated, calls to is_complete() return true and the coroutine cannot be reentered.

Note that a coroutine may also be implicitly terminated if the coroutine body is exited without a yield, e.g. by return, throw or by running to the end of the body.

fork statement ;

The fork pseudo-keyword is used when "forking" a coroutine, i.e. splitting it into two (or more) copies. One use of fork is in a server, where a new coroutine is created to handle each client connection:

reenter (this)
{
  do
  {
    socket_.reset(new tcp::socket(io_service_));
    yield acceptor->async_accept(*socket_, *this);
    fork server(*this)();
  } while (is_parent());
  ... client-specific handling follows ...
}

The logical steps involved in a fork are:

fork saves the current state of the coroutine.
The statement creates a copy of the coroutine and either executes it immediately or schedules it for later execution.
The resume point is defined immediately following the semicolon.
For the "parent", control immediately continues from the next line.

The functions is_parent() and is_child() can be used to differentiate between parent and child. You would use these functions to alter subsequent control flow.

Note that fork doesn't do the actual forking by itself. It is your responsibility to write the statement so that it creates a clone of the coroutine and calls it. The clone can be called immediately, as above, or scheduled for delayed execution using something like io_service::post().

Composed operations, coroutines and code makeover

2009-08-12T20:02:00.007+10:00

In the previous two posts, I showed some nifty macros for doing clean and simple stackless coroutines with asio. Hold on to your hats, because in this post we'll see what these coroutines can really do for your asio programs.

A design goal of asio is to provide a basis for further levels of abstraction. One of the ways to develop abstractions on top of asio is to create what I like to call composed operations. These are simply operations that are made up of calls to other lower-level operations. Asio already includes some composed operations to address common network programming problems: async_read and async_write to deal with short reads and writes; and async_read_until to perform delimited reads.

As an example, let's say we want to write a composed operation that echoes all data received on a socket until an error occurs. The way I have done this in the past (and the way composed operations like async_read_until are written) is to implement the operation as a set of function objects:

template <typename Handler>
struct echo_read_handler
{
  tcp::socket& socket;
  mutable_buffer working_buffer;
  Handler handler;
  void operator()(error_code ec, size_t length);
}

template <typename Handler>
struct echo_write_handler
{
  tcp::socket& socket;
  mutable_buffer working_buffer;
  Handler handler;
  void operator()(error_code ec, size_t length);
};

template <typename Handler>
void echo_read_handler::operator()(
    error_code ec, size_t length)
{
  if (!ec)
  {
    echo_write_handler write_handler =
      { socket, working_buffer, handler };

    async_write(socket,
        buffer(working_buffer, length),
        write_handler);
  }
  else
    handler(ec);
}

template <typename Handler>
void echo_write_handler::operator()(
    error_code ec, size_t /*length*/)
{
  if (!ec)
  {
    echo_read_handler read_handler =
      { socket, working_buffer, handler };

    socket.async_read_some(
        buffer(working_buffer),
        read_handler);
  }
  else
    handler(ec);
}

and a convenience function which acts as the public interface for the abstraction:

template <typename Handler>
void async_echo(
    tcp::socket& socket,
    mutable_buffer working_buffer,
    Handler handler)
{
  echo_read_handler read_handler =
    { socket, working_buffer, handler };

  socket.async_read_some(
      buffer(working_buffer),
      read_handler);
}

Not very encouraging if you want to write your own abstractions, is it? Now imagine you've been asked to develop a composed operation to send an email using SMTP. That would involve about a dozen lower level operations, so even I probably wouldn't bother if I had to use a function object approach.

Coroutines to the rescue

In the previous two posts we already saw how to combine stackless coroutines with asio's asynchronous operations, simply by prepending the yield "keyword". I'm sure you know where this is going... We can also use a coroutine to implement a composed operation.

Let's rewrite async_echo as a coroutine:

template <typename Handler>
struct echo_coro
{
  tcp::socket& socket;
  mutable_buffer working_buffer;
  Handler handler;
  coroutine coro;
  void operator()(
    error_code ec = error_code(),
    size_t length = 0)
  {
    reenter (coro)
    {
    entry:
      while (!ec)
      {
        yield socket.async_read_some(
            buffer(working_buffer), *this);

        if (ec) break;

        yield async_write(socket,
            buffer(working_buffer, length), *this);
      }

      handler(ec);
    }
  }
};

template <typename Handler>
void async_echo(
    tcp::socket& socket,
    mutable_buffer working_buffer,
    Handler handler)
{
  echo_coro coro = { socket, working_buffer, handler };
  coro();
}

The code is much shorter and clearer than the function object version. For an SMTP email operation the savings would be so much more, but I'll leave that as an exercise for the reader.

Now you might think this next point is obvious, but I'm going to say it anyway and put it in bold because it's important:

The fact that the composed operation is implemented as a coroutine is entirely transparent to the caller.

What does this mean? It means:

You can write your composed operations as coroutines, or not, as you choose.
You can combine those composed operations still further using coroutines (or not).

And so on and so on, up through as many layers of abstraction as you think you can reasonably fit into your program.

An alternative approach

One aspect of the implementation above still bothers me a little: repetition. Specifically, the repetition of the operation's template parameter list and the arguments (socket, working_buffer and handler) when defining the coroutine's function object.

Here's an alternative design that implements the composed operation in a single function:

template <typename Handler>
void async_echo(
  tcp::socket& socket,
  mutable_buffer working_buffer,
  Handler handler,
  // coroutine state:
  coroutine coro = coroutine(),
  error_code ec = error_code(),
  size_t length = 0)
{
  reenter (coro)
  {
  entry:
    while (!ec)
    {
      yield socket.async_read_some(
          buffer(working_buffer),
          bind(&async_echo<Handler>,
            ref(socket), working_buffer,
            box(handler), coro, _1, _2));

      if (ec) break;

      yield async_write(socket,
          buffer(working_buffer, length),
          bind(&async_echo<Handler>,
            ref(socket), working_buffer,
            box(handler), coro, _1, _2));
    }

    handler(ec);
  }
}

(N.B. box() wraps the handler with another function object to prevent evaluation of the handler as a nested bind expression.)

Of course, we've just traded one type of repetition for another: the bind expressions to create the completion handlers. At this point, I think it's a matter of taste which approach you use.

Lambdas == code liposuction

It's left to C++0x lambdas to make the coroutine-in-one-function approach the clear winner in brevity, and perhaps not in the way you first expect. Combined with auto, you can use lambdas as local functions to eliminate repeated code:

template <typename Handler>
void async_echo(
  tcp::socket& socket,
  mutable_buffer working_buffer,
  Handler handler,
  // coroutine state:
  coroutine coro = coroutine(),
  error_code ec = error_code(),
  size_t length = 0)
{
  auto resume = [&]()
  {
    return bind(&async_echo<Handler>,
        ref(socket), working_buffer,
        box(handler), coro, _1, _2));
  };

  reenter (coro)
  {
  entry:
    while (!ec)
    {
      yield socket.async_read_some(
          buffer(working_buffer),
          resume());

      if (ec) break;

      yield async_write(socket,
          buffer(working_buffer, length),
          resume());
    }

    handler(ec);
  }
}

What we end up with is a composed operation in one function, a concise coroutine to specify the asynchronous control flow, and a single definition of how to reenter the coroutine.

Phew. I think we're done.

Secret sauce revealed

2009-08-10T22:52:00.003+10:00

In my previous post, I showed a little program using stackless coroutines with asio. Obviously there's no yield keyword in C++, so without further ado here's the preprocessor magic that makes it possible:

class coroutine
{
public:
  coroutine() : value_(0) {}
private:
  friend class coroutine_ref;
  int value_;
};

class coroutine_ref
{
public:
  coroutine_ref(coroutine& c) : value_(c.value_) {}
  coroutine_ref(coroutine* c) : value_(c->value_) {}
  operator int() const { return value_; }
  int operator=(int v) { return value_ = v; }
private:
  int& value_;
};

#define reenter(c) \
  switch (coroutine_ref _coro_value = c)

#define entry \
  extern void you_forgot_to_add_the_entry_label(); \
  bail_out_of_coroutine: break; \
  case 0

#define yield \
  if ((_coro_value = __LINE__) == 0) \
  { \
    case __LINE__: ; \
    (void)&you_forgot_to_add_the_entry_label; \
  } \
  else \
    for (bool _coro_bool = false;; \
         _coro_bool = !_coro_bool) \
      if (_coro_bool) \
        goto bail_out_of_coroutine; \
      else

Unlike the preprocessor-based coroutines presented here, the above macros let you yield from a coroutine without having to return from a function. Instead, the yield simply breaks you out of the reenter block. That trick is what allows us to write a server in one function.

Yes, yes, I know. An echo server in a single function is a bit of a gimmick. The following snippet may give a better idea of how the coroutines can be used:

class session : coroutine
{
public:
  session(tcp::acceptor& acceptor)
    : acceptor_(acceptor),
      socket_(new tcp::socket(acceptor.get_io_service())),
      data_(new array<char, 1024>)
  {
  }

  void operator()(
      error_code ec = error_code(),
      size_t length = 0)
  {
    reenter (this)
    {
    entry:
      for (;;)
      {
        yield acceptor_.async_accept(
            *socket_, *this);

        while (!ec)
        {
          yield socket_->async_read_some(
              buffer(*data_), *this);

          if (ec) break;

          yield async_write(*socket_,
              buffer(*data_, length), *this);
        }

        socket_->close();
      }
    }
  }

private:
  tcp::acceptor& acceptor_;
  shared_ptr<tcp::socket> socket_;
  shared_ptr<array<char, 1024> > data_;
};

Compared to the usual boost::bind-based approach of doing callbacks, the control flow is all in one place and easy to follow.

But wait, there's more... In the next post I'll reveal the real power you get when you combine stackless coroutines and asio.

Wife says: "I can't believe it works"

2009-07-29T23:04:00.007+10:00

Just a teaser:

int main()
{
  try
  {
    using asio::ip::tcp;
    using namespace boost::lambda;

    asio::io_service io_service;
    tcp::acceptor acceptor(io_service,
        tcp::endpoint(tcp::v4(), 54321));

    const int max_clients = 100;
    coroutine coro[max_clients];
    std::auto_ptr<tcp::socket> socket[max_clients];
    asio::error_code ec[max_clients];
    std::size_t length[max_clients];
    boost::array<char, 1024> data[max_clients];

    // Kick off all the coroutines.
    int n = -1;
    for (int i = 0; i < max_clients; ++i)
    {
      socket[i].reset(new tcp::socket(io_service));
      io_service.post(
          unlambda((
            var(n) = i
          )));
    }

    for (; io_service.run_one() > 0; n = -1)
    {
      if (n != -1)
      {
        reenter (coro[n])
        {
        entry:
          for (;;)
          {
            // Wait for a client to connect.
            yield acceptor.async_accept(
                *socket[n],
                unlambda((
                  var(n) = n,
                  var(ec[n]) = _1
                )));

            // Echo at will.
            while (!ec[n])
            {
              yield socket[n]->async_read_some(
                  asio::buffer(data[n]),
                  unlambda((
                    var(n) = n,
                    var(ec[n]) = _1,
                    var(length[n]) = _2
                  )));

              if (!ec[n])
              {
                yield asio::async_write(
                    *socket[n],
                    asio::buffer(data[n], length[n]),
                    unlambda((
                      var(n) = n,
                      var(ec[n]) = _1
                    )));
              }
            }

            // Clean up before accepting next client.
            socket[n]->close();
          }
        }
      }
    }
  }
  catch (std::exception& e)
  {
    std::cerr << "Exception: " << e.what() << "\n";
  }
}

One function. One fully asynchronous server. Bog standard C++.

User-friendly compile errors for templates in C++0x

2009-07-14T21:36:00.007+10:00

The C++0x features decltype, static_assert and the "new function declarator syntax" can be combined with our old friend SFINAE to generate nicer template compile errors.

As a simple example, consider a container class similar to std::set. Normally if you just declare a variable

set<my_type> s;

it will compile without error even if my_type has no operator<. You will only get an error when you try to call a set member function, such as insert(). Worse still, the errors tend to be quite verbose. (Too verbose for me to want to paste here, anyway.) It would be really nice to generate a short, readable error at the point of the original variable declaration. Let's see how we can do just that in C++0x.

First, we need to write a compile-time test for operator<. This is where SFINAE, decltype and the new function declarator syntax come together. We write the test function:

auto less_than_test(const T* t)
  -> decltype(*t < *t, char(0));

and the fallback overload:

std::array<char, 2> less_than_test(...);

The trick here is that, according to the C++0x grammar, we have:

decltype ( expression )

and

expression:
    assignment-expression
    expression , assignment-expression

This means that the first overload uses decltype to do two things: it makes the overload a viable candidate only if the expression *t < *t is valid; and it says the overload returns a char.

Second, we can use sizeof to determine which of the overloads is selected for a given type T, and static_assert to generate a readable error:

template <typename T>
class set
{
public:
  static_assert(
      sizeof(less_than_test((T*)0)) == 1,
      "type T must provide operator<");
};

The g++ 4.4 compiler then gives the following output on the original variable declaration:

test.cpp: In instantiation of set<my_type>
test.cpp:21:   instantiated from here
test.cpp:13: error: static assertion failed:
    "type T must provide operator<"

It works with function templates too. To add a check to Asio's async_read function's ReadHandler parameter, I could write the check as follows:

template <typename T>
auto read_handler_test(T* t)
  -> decltype(
      (*t)(
        *(const error_code*)0,
        (const std::size_t)0),
      char(0));

std::array<char, 2> read_handler_test(...);

template <..., typename ReadHandler>
void async_read(..., ReadHandler handler)
{
  static_assert(
      sizeof(read_handler_test(&handler)) == 1,
      "ReadHandler type requirements not met");
  ...
}

Perhaps with a touch of macro magic, checks of this sort could become quite easy to write.

"Hang on, what about C++0x concepts?" I hear you ask. What are they? ;-)

Asynchronous Fork/Join using Asio

2008-10-06T23:58:00.010+11:00

As most Asio users will no doubt be aware, multiple threads can call io_service::run() to set up a pool of threads from which the completion handlers will be executed. This can be used in conjunction with io_service::post() to execute arbitrary tasks in the thread pool.

In some rare spare moments I have used this facility to dabble in parallel algorithms (mainly to do with sorting large data sets). However, I was not completely satisfied with its ease-of-use when it came to implementing the algorithms.

Recently I came across the new Fork/Join framework that's going to be included in Java 7. I was particularly struck by the simplicity of the coinvoke() function, and was inspired to implement something similar on top of Asio. Of course, what with Asio and my preferred mode of thinking, I wanted to implement an asynchronous version.

And the result...

I created a function template that may be used to initiate two or more tasks to run in parallel:

template <typename TaskCont0, ..., typename TaskContN,
    typename Task0, ..., typename TaskN, Cont>
void coinvoke(asio::io_service& io_service,
    Task0 task0, ..., TaskN taskN, Cont cont);

Each task must be a function object with a single argument, where the argument is the continuation function object for the task. The TaskContN template parameters explicitly specify the function signatures used for each of the task continuations. For example:

coinvoke<void(int), void(int)>(task0, task1, cont);

says that both tasks have a continuation with the signature void(int). The combining continuation has a signature that is the concatenation of all of the task continuations' arguments. In the above example, that's void(int, int).

The operation of coinvoke() works as follows (click image for full size view):

You can get the implementation here. Don't expect the source to be readable; it contains hairy uses of template metaprogramming and preprocessor magic.

Why continuations?

You might be wondering why each task passes its result to a continuation function rather than simply returning it. The answer to that is that a task need not be a single calcuation; it could instead be the start of a chain of asynchronous operations. This means that coinvoke() could be used to simplify management of parallel operations, such as writing data to multiple sockets, and not having the handler called until all operations have finished. I plan to explore those and other related ideas further in the near future, but for now let's just look at parallel algorithms.

Fibonacci revisited

The equivalent implementation of the Fibonacci example from the Java Fork/Join paper looks like:

void combine_fib(
    int a, int b,
    function<void(int)> h)
{
  h(a + b);
}

void calc_fib(
    asio::io_service& io_service,
    int n,
    function<void(int)> f)
{
  if (n <= threshold)
  {
    f(seq_fib(n));
  }
  else
  {
    coinvoke<void(int), void(int)>(io_service,
        bind(calc_fib, ref(io_service), n - 1, _1),
        bind(calc_fib, ref(io_service), n - 2, _1),
        bind(combine_fib, _1, _2, f));
  }
}

Can I have C++0x lambdas now, please?

The need to define a separate combine_fib is not ideal, since a key part of the algorithm is off in another spot. Fortunately, C++0x's new monomorphic lambdas come to the rescue:

void calc_fib(
    asio::io_service& io_service,
    int n,
    function<void(int)> f)
{
  if (n <= threshold)
  {
    f(seq_fib(n));
  }
  else
  {
    coinvoke<void(int), void(int)>(io_service,
        [&io_service, =n](function<void(int)> c)
        {
          calc_fib(io_service, n - 1, c),
        },
        [&io_service, =n](function<void(int)> c)
        {
          calc_fib(io_service, n - 2, c),
        },
        [=f](int a, int b)
        {
          f(a + b);
        });
  }
}

A useful example

Since that has to come close to being the most convoluted way of calculating a Fibonacci value, here is an example where coinvoke() is used for a parallel merge sort:

template <typename Iterator>
void merge(
    Iterator begin,
    Iterator middle,
    Iterator end,
    function<void()> f)
{
  std::inplace_merge(begin, middle, end);
  f();
}

template <typename Iterator>
void sort(
    asio::io_service& io_service,
    Iterator begin,
    Iterator end,
    function<void()> f)
{
  std::size_t n = end - begin;
  if (n <= 16384)
  {
    std::sort(begin, end);
    io_service.post(f);
  }
  else
  {
    coinvoke<void(), void()>(io_service,

        // First task sorts the initial half of the range.
        bind(&sort<Iterator>,
          ref(io_service),
          begin, begin + n / 2, _1),

        // Second task sorts the latter half of the range.
        bind(&sort<Iterator>,
          ref(io_service),
          begin + n / 2, end, _1),

        // Continuation function merges the two sorted ranges.
        bind(&merge<Iterator>,
          begin, begin + n / 2, end, f)

        );
  }
}

On my 8-core machine, this gives a little more than a threefold speedup in sorting large vectors.

Mention in Stroustrup Interview

2008-06-27T11:49:00.002+10:00

The A-Z of Programming Languages: C++, top of page 5:

Do you feel that resources like the boost libraries will provide this functionality/accessibility for C++?

Some of the boost libraries - especially the networking library - are a good beginning. The C++0x standard threads look a lot like boost threads. If at all possible, a C++ programmer should begin with an existing library (and/or tool), rather than building directly on fundamental language features and/or system threads.

Not by name, but hey! The rest of the interview is worth reading too. ;)

Boost.Asio vs Asio

2008-05-23T08:05:00.015+10:00

Sometimes I am asked what the difference is between the (non-Boost) Asio and Boost.Asio packages I provide. Here is the definitive word on the subject, presented as a series of questions and answers.

What are the differences in the source code?

— Asio is in a namespace called asio::, whereas Boost.Asio puts everything under boost::asio::.

— The main Asio header file is called asio.hpp. The corresponding header in Boost.Asio is boost/asio.hpp. All other headers are similarly changed.

— Any macros used by or defined in Asio are prefixed with ASIO_. In Boost.Asio they are prefixed with BOOST_ASIO_.

— Asio includes a class for launching threads, asio::thread. Boost.Asio does not include this class, to avoid overlap with the Boost.Thread library

— Boost.Asio uses the Boost.System library to provide support for error codes (boost::system::error_code and boost::system::system_error). Asio includes these under its own namespace (asio::error_code and asio::system_error). The Boost.System version of these classes currently supports better extensibility for user-defined error codes.

— Asio is header-file-only and for most uses does not require linking against any Boost library. Boost.Asio always requires that you link against the Boost.System library, and also against Boost.Thread if you want to launch threads using boost::thread.

Where do I get a release package?

Asio is available for download from sourceforge, in a package named asio-X.Y.Z.tar.gz (or .tar.bz2 or .zip).

Boost.Asio is included in the Boost 1.35 distribution. It is also available as a separate package on sourceforge, named boost_asio_X_Y_Z.tar.gz. The latter is intended to be copied over the top of an existing Boost source code distribution.

Where are the source code repositories?

Asio uses a sourceforge-hosted CVS repository. Details of how to access it may be found here. It may also be browsed via the web.

Boost.Asio is checked into Boost's subversion repository.

How do you maintain both versions?

All development is done in the Asio CVS repository. I periodically convert the source into Boost format using a script called boostify.pl, and merge the changes into the Boost subversion repository.

Will Asio be discontinued now that Boost.Asio is included with Boost?

No. There are projects using Asio and they will continue to be supported. I also prefer to use Asio over Boost.Asio in my own projects, for the convenience of header-file-only and shorter namespaces.

Should I use Asio or Boost.Asio?

It depends. Here are some things to consider:

— If you (like me) prefer the convenience of header-file-only libraries then I'd suggest using Asio over Boost.Asio.

— If you must use a version of Boost older than 1.35 then Boost.Asio is not included. You can use Boost.Asio by copying it over the top of your Boost distribution (see above), but not everyone is comfortable doing this. In that case, I would suggest using Asio over Boost.Asio.

— I will be creating new versions of both the Asio and Boost.Asio packages on a faster release cycle than that followed by Boost. If you want to use the latest features you can still use Boost.Asio as long as you are happy to copy it over the top of your Boost distribution. If you don't want to do this, use Asio rather than Boost.Asio.

Can Asio and Boost.Asio coexist in the same program?

Yes. Since they use different namespaces there should be no conflicts, although obviously the types themselves are not interchangeable. (In case you're wondering why you might want to do this, consider a situation where a program is using third party libraries that are also using Asio internally.)

739 days ago ...

2008-03-30T22:09:00.003+11:00

... asio was accepted into Boost. Today you can find it as part of a Boost release. Woohoo!

Time Travel

2007-08-08T23:00:00.000+10:00

Many event-driven programs involve state changes that are triggered according to the system clock. You might be coding for:

A share market that opens at 10:00am and closes at 4:00pm.

An off-peak phone billing rate that starts after 7:00pm.

An interest calculation that is run on the last day of every month.

The asio::deadline_timer class lets you handle this easily. For example:

using namespace boost::posix_time;
typedef boost::date_time::c_local_adjustor<ptime> local_adj;

...

asio::deadline_timer timer(io_service);

ptime open_time(second_clock::local_time().date(), hours(10));
timer.expires_at(local_adj::local_to_utc(open_time));
timer.async_wait(open_market);

There's a catch: to test that your timer events work correctly, you have to run your program at the right time of day. It usually isn't practical to sit around all day (or, worse, all year) waiting for the timers to expire.

Time Traits

You may have noticed that the asio::deadline_timer class is actually a typedef:

typedef basic_deadline_timer<boost::posix_time::ptime>
  deadline_timer;

where the basic_deadline_timer class template is declared as follows:

template <
    typename Time,
    typename TimeTraits
      = asio::time_traits<Time>,
    typename TimerService
      = deadline_timer_service<Time, TimeTraits> >
class basic_deadline_timer;

In the context of our problem, the most interesting template parameter is the second one: TimeTraits. An implementation of TimeTraits lets us customise the treatment of the template's Time parameter, and consequently the behaviour of the timer itself.

A TimeTraits class must implement an interface that matches the following:

class TimeTraits
{
public:
  // The type used to represent an absolute time, i.e. the same
  // as the Time template parameter to basic_deadline_timer.
  typedef ... time_type;

  // The type used to represent the difference between two
  // absolute times.
  typedef ... duration_type;

  // Returns the current time.
  static time_type now();

  // Returns a new absolute time resulting from adding the
  // duration d to the absolute time t.
  static time_type add(time_type t, duration_type d);

  // Returns the duration resulting from subtracting t2 from t1.
  static duration_type subtract(time_type t1, time_type t2);

  // Returns whether t1 is to be treated as less than t2.
  static bool less_than(time_type t1, time_type t2);

  // Returns a "posix" duration corresponding to the duration d.
  static boost::posix_time::time_duration to_posix_duration(
      duration_type d);
};

As you can see from the declaration of the basic_deadline_timer class template, Asio provides a default TimeTraits implementation called asio::time_traits<>.

Offsetting Now

To test our timer events at any time of our choosing, we simply need to change the definition of "now" using a custom TimeTraits class.

Since we want to use the same time types as the regular deadline_timer class, we'll start by reusing the default traits implementation:

class offset_time_traits
  : public asio::deadline_timer::traits_type
{
};

The value returned by the now() function will be offset from the system clock by a specified duration:

class offset_time_traits
  : public asio::deadline_timer::traits_type
{

private:
  static duration_type offset_;
};

which is simply added to the system clock:

class offset_time_traits
  : public asio::deadline_timer::traits_type
{
public:
  static time_type now()
  {
    return add(asio::deadline_timer::traits_type::now(), offset_);
  }

private:
  static duration_type offset_;
};

Of course, we will also need to provide a way to set the offset, which can be done by setting an initial value for "now":

class offset_time_traits
  : public asio::deadline_timer::traits_type
{
public:
  static time_type now()
  {
    return add(asio::deadline_timer::traits_type::now(), offset_);
  }

  static void set_now(time_type t)
  {
    offset_ =
      subtract(t, asio::deadline_timer::traits_type::now());
  }

private:
  static duration_type offset_;
};

Creating a Timer

To use our custom traits type with the basic_deadline_timer template, we simply need to add the following typedef:

typedef asio::basic_deadline_timer<
    boost::posix_time::ptime, offset_time_traits> offset_timer;

To see the offset timer in action, let's create a timer to fire precisely at the start of the coming new year. So we don't have to wait until then, we'll set "now" to be just ten seconds prior to midnight:

offset_time_traits::set_now(
    boost::posix_time::from_iso_string("20071231T235950"));

offset_timer timer(io_service);
timer.expires_at(
    boost::posix_time::from_iso_string("20080101T000000"));
timer.async_wait(handle_timeout);

io_service.run();

When the program is run, it will take just ten seconds to complete.

Jumping Through Time

One feature not supported by the above solution is the ability to change the definition of "now" after the timers have been started. However, if your timer events are spread across a long period of time, then this is likely to be something you would want.

Let's say that the next timer does not expire for several hours, but in an attempt to speed things up we call set_now() to move to just seconds before. The problem with the above traits class is that the existing asynchronous wait operation does not know about the change to "now", and so will continue to run for the remaining hours.

Fortunately, Asio provides a way around this: by customising the to_posix_duration() function in our traits class.

The to_posix_duration() function is normally used to convert from a user-defined duration type to a type that Asio knows about (namely boost::posix_time::time_duration). The key point here is that this converted duration value is used by Asio to determine how long to wait until the timer expires. Furthermore, it doesn't matter if this function returns a duration that is smaller (even substantially so) than the actual duration. The timer won't fire early, because Asio guarantees that it won't expire until the following condition holds true:

!TimeTraits::less_than(Time_Traits::now(), timer.expires_at())

So, by adding the to_posix_duration() function to our traits class:

class offset_time_traits
  : public asio::deadline_timer::traits_type
{
public:
  static time_type now()
  {
    return add(asio::deadline_timer::traits_type::now(), offset_);
  }

  static void set_now(time_type t)
  {
    offset_ =
      subtract(t, asio::deadline_timer::traits_type::now());
  }

  static boost::posix_time::time_duration to_posix_duration(
      duration_type d)
  {
    return d < boost::posix_time::seconds(5)
      ? d : boost::posix_time::seconds(5);
  }

private:
  static duration_type offset_;
};

we can ensure that Asio detects changes to the offset within seconds.

New home heating solution

2007-04-26T23:57:00.000+10:00

For quite some time I have wanted to take a really good look at improving Boost.Asio's scalability across multiple processors. Unfortunately, getting unlimited access to this sort of hardware has been somewhat problematic. What I really needed was a decent multiprocessor box at home :)

The arrival of Intel's Clovertown quad core CPUs gave me the opportunity. The primary goal was to maximise parallelism while minimising the cost, and the lowest spec quad cores were cheap enough for me to justify spending the money. So, after months of thinking (and weeks of waiting for parts), last week I finally completed my home-built server.

Here are the headline specs:

Two Intel Xeon E5310 quad core processors (1.6 GHz)
Tyan Tempest i5000XL motherboard
2GB DDR2-667 fully buffered ECC DIMMs
OCZ GameXStream 700W power supply (OK, OK, it's a little overpowered, but it was in stock!)
Other stuff like case, hard disk, DVD drive, video card and wireless LAN card
Lots of fans to provide soothing ambient noise

So far I have installed CentOS Linux 5 on it, but also plan to try Solaris 10 and FreeBSD. It seems pretty snappy.

Unbuffered socket iostreams

2007-01-15T17:44:00.000+11:00

Boost.Asio includes an iostreams-based interface to TCP sockets, ip::tcp::iostream, for simple use cases. However, like the file iostreams provided by the standard library, ip::tcp::iostream buffers input and output data. This can lead to problems if you forget to explicitly flush the stream. For example, consider the following code to perform an HTTP request:

ip::tcp::iostream stream("www.boost.org", "http");
stream << "GET / HTTP/1.0\r\n"
       << "Host: www.boost.org\r\n"
       << "\r\n";

std::string response_line;
std::getline(stream, response_line);
...

The code will be stuck on the getline() call waiting for the response, because the request will still be sitting stream's output buffer. The correct code looks like this:

ip::tcp::iostream stream("www.boost.org", "http");
stream << "GET / HTTP/1.0\r\n"
       << "Host: www.boost.org\r\n"
       << "\r\n"
       << std::flush;

The std::flush will cause the stream to send the entire contents of its output buffer at that point.

Boost.Asio now supports an alternative solution: turn off the stream's output buffering. This is accomplished as follows:

ip::tcp::iostream stream("www.boost.org", "http");
stream.rdbuf()->pubsetbuf(0, 0);
stream << "GET / HTTP/1.0\r\n"
       << "Host: www.boost.org\r\n"
       << "\r\n";

Now you can send and receive to your heart's content, without having to worry about whether your message is stuck in the output buffer, but be warned: an unbuffered stream is a lot less efficient in terms of system calls. Don't use this feature if you care about performance.

Buffer debugging

2006-11-10T09:33:00.000+11:00

Some standard library implementations, such as the one that ships with MSVC 8.0, provide a nifty feature called iterator debugging. What this means is that the validity of your iterators is checked at runtime. If you try to use an iterator that has been invalidated, you'll get an assertion. For example:

std::vector<int> v(1)
std::vector<int>::iterator i = v.begin();
v.clear(); // invalidates iterators
*i = 0; // assertion!

Boost.Asio now takes advantage of this feature to add buffer debugging. Consider the following code:

void dont_do_this()
{
 std::string msg = "Hello, world!";
 asio::async_write(sock, asio::buffer(msg), my_handler);
}

When you call an asynchronous read or write you need to ensure that the buffers for the operation are valid until the completion handler is called. In the above example, the buffer is the std::string variable msg. This variable is on the stack, and so it goes out of scope before the asynchronous operation completes. If you're lucky, your application will crash. Often you will get random failures.

With the new buffer debug checking, however, Boost.Asio stores an iterator into the string until the asynchronous operation completes, and then dereferences it to check its validity. In the above example you get an assertion failure just before Boost.Asio tries to call the completion handler.

This feature has only been tested with MSVC 8.0 so far, but it should work with any other implementation that supports iterator debugging. Obviously there's a performance cost to this checking, so it's only enabled in debug builds. You can also explicitly disable it by defining BOOST_ASIO_DISABLE_BUFFER_DEBUGGING (or ASIO_DISABLE_BUFFER_DEBUGGING if you're using standalone asio).

FreeBSD support

2006-10-07T00:46:00.000+10:00

Asio has now been tested successfully on FreeBSD 6.0, and should support FreeBSD 5.5 and later. FreeBSD 5.4 and earlier are not supported since, according to the man pages, getaddrinfo is not thread-safe.

SSL password callbacks

2006-09-26T22:26:00.000+10:00

On the weekend I made some changes to asio to support password callbacks for SSL. There is a new function on the asio::ssl::context class called set_password_callback(), which takes a function object with the following signature:

std::string password_callback(
   std::size_t max_length,
   ssl::context::password_purpose purpose);

The callback must return the password as a string. The max_length argument indicates the maximum allowable length of the password, and if the returned string is longer it will be truncated. The context::password_purpose type is an enum with values for_reading and for_writing. In most cases you won't need to use the max_length or purpose arguments, and if you use boost::bind() to create the function object you can just leave them off. For example, the SSL server sample included with asio now has the following:

context_.set_password_callback(
    boost::bind(&server::get_password, this));

...

std::string get_password() const
{
  return "test";
}

The final thing to note is that the password callback needs to be set before calling any ssl::context functions that load keys, such as use_private_key_file().

What's this all about?

2006-09-26T13:00:00.000+10:00

Greetings, reader. I have a blog. Now what? Well, the plan is to post ideas, tips and tricks, design thoughts, and anything else related to C++, Boost.Asio and programming that happens to take my interest.

Thinking Asynchronously in C++

System error support in C++0x - part 5

Creating your own error conditions

Why create custom error conditions?

Step 1: define the error values

Step 2: define an error_category class

Step 3: give the category a human-readable name

Step 4: convert error conditions to strings

Step 5: implement error equivalence

Step 6: uniquely identify the category

Step 7: construct an error_condition from the enum

Step 8: register for implicit conversion to error_condition

Using the error conditions

System error support in C++0x - part 4

Creating your own error codes

Step 1: define the error values

Step 2: define an error_category class

Step 3: give the category a human-readable name

Step 4: convert error codes to strings

Step 5: uniquely identify the category

Step 6: construct an error_code from the enum

Step 7: register for implicit conversion to error_code

Step 8 (optional): assign default error conditions

Using the error codes

System error support in C++0x - part 3

Enumerators as class constants

It's not quite that simple

Step 1: determine whether the enum is an error code or condition

Step 2: associate the value with an error category

Explicit conversion to error_code or error_condition

Some history

System error support in C++0x - part 2

error_code vs error_condition

It's what you do with it that counts

Comparing error_codes and error_conditions

How to know what conditions you can test for

A bit of history

System error support in C++0x - part 1

Where to get it

Overview

Principles

Not all errors are exceptional

Errors come from multiple sources

Be user-extensible

Preserve the original error code

Bind illustrated

Timeouts by analogy

Parking meters

Using the analogy to inform program design

A potted guide to stackless coroutines

class coroutine

reenter

yield statement

yield return expression ;

yield ;

yield break ;

fork statement ;

Composed operations, coroutines and code makeover

Coroutines to the rescue

An alternative approach

Lambdas == code liposuction

Secret sauce revealed

Wife says: "I can't believe it works"

User-friendly compile errors for templates in C++0x

Asynchronous Fork/Join using Asio

And the result...

Why continuations?

Fibonacci revisited

Can I have C++0x lambdas now, please?

A useful example

Mention in Stroustrup Interview

Boost.Asio vs Asio

What are the differences in the source code?

Where do I get a release package?

Where are the source code repositories?

How do you maintain both versions?

Will Asio be discontinued now that Boost.Asio is included with Boost?

Should I use Asio or Boost.Asio?

Can Asio and Boost.Asio coexist in the same program?

739 days ago ...

Step 2: define an `error_category` class

Step 7: construct an `error_condition` from the `enum`

Step 8: register for implicit conversion to `error_condition`

Step 2: define an `error_category` class

Step 6: construct an `error_code` from the `enum`

Step 7: register for implicit conversion to `error_code`

Step 1: determine whether the `enum` is an error code or condition

Explicit conversion to `error_code` or `error_condition`

`error_code` vs `error_condition`

Comparing `error_code`s and `error_condition`s