18.5.3. 任务和协程 ¶

18.5.3.1. 协程 ¶

A coroutine is a generator that follows certain conventions. For documentation purposes, all coroutines should be decorated with @asyncio.coroutine , but this cannot be strictly enforced.

Coroutines use the yield from syntax introduced in PEP 380 , instead of the original yield 句法。

The word “coroutine”, like the word “generator”, is used for two different (though related) concepts:

The function that defines a coroutine (a function definition decorated with @asyncio.coroutine ). If disambiguation is needed we will call this a 协程函数 ( iscoroutinefunction() 返回 True ).
The object obtained by calling a coroutine function. This object represents a computation or an I/O operation (usually a combination) that will complete eventually. If disambiguation is needed we will call it a 协程对象 ( iscoroutine() 返回 True ).

Things a coroutine can do:

result = yield from future – suspends the coroutine until the future is done, then returns the future’s result, or raises an exception, which will be propagated. (If the future is cancelled, it will raise a CancelledError exception.) Note that tasks are futures, and everything said about futures also applies to tasks.
result = yield from coroutine – wait for another coroutine to produce a result (or raise an exception, which will be propagated). The coroutine expression must be a call to another coroutine.
return expression – produce a result to the coroutine that is waiting for this one using yield from .
raise exception – raise an exception in the coroutine that is waiting for this one using yield from .

Calling a coroutine does not start its code running – it is just a generator, and the coroutine object returned by the call is really a generator object, which doesn’t do anything until you iterate over it. In the case of a coroutine object, there are two basic ways to start it running: call yield from coroutine from another coroutine (assuming the other coroutine is already running!), or schedule its execution using the async() function or the BaseEventLoop.create_task() 方法。

Coroutines (and tasks) can only run when the event loop is running.

@ asyncio. 协程 ¶

注意

In this documentation, some methods are documented as coroutines, even if they are plain Python functions returning a Future . This is intentional to have a freedom of tweaking the implementation of these functions in the future. If such a function is needed to be used in a callback-style code, wrap its result with async() .

18.5.3.1.1. Example: Hello World coroutine ¶

Example of coroutine displaying "Hello World" :

import asyncio
@asyncio.coroutine
def hello_world():
    print("Hello World!")
loop = asyncio.get_event_loop()
# Blocking call which returns when the hello_world() coroutine is done
loop.run_until_complete(hello_world())
loop.close()

另请参阅

The Hello World 采用 call_soon() 范例使用 BaseEventLoop.call_soon() method to schedule a callback.

18.5.3.1.2. Example: Coroutine displaying the current date ¶

Example of coroutine displaying the current date every second during 5 seconds using the sleep() 函数：

import asyncio
import datetime
@asyncio.coroutine
def display_date(loop):
    end_time = loop.time() + 5.0
    while True:
        print(datetime.datetime.now())
        if (loop.time() + 1.0) >= end_time:
            break
        yield from asyncio.sleep(1)
loop = asyncio.get_event_loop()
# Blocking call which returns when the display_date() coroutine is done
loop.run_until_complete(display_date(loop))
loop.close()

另请参阅

The display the current date with call_later() example uses a callback with the BaseEventLoop.call_later() 方法。

18.5.3.1.3. Example: Chain coroutines ¶

Example chaining coroutines:

import asyncio
@asyncio.coroutine
def compute(x, y):
    print("Compute %s + %s ..." % (x, y))
    yield from asyncio.sleep(1.0)
    return x + y
@asyncio.coroutine
def print_sum(x, y):
    result = yield from compute(x, y)
    print("%s + %s = %s" % (x, y, result))
loop = asyncio.get_event_loop()
loop.run_until_complete(print_sum(1, 2))
loop.close()

compute() is chained to print_sum() : print_sum() coroutine waits until compute() is completed before returning its result.

Sequence diagram of the example:

The “Task” is created by the BaseEventLoop.run_until_complete() method when it gets a coroutine object instead of a task.

The diagram shows the control flow, it does not describe exactly how things work internally. For example, the sleep coroutine creates an internal future which uses BaseEventLoop.call_later() to wake up the task in 1 second.

18.5.3.2. InvalidStateError ¶

exception asyncio. InvalidStateError ¶

18.5.3.3. TimeoutError ¶

exception asyncio. TimeoutError ¶

注意

This exception is different from the builtin TimeoutError exception!

