Composed operations, coroutines and code makeover

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.