boost::asio::coroutine 文档翻译 + 源码解析

文档地址

http://www.boost.org/doc/libs/1_60_0/doc/html/boost_asio/reference/coroutine.html

文档翻译

协程

提供实现不需要栈的协程的支持

class coroutine

成员函数

函数名	描述
coroutine	构造成为初始化状态
is_child	如果是一个fork子协程的话返回true
is_complete	如果到了终止状态就返回true
is_parent	如果是fork的父协程的话返回true

coroutine 类可以用来实现无栈的协程。这个类自身被用来保存协程的状态。
coroutine 类可以支持复制构造和赋值。最大一个int的空间占用。可以当作基类使用

class session : coroutine
{
 // 。。。
};

或者作为一个数据项。

class session
{
  //。。。
  coroutine coro_;
};

或者设置作为一个lambda或者bind（）的参数。 这种实现的重点是在协程存在的时候，这个对下必须不被释放。

伪关键字

协程是联合特定伪关键子使用的，这些伪关键字使用宏实现。这些宏被定义在

#include <boost/asio/yield.hpp>

可以通过下面的头文件方便的undefine

#include <boost/asio/unyield.hpp>

reenter

reenter宏是用来定义一段协程的。他仅仅接收1个参数 ： 一个coroutine的指针或者引用。比如 ， 如果基类是coroutine你可以这样写 ：

reenter (this)
{
  //coroutine body 
}

如果coroutine是成员变量的话

reenter (coro_)
{
  // coroutine body 
}

当一段reenter代码被执行的时候，直接跳转到最近的一次yeild或者fork位置后执行。
协程代码段也可以是一个单独的语句

reenter (this) for (;;)
{
  //。。。
}

局限性: 由于reenter宏是用swtich来实现的，所以你在协程代码中定义局部变量的时候必须格外注意。 这个变量不能定义在重入的时候会被跳过的地方。

yield 语句

这种格式的 yield 关键字通常被用来做异步操作 :

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

这个分成4步骤实现:

• yield 保存当前协程的状态.
• 初始化异步操作。
• 继续执行点被设置为下一行。
• 控制跳转到协程末尾，推出协程.。

当异步操作完成后，再次执行这个协程。重入后从继续执行点执行。记住，异步操作执行后再次调用协程是很重要的。

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

yield return expression ;

这种形式通常被用来做基于协程的解析器。比如 ：

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

定义了一个小协程来间隔的从两个流中读取数据，

这个分成3步骤实现

• yield 保存当前协程的状态.
• 继续执行点被设置为下一行。
• 函数返回表达式的值

yield ;

This form of yield is equivalent to the following steps:

这个分成3步骤实现

• yield 保存当前协程的状态.
• 继续执行点被设置为紧跟着分号。
• 控制函数到达代码末尾。
  这种格式在协程被用来组织线程的合作和调度的时候。比如 ：

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 ;

最后一种格式是用来显示的终止协程。分成两步骤：

• yeild将协程状态设置为终止。
• 控制函数到达代码末尾。

一旦协程终止。调用 is_complete()返回true 。 协程不能再被重入。
注意 ： 当协程代码块被显示终止的时候，比如return ， 抛出异常或者运行到结尾的时候，都会被设置为终止。

fork statement

fork伪关键字是用来使得一个协程分支的。它将一个协程分成两个（或者更多）复制。一个使用场景是在服务器，产生一个新的协程来处理每个客户端的链接。

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 
}

这个分4个步骤实现 ：

• fork 保存当前的协程状态.
• 创建一个协程的复制，要么立刻执行它，要么呆会。
• 回复点紧跟着分号之后.
• 对于父类，回复点在下一行。

函数is_parenet()和is_child()可以被用来区分父协程和自协程。你可以用他们来改变后面的工作顺序。
注意： fork 关键字并不真的实现分支。是程序来创建一个新的副本并调用它。你可以像上面那样立刻执行，也可以利用类似io_server::post() 这样的接口来延迟执行。

替代的宏

• BOOST_ASIO_CORO_REENTER instead of reenter
• BOOST_ASIO_CORO_YIELD instead ofyield
• BOOST_ASIO_CORO_FORK instead of fork