18.5.3.4. Future ¶

class asyncio. Future ( * , loop=None ) ¶

cancel ( ) ¶

cancelled ( ) ¶

done ( ) ¶

result ( ) ¶

exception ( ) ¶

add_done_callback ( fn ) ¶

remove_done_callback ( fn ) ¶

set_result ( result ) ¶

set_exception ( exception ) ¶

18.5.3.4.1. Example: Future with run_until_complete() ¶

Example combining a Future 和协程函数 :

import asyncio
@asyncio.coroutine
def slow_operation(future):
    yield from asyncio.sleep(1)
    future.set_result('Future is done!')
loop = asyncio.get_event_loop()
future = asyncio.Future()
asyncio.ensure_future(slow_operation(future))
loop.run_until_complete(future)
print(future.result())
loop.close()

The coroutine function is responsible for the computation (which takes 1 second) and it stores the result into the future. The run_until_complete() method waits for the completion of the future.

注意

The run_until_complete() method uses internally the add_done_callback() method to be notified when the future is done.

18.5.3.4.2. Example: Future with run_forever() ¶

The previous example can be written differently using the Future.add_done_callback() method to describe explicitly the control flow:

import asyncio
@asyncio.coroutine
def slow_operation(future):
    yield from asyncio.sleep(1)
    future.set_result('Future is done!')
def got_result(future):
    print(future.result())
    loop.stop()
loop = asyncio.get_event_loop()
future = asyncio.Future()
asyncio.ensure_future(slow_operation(future))
future.add_done_callback(got_result)
try:
    loop.run_forever()
finally:
    loop.close()

In this example, the future is used to link slow_operation() to got_result() : when slow_operation() is done, got_result() is called with the result.

18.5.3.5. 任务 ¶

class asyncio. Task ( coro , * , loop=None ) ¶

18.5.3.5.1. Example: Parallel execution of tasks ¶

Example executing 3 tasks (A, B, C) in parallel:

import asyncio
@asyncio.coroutine
def factorial(name, number):
    f = 1
    for i in range(2, number+1):
        print("Task %s: Compute factorial(%s)..." % (name, i))
        yield from asyncio.sleep(1)
        f *= i
    print("Task %s: factorial(%s) = %s" % (name, number, f))
loop = asyncio.get_event_loop()
tasks = [
    asyncio.ensure_future(factorial("A", 2)),
    asyncio.ensure_future(factorial("B", 3)),
    asyncio.ensure_future(factorial("C", 4))]
loop.run_until_complete(asyncio.wait(tasks))
loop.close()

输出：

Task A: Compute factorial(2)...
Task B: Compute factorial(2)...
Task C: Compute factorial(2)...
Task A: factorial(2) = 2
Task B: Compute factorial(3)...
Task C: Compute factorial(3)...
Task B: factorial(3) = 6
Task C: Compute factorial(4)...
Task C: factorial(4) = 24

A task is automatically scheduled for execution when it is created. The event loop stops when all tasks are done.

18.5.3.6. 任务函数 ¶

注意

In the functions below, the optional loop argument allows to explicitly set the event loop object used by the underlying task or coroutine. If it’s not provided, the default event loop is used.

asyncio. as_completed ( fs , * , loop=None , timeout=None ) ¶

asyncio. ensure_future ( coro_or_future , * , loop=None ) ¶

asyncio. async ( coro_or_future , * , loop=None ) ¶

asyncio. gather ( *coros_or_futures , loop=None , return_exceptions=False ) ¶

asyncio. iscoroutine ( obj ) ¶

asyncio. iscoroutinefunction ( obj ) ¶

协程 asyncio. sleep ( delay , result=None , * , loop=None ) ¶

asyncio. shield ( arg , * , loop=None ) ¶

协程 asyncio. wait ( futures , * , loop=None , timeout=None , return_when=ALL_COMPLETED ) ¶

常量	描述
`FIRST_COMPLETED`	The function will return when any future finishes or is cancelled.
`FIRST_EXCEPTION`	The function will return when any future finishes by raising an exception. If no future raises an exception then it is equivalent to `ALL_COMPLETED` .
`ALL_COMPLETED`	The function will return when all futures finish or are cancelled.

协程 asyncio. wait_for ( fut , timeout , * , loop=None ) ¶

asyncio. run_coroutine_threadsafe ( coro , loop ) ¶