譯者說

Tornado 4.3于2015年11月6日發布，該版本正式支持Python3.5的async/await關鍵字，并且用舊版本CPython編譯Tornado同樣可以使用這兩個關鍵字，這無疑是一種進步。其次，這是最后一個支持Python2.6和Python3.2的版本了，在后續的版本了會移除對它們的兼容。現在網絡上還沒有Tornado4.3的中文文檔，所以為了讓更多的朋友能接觸并學習到它，我開始了這個翻譯項目，希望感興趣的小伙伴可以一起參與翻譯，項目地址是tornado-zh on Github，翻譯好的文檔在Read the Docs上直接可以看到。歡迎Issues or PR。

協程

Tornado中推薦使用協程寫異步代碼. 協程使用了Python的yield關鍵字代替鏈式回調來將程序掛起和恢復執行(像在 gevent中出現的輕量級線程合作方式有時也被稱為協程,但是在Tornado中所有的協程使用明確的上下文切換,并被稱為異步函數).

使用協程幾乎像寫同步代碼一樣簡單, 并且不需要浪費額外的線程. 它們還通過減少上下文切換來 使并發編程更簡單.

例子:

    from tornado import gen

    @gen.coroutine
    def fetch_coroutine(url):
        http_client = AsyncHTTPClient()
        response = yield http_client.fetch(url)
        # 在Python 3.3之前, 在generator中是不允許有返回值的
        # 必須通過拋出異常來代替.
        # 就像 raise gen.Return(response.body).
        return response.body

Python 3.5:async和await

Python 3.5 引入了async和await關鍵字(使用這些關鍵字的函數也被稱為"原生協程"). 從Tornado 4.3,你可以用它們代替yield為基礎的協程.只需要簡單的使用async def foo()在函數定義的時候代替@gen.coroutine裝飾器, 用await代替yield. 本文檔的其他部分會繼續使用yield的風格來和舊版本的Python兼容, 但是如果async和await可用的話，它們運行起來會更快:

    async def fetch_coroutine(url):
        http_client = AsyncHTTPClient()
        response = await http_client.fetch(url)
        return response.body

await 關鍵字比 yield 關鍵字功能要少一些.例如,在一個使用 yield 的協程中， 你可以得到Futures 列表, 但是在原生協程中,你必須把列表用 tornado.gen.multi 包起來. 你也可以使用 tornado.gen.convert_yielded來把任何使用yield工作的代碼轉換成使用await的形式.

雖然原生協程沒有明顯依賴于特定框架(例如它們沒有使用裝飾器,例如tornado.gen.coroutine或asyncio.coroutine), 不是所有的協程都和其他的兼容. 有一個coroutine runner在第一個協程被調用的時候進行選擇, 然后被所有用await直接調用的協程共享. Tornado的協程執行者(coroutine runner)在設計上是多用途的,可以接受任何來自其他框架的awaitable對象;其他的協程運行時可能有很多限制(例如,asyncio協程執行者不接受來自其他框架的協程).基于這些原因,我們推薦組合了多個框架的應用都使用Tornado的協程執行者來進行協程調度.為了能使用Tornado來調度執行asyncio的協程, 可以使用tornado.platform.asyncio.to_asyncio_future適配器.

它是如何工作的

包含了yield關鍵字的函數是一個生成器(generator). 所有的生成器都是異步的; 當調用它們的時候,會返回一個生成器對象,而不是一個執行完的結果.@gen.coroutine裝飾器通過yield表達式和生成器進行交流, 而且通過返回一個.Future與協程的調用方進行交互.

下面是一個協程裝飾器內部循環的簡單版本:

    # tornado.gen.Runner 簡化的內部循環
    def run(self):
        # send(x) makes the current yield return x.
        # It returns when the next yield is reached
        future = self.gen.send(self.next)
        def callback(f):
            self.next = f.result()
            self.run()
        future.add_done_callback(callback)

裝飾器從生成器接收一個.Future對象, 等待(非阻塞的)這個.Future對象執行完成, 然后"解開(unwraps)"這個.Future對象，并把結果作為yield 表達式的結果傳回給生成器.大多數異步代碼從來不會直接接觸.Future類.除非 .Future立即通過異步函數返回給yield表達式.

如何調用協程

協程一般不會拋出異常: 它們拋出的任何異常將被.Future捕獲直到它被得到.這意味著用正確的方式調用協程是重要的, 否則你可能有被忽略的錯誤:

    @gen.coroutine
    def divide(x, y):
        return x / y

    def bad_call():
        # 這里應該拋出一個 ZeroDivisionError 的異常, 但事實上并沒有
        # 因為協程的調用方式是錯誤的.
        divide(1, 0)

