16-coroutine.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# 协程\n",
    "> 如果 Python 书籍有一定的指导作用，那么（协程就是）文档最匮乏、最鲜为人知的 Python 特性，因此表面上看是最无用的特性。\n",
    "> ——David Beazley, Python 图书作者\n",
    "\n",
    "在“生成器”章节中我们认识了 `yield` 语句。但 `yield` 的作用不只是在生成器运行过程中**返回**一个值，还可以从调用方拿回来一个值（`.send(datum)`），甚至一个异常（`.throw(exc)`）。  \n",
    "由此依赖，`yield` 语句就成为了一种流程控制工具，使用它可以实现协作式多任务：协程可以把控制器让步给中心调度程序，从而激活其它的协程。\n",
    "\n",
    "从根本上把 yield 视作控制流程的方式，这样就好理解协程了。\n",
    "\n",
    "本章涵盖以下话题：\n",
    "* 生成器作为协程使用时的行为和状态\n",
    "* 使用装饰器自动预激协程\n",
    "* 调用方如何使用生成器对象的 `.close()` 和 `.throw(...)` 方法控制协程\n",
    "* 协程终止时如何返回值\n",
    "* `yield from` 新句法的用途和语义\n",
    "* 使用案例——使用协程管理仿真系统中的并发活动"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "协程的四种状态：\n",
    "* `GEN_CREATED`: 等待开始执行\n",
    "* `GEN_RUNNING`: 解释器正在执行\n",
    "* `GEN_SUSPENDED`: 在 `yield` 表达式处暂停\n",
    "* `GEN_CLOSED`: 执行结束"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# 最简单的协程使用演示\n",
    "from inspect import getgeneratorstate\n",
    "\n",
    "def simple_coroutine():\n",
    "    # GEN_RUNNING 状态\n",
    "    print(\"Coroutine started\")\n",
    "    x = yield\n",
    "    print(\"Couroutine received:\", x)\n",
    "\n",
    "my_coro = simple_coroutine()\n",
    "print(getgeneratorstate(my_coro)) # GEN_CREATED\n",
    "next(my_coro)                     # “预激”(prime)协程，使它能够接收来自外部的值\n",
    "print(getgeneratorstate(my_coro)) # GEN_SUSPENDED\n",
    "try:\n",
    "    my_coro.send(42)\n",
    "except StopIteration as e:\n",
    "    print('StopIteration')\n",
    "print(getgeneratorstate(my_coro)) # GEN_CLOSED"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "1 1\n",
      "2 3\n",
      "3 6\n",
      "4 10\n",
      "5 15\n",
      "6 21\n",
      "7 28\n",
      "8 36\n",
      "9 45\n",
      "10 55\n"
     ]
    },
    {
     "ename": "StopIteration",
     "evalue": "",
     "output_type": "error",
     "traceback": [
      "\u001b[1;31m---------------------------------------------------------------------------\u001b[0m",
      "\u001b[1;31mStopIteration\u001b[0m                             Traceback (most recent call last)",
      "\u001b[1;32m<ipython-input-13-0daab1220103>\u001b[0m in \u001b[0;36m<module>\u001b[1;34m()\u001b[0m\n\u001b[0;32m     11\u001b[0m     \u001b[0mprint\u001b[0m\u001b[1;33m(\u001b[0m\u001b[0mi\u001b[0m\u001b[1;33m,\u001b[0m \u001b[0masum\u001b[0m\u001b[1;33m.\u001b[0m\u001b[0msend\u001b[0m\u001b[1;33m(\u001b[0m\u001b[0mi\u001b[0m\u001b[1;33m)\u001b[0m\u001b[1;33m)\u001b[0m\u001b[1;33m\u001b[0m\u001b[0m\n\u001b[0;32m     12\u001b[0m \u001b[0masum\u001b[0m\u001b[1;33m.\u001b[0m\u001b[0mclose\u001b[0m\u001b[1;33m(\u001b[0m\u001b[1;33m)\u001b[0m                 \u001b[1;31m# 如果协程不会自己关闭，我们还可以手动终止协程\u001b[0m\u001b[1;33m\u001b[0m\u001b[0m\n\u001b[1;32m---> 13\u001b[1;33m \u001b[0masum\u001b[0m\u001b[1;33m.\u001b[0m\u001b[0msend\u001b[0m\u001b[1;33m(\u001b[0m\u001b[1;36m11\u001b[0m\u001b[1;33m)\u001b[0m\u001b[1;33m\u001b[0m\u001b[0m\n\u001b[0m",
      "\u001b[1;31mStopIteration\u001b[0m: "
     ]
    }
   ],
   "source": [
    "# 产出多个值的协程\n",
    "def async_sum(a=0):\n",
    "    s = a\n",
    "    while True:\n",
    "        n = yield s\n",
    "        s += n\n",
    "\n",
    "asum = async_sum()\n",
    "next(asum)\n",
    "for i in range(1, 11):\n",
    "    print(i, asum.send(i))\n",
    "asum.close()                 # 如果协程不会自己关闭，我们还可以手动终止协程\n",
    "asum.send(11)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "协程手动终止的注意事项：  \n",
    "调用 `gen.closed()` 后，生成器内的 `yield` 语句会抛出 `GeneratorExit` 异常。如果生成器没有处理这个异常，或者抛出了 `StopIteration` 异常（通常是指运行到结尾），调用方不会报错。  \n",
    "如果收到 `GeneratorExit` 异常，生成器一定不能产出值，否则解释器会抛出 `RuntimeError` 异常。生成器抛出的其他异常会向上冒泡，传给调用方。\n",
    "\n",
    "协程内异常处理的示例见[官方示例 Repo](https://github.com/fluentpython/example-code/blob/master/16-coroutine/coro_finally_demo.py)。\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## yield from\n",
    "在协程中，`yield from` 语句的主要功能是打开双向通道，把外层的调用方与内层的子生成器连接起来，这样二者可以直接发送和产出值，还可以直接传入异常，而不用在位于中间的协程中添加大量处理异常的样板代码。  \n",
    "这种夹在中间的生成器，我们称它为“委派生成器”。\n",
    "\n",
    "子生成器迭代结束后返回（`return`）的值，会交给 `yield from` 函数。\n",
    "\n",
    "注意：`yield from` 语句会预激生成器，所以与用来预激生成器的装饰器不能放在一起用，否则会出问题。"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "1\n",
      "3\n",
      "6\n",
      "10\n",
      "15\n",
      "21\n",
      "28\n",
      "36\n",
      "45\n",
      "55\n",
      "Caught exception \n",
      "Final result: 55\n"
     ]
    },
    {
     "ename": "StopIteration",
     "evalue": "",
     "output_type": "error",
     "traceback": [
      "\u001b[1;31m---------------------------------------------------------------------------\u001b[0m",
      "\u001b[1;31mStopIteration\u001b[0m                             Traceback (most recent call last)",
      "\u001b[1;32m<ipython-input-16-27762d9b83ae>\u001b[0m in \u001b[0;36m<module>\u001b[1;34m()\u001b[0m\n\u001b[0;32m     19\u001b[0m     \u001b[0mprint\u001b[0m\u001b[1;33m(\u001b[0m\u001b[0masum\u001b[0m\u001b[1;33m.\u001b[0m\u001b[0msend\u001b[0m\u001b[1;33m(\u001b[0m\u001b[0mi\u001b[0m\u001b[1;33m)\u001b[0m\u001b[1;33m)\u001b[0m\u001b[1;33m\u001b[0m\u001b[0m\n\u001b[0;32m     20\u001b[0m \u001b[1;33m\u001b[0m\u001b[0m\n\u001b[1;32m---> 21\u001b[1;33m \u001b[0m_\u001b[0m \u001b[1;33m=\u001b[0m \u001b[0masum\u001b[0m\u001b[1;33m.\u001b[0m\u001b[0mthrow\u001b[0m\u001b[1;33m(\u001b[0m\u001b[0mValueError\u001b[0m\u001b[1;33m)\u001b[0m\u001b[1;33m\u001b[0m\u001b[0m\n\u001b[0m",
      "\u001b[1;31mStopIteration\u001b[0m: "
     ]
    }
   ],
   "source": [
    "# 委派生成器\n",
    "def async_sum(a=0):\n",
    "    s = a\n",
    "    while True:\n",
    "        try:\n",
    "            n = yield s\n",
    "        except Exception as e:\n",
    "            print('Caught exception', e)\n",
    "            return s\n",
    "        s += n\n",
    "\n",
    "def middleware():\n",
    "    x = yield from async_sum()\n",
    "    print('Final result:', x)\n",
    "        \n",
    "asum = middleware()\n",
    "next(asum)\n",
    "for i in range(1, 11):\n",
    "    print(asum.send(i))\n",
    "\n",
    "_ = asum.throw(ValueError)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "关于“任务式”协程，书中给出了一个[简单的例子](https://github.com/fluentpython/example-code/blob/master/16-coroutine/taxi_sim.py)，用于执行[离散事件仿真](https://zhuanlan.zhihu.com/p/22689081)，仔细研究一下可以对协程有个简单的认识。"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.7.0"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}