Futures
Future对象用来衔接低级的基于回调函数的代码和高级的async/await代码。
Future函数
asyncio.isfuture(obj)
如果obj是下列情况之一返回True：
- 一个asyncio.Future实例
- 一个asyncio.Task实例
- 一个拥有_asyncio_future_blocking属性的类Future对象(python3.5加入的)
asyncio.ensure_future(obj, *, loop=None)
返回：
- 如果obj是Future、Task、类Future对象，返回obj
- 如果obj是一个corotine对象，返回一个Task包装的对象
- 如果obj是一个可等待对象，返回一个等待obj的Task对象
如果obj不是上述的对象，会引发TypeError异常。
重要：参考create_task()函数，一个更好的创建Task的方式。
python3.5.5：此函数接受任何awaitable对象。
Future对象
class asyncio.Future(*, loop=None)
一个Future对象表示一个异步操作的结果。不是线程安全的。
Future是一个awaitable对象。协程能等待Future对象直到他们得到一个结果或者抛出一个异常，再或者他们被取消。
典型的，Future被用于基于低级的回调函数代码和高级的async/await代码交互。（例如，使用asyncio transports实现的协议）。
首要规则是，不要在面向用户的API中揭露Future对象，推荐的方式是创建一个Future对象来调用loop.create_future()。这是一种可供选择的和事件循环(event loop)交互的方式，来实现优化他们自己的Future对象。
在3.7中修改：添加支持contextvars模块。
result()
返回Future对象的结果。
如果Future完成并通过set_result()函数产出一个结果，此时结果就被返回了。
如果Future完成并通过set_exceptions()函数返回一个异常，此时方法就会抛出一个异常。
如果Future被取消了，此方法会引发一个CancelledError异常。
如果Future还没有完成，此方法会引发一个InvalidStateError异常。
set_result(result)
标记Future已经完成并设置它的结果。
如果Future已经完成则会抛出一个InvalidStateError异常。
set_exception(exeption)
标记Future已经完成并设置一个异常。
如果Futre已经完成则会抛出一个InvalidStateError。
done()
如果Future完成，则返回True。
如果Future被取消或者通过调用set_result()得到了一个结果，再或者调用set_exception()设置了一个异常时，都会被认为Future已经完成。
cancelled()
如果Future被取消则返回True。
此方法经常被用于检查Future在被设置结果或者异常之前是否被取消。
if not fut.cancelled():
fut.set_result(42)
add_done_callback(callback, *, context=None)
当Future完成时，添加一个回调函数来运行。
回调函数和Future对象作为仅有的参数被调用。
如果当方法被调用时Future已经完成，回调函数被安排和loop.call_soon()一起。
一个可选的，唯一的context参数允许指定一个自定义的contextvars.Context用于运行回调函数。当没有上下文被提供时，使用当前上下文。
functools.partial()被用于给回调函数传递参数，比如:
# Call 'print("Future:", fut)' when "fut" is done.
fut.add_done_callback(
functools.partial(print, "Future:"))
在python3.7中被修改：context关键字参数被添加。详情可以参照PEP 567。
remove_done_callback(callback)
从回调函数列表中删除回调函数。
返回被删除的回调函数的数量，一般都是1，除非一个回调函数被添加了多次。
cancel()
取消Future，并安排回调函数。
如果Future已经完成或者被取消了，返回False。否则，把Future的状态改为cancelled，安排回调函数并返回True。
exception()
返回设置在这个Future上的异常。
只有在Future完成时被返回(如果异常没有被设置，返回None)。
如果Future被取消了，这个方法抛出CancelledError异常。
如果Futre还未完成，这个方法抛出InvalidStateError异常。
get_loop()
返回Future绑定了的事件循环。(3.7中加入)
这个例子创建了一个Future对象，创建并安排了一个异步任务来给Future设置结果，等待直到Future有结果：
async def set_after(fut, delay, value):
# Sleep for *delay* seconds.
await asyncio.sleep(delay)
# Set *value* as a result of *fut* Future.
fut.set_result(value)
async def main():
# Get the current event loop.
loop = asyncio.get_running_loop()
# Create a new Future object.
fut = loop.create_future()
# Run "set_after()" coroutine in a parallel Task.
# We are using the low-level "loop.create_task()" API here because
# we already have a reference to the event loop at hand.
# Otherwise we could have just used "asyncio.create_task()".
loop.create_task(
set_after(fut, 1, '... world'))
print('hello ...')
# Wait until *fut* has a result (1 second) and print it.
print(await fut)
asyncio.run(main())
重要：Future对象被设计用来模仿concurrent.futures.Future。
关键的不同包括下面几点：
- 和asyncio Future不同，concurrent.futures.Future实例不可被阻塞(await)。
- asyncio.Future.result()和asnycio.Future.exception()不接受timeout参数。
- asyncio.Future.result()和asnycio.Future.exception()当Future还未完成时抛出一个InvalidStateError异常。
- 回调函数被asyncio.Future.add_done_callback()注册，没有被立即调用，而是被放在了loop.call_soon()中。
- asyncio Future与concurrent.futures.wait()、concurrent.futures.as_completed()不兼容。
网友评论