幾乎所有的情況下, 任何一個調用協程的函數都必須是協程它自身, 并且在調用的時候使用yield關鍵字. 當你復寫超類中的方法, 請參閱文檔,看看協程是否支持(文檔應該會寫該方法 "可能是一個協程" 或者 "可能返回一個 .Future "):

    @gen.coroutine
    def good_call():
        # yield 將會解開 divide() 返回的 Future 并且拋出異常
        yield divide(1, 0)

有時你可能想要對一個協程"一勞永逸"而且不等待它的結果. 在這種情況下,建議使用.IOLoop.spawn_callback, 它使得.IOLoop 負責調用. 如果它失敗了, .IOLoop會在日志中把調用棧記錄下來:

    # IOLoop 將會捕獲異常,并且在日志中打印棧記錄.
    # 注意這不像是一個正常的調用, 因為我們是通過
    # IOLoop 調用的這個函數.
    IOLoop.current().spawn_callback(divide, 1, 0)

最后, 在程序頂層, 如果.IOLoop尚未運行, 你可以啟動.IOLoop,執行協程,然后使用.IOLoop.run_sync方法停止.IOLoop. 這通常被用來啟動面向批處理程序的main函數:

    # run_sync() 不接收參數,所以我們必須把調用包在lambda函數中.
    IOLoop.current().run_sync(lambda: divide(1, 0))

協程模式

結合 callback

為了使用回調代替.Future與異步代碼進行交互, 把調用包在.Task類中. 這將為你添加一個回調參數并且返回一個可以yield的.Future :

    @gen.coroutine
    def call_task():
        # 注意這里沒有傳進來some_function.
        # 這里會被Task翻譯成
        #   some_function(other_args, callback=callback)
        yield gen.Task(some_function, other_args)

調用阻塞函數

從協程調用阻塞函數最簡單的方式是使用concurrent.futures.ThreadPoolExecutor, 它將返回和協程兼容的Futures:

    thread_pool = ThreadPoolExecutor(4)

    @gen.coroutine
    def call_blocking():
        yield thread_pool.submit(blocking_func, args)

并行

協程裝飾器能識別列表或者字典對象中各自的 Futures, 并且并行的等待這些 Futures :

    @gen.coroutine
    def parallel_fetch(url1, url2):
        resp1, resp2 = yield [http_client.fetch(url1),
                              http_client.fetch(url2)]

    @gen.coroutine
    def parallel_fetch_many(urls):
        responses = yield [http_client.fetch(url) for url in urls]
        # 響應是和HTTPResponses相同順序的列表

    @gen.coroutine
    def parallel_fetch_dict(urls):
        responses = yield {url: http_client.fetch(url)
                            for url in urls}
        # 響應是一個字典 {url: HTTPResponse}

交叉存取

有時候保存一個 .Future 比立即yield它更有用, 所以你可以在等待之前
執行其他操作:

    @gen.coroutine
    def get(self):
        fetch_future = self.fetch_next_chunk()
        while True:
            chunk = yield fetch_future
            if chunk is None: break
            self.write(chunk)
            fetch_future = self.fetch_next_chunk()
            yield self.flush()

循環

協程的循環是棘手的, 因為在Python中沒有辦法在for循環或者while循環yield迭代器,并且捕獲yield的結果. 相反,你需要將循環條件從訪問結果中分離出來, 下面是一個使用Motor的例子:

    import motor
    db = motor.MotorClient().test

    @gen.coroutine
    def loop_example(collection):
        cursor = db.collection.find()
        while (yield cursor.fetch_next):
            doc = cursor.next_object()

在后臺運行

PeriodicCallback 通常不使用協程. 相反,一個協程可以包含一個while True:循環并使用tornado.gen.sleep:

    @gen.coroutine
    def minute_loop():
        while True:
            yield do_something()
            yield gen.sleep(60)

    # Coroutines that loop forever are generally started with
    # spawn_callback().
    IOLoop.current().spawn_callback(minute_loop)

有時可能會遇到一個更復雜的循環. 例如, 上一個循環運行每次花費60+N秒,其中N是do_something()花費的時間. 為了準確的每60秒運行,使用上面的交叉模式:

    @gen.coroutine
    def minute_loop2():
        while True:
            nxt = gen.sleep(60)   # 開始計時.
            yield do_something()  # 計時后運行.
            yield nxt             # 等待計時結束.