源码解析

来源 ：

boost/asio/coroutine.hpp

// 定义 coroutine 类， 本质上是一个行号记录类。
// 行号是这个东西冲入的唯一依据。
class coroutine
{
public:
  // 初始化0
  /// Constructs a coroutine in its initial state.
  coroutine() : value_(0) {}

  // fork 的子协程初始行号是当前行号的负数。因此判断它是否为负数。
  // 当子协程支持再fork后，value_变成新的行号，便不再被认为是child。 
  /// Returns true if the coroutine is the child of a fork.
  bool is_child() const { return value_ < 0; }
  // 返回 ！ is_child()
  /// Returns true if the coroutine is the parent of a fork.
  bool is_parent() const { return !is_child(); }

  // 当reenter宏包被的模块（里面应该有yeild或者fork ， 否则这个模块仅仅是普通的代码块，永远不存在结束状态）执行结束的时候，vaule_被设置为-1。
  /// Returns true if the coroutine has reached its terminal state.
  bool is_complete() const { return value_ == -1; }

private:
  friend class detail::coroutine_ref;
  int value_;
};


namespace detail {
// 引用类，使用这个类来方便的修改& 检测coroutine 类的值。
class coroutine_ref
{
public:
  coroutine_ref(coroutine& c) : value_(c.value_), modified_(false) {}
  coroutine_ref(coroutine* c) : value_(c->value_), modified_(false) {}
  ~coroutine_ref() { if (!modified_) value_ = -1; }
  operator int() const { return value_; }
  int& operator=(int v) { modified_ = true; return value_ = v; }
private:
  void operator=(const coroutine_ref&);
  int& value_;
  bool modified_;
};

} // namespace detail
} // namespace asio
} // namespace boost

#define BOOST_ASIO_CORO_REENTER(c) \
  switch (::boost::asio::detail::coroutine_ref _coro_value = c)\
    case -1: if (_coro_value) \
    { \
      goto terminate_coroutine; \
      terminate_coroutine: /*这是标记reenter模块结束的清理代码*/\
      _coro_value = -1; \
      goto bail_out_of_coroutine; /*退出这次执行*/\
      bail_out_of_coroutine: \
      break; \
    } \
    else case 0: /*下面是我们的代码块*/

#define BOOST_ASIO_CORO_YIELD_IMPL(n) \
  for (_coro_value = (n);;) \
    if (_coro_value == 0) \
    { \
      case (n): /*当reenter模块被重入的时候，根据行号直接跳转到这里从而直接执行下一行*/; \
      break; \
    } \
    else /*第一次执行到这里*/\
      switch (_coro_value ? 0 : 1) \
        for (;;)  \
          case -1: if (_coro_value)/*执行yeild break 终止 */ \
            goto terminate_coroutine; \
          else for (;;)/*执行yeild 而不是 yeild return 的话,循环 */\
            case 1: if (_coro_value) \
              goto bail_out_of_coroutine; \
            else case 0:

#define BOOST_ASIO_CORO_FORK_IMPL(n) \
  for (_coro_value = -(n);; _coro_value = (n))/*这个循环其实仅仅执行两次 ： core_calue == -n 执行子协程和 core_value == n 执行父协程*/ \
    if (_coro_value == (n)) \
    { \
      case -(n): ; \
      break; \
    } \
    else

#if defined(_MSC_VER)
# define BOOST_ASIO_CORO_YIELD BOOST_ASIO_CORO_YIELD_IMPL(__COUNTER__ + 1)
# define BOOST_ASIO_CORO_FORK BOOST_ASIO_CORO_FORK_IMPL(__COUNTER__ + 1)
#else // defined(_MSC_VER)
# define BOOST_ASIO_CORO_YIELD BOOST_ASIO_CORO_YIELD_IMPL(__LINE__)
# define BOOST_ASIO_CORO_FORK BOOST_ASIO_CORO_FORK_IMPL(__LINE__)
#endif // defined(_MSC_VER)

#endif // BOOST_ASIO_COROUTINE_HPP