在异步程序中,一个操作开始时,结果往往还没有准备好。例如,网络库已经发出了请求,但响应要稍后才能到达;某个底层回调已经注册,但回调什么时候触发还不确定。
等待方需要一个可以表达「结果将来会出现」的对象,这就是 asyncio.Future。
asyncio.Future
Future 本身不会执行网络请求,也不会启动一段协程。它只是保存一个尚未产生的结果,并在结果准备好时通知等待者。可以把参与者分成两端:
await
01import asyncio 02 03async def produce(future): 04 await asyncio.sleep(1) 05 06 if not future.cancelled(): 07 future.set_result("数据已经准备好") 08 09async def consume(future): 10 print("等待结果") 11 result = await future 12 print(result) 13 14async def main(): 15 loop = asyncio.get_running_loop() 16 future = loop.create_future() 17 18 producer = asyncio.create_task(produce(future)) 19 await consume(future) 20 await producer 21 22asyncio.run(main())
代码运行到 await future 时,如果 Future 尚未完成,当前的 consume Task 会暂停,并把执行机会交还给事件循环。事件循环继续推进 produce Task。生产者调用 set_result() 后,Future 进入完成状态,事件循环随后恢复等待它的 Task。
await future
consume
produce
set_result()
注意,set_result() 的职责是完成 Future,而不是在这一行直接跳进 consume() 继续执行。等待者由事件循环安排在后续调度机会中恢复。
consume()
Future 与前面学过的两个对象各自负责不同的事情:
因此,不能把 Future 理解成一个「还没开始的任务」。它更像 Task 或底层异步操作正在等待的结果凭证。
在协程中创建 Future 时,推荐先取得当前事件循环,再调用 loop.create_future():
loop.create_future()
1import asyncio 2 3async def main(): 4 loop = asyncio.get_running_loop() 5 future = loop.create_future() 6 7 print(future.done()) # False 8 9asyncio.run(main())
虽然也能直接调用 asyncio.Future(),但 loop.create_future() 会明确地把 Future 绑定到当前事件循环,也允许第三方事件循环提供与自身适配的实现。因此,编写异步库和底层适配代码时应优先使用这种方式。
asyncio.Future()
刚创建的 Future 处于未完成状态。创建它不会自动安排任何工作,如果没有其他代码负责完成它,下面的程序会一直等待:
01import asyncio 02 03async def main(): 04 loop = asyncio.get_running_loop() 05 future = loop.create_future() 06 07 # 没有任何生产者调用 set_result()、set_exception() 或 cancel() 08 # await future # 将一直等待 09 10asyncio.run(main())
这也解释了为什么普通业务代码很少需要手动创建 Future:Future 通常由网络库、驱动程序、事件循环适配层创建,业务代码只负责等待库返回的协程或 Task。
同一个 Future 可以被多个 Task 等待。Future 完成后,所有等待者都会取得同一个结果:
01import asyncio 02 03async def wait_result(name, future): 04 result = await future 05 print(f"{name} 收到:{result}") 06 07async def main(): 08 loop = asyncio.get_running_loop() 09 future = loop.create_future() 10 11 first = asyncio.create_task(wait_result("A", future)) 12 second = asyncio.create_task(wait_result("B", future)) 13 14 await asyncio.sleep(0.1) 15 future.set_result("完成") 16 17 await asyncio.gather(first, second) 18 19asyncio.run(main())
Future 完成后会保留结果,所以还可以再次 await 它,新的等待不会让生产者重新执行:
01import asyncio 02 03async def main(): 04 loop = asyncio.get_running_loop() 05 future = loop.create_future() 06 future.set_result("已缓存的结果") 07 08 print(await future) 09 print(await future) 10 11asyncio.run(main())
这和直接重复等待同一个协程对象不同。协程对象只能被完整执行一次,而完成后的 Future 可以反复读取同一个最终结果。
Future 创建后处于 pending,也就是未完成状态。之后只能走向三种终态之一:
pending
set_result(value)
value
set_exception(error)
cancel()
CancelledError
正常、异常和取消都属于「已经完成」,所以这三种情况下 done() 都返回 True。终态不能再切换到其他状态,一个 Future 只能被完成一次。
done()
True
01import asyncio 02 03async def main(): 04 loop = asyncio.get_running_loop() 05 future = loop.create_future() 06 07 print(future.done()) # False 08 print(future.cancelled()) # False 09 10 future.set_result("成功") 11 12 print(future.done()) # True 13 print(future.cancelled()) # False 14 print(future.result()) # 成功 15 16asyncio.run(main())
常用状态方法如下:
cancelled()
result()
exception()
None
get_loop()
如果 Future 还没有完成,直接调用 result() 或 exception() 会抛出 asyncio.InvalidStateError。在业务代码中,应优先使用 await future,因为 await 会在结果未准备好时暂停,而不是提前读取:
asyncio.InvalidStateError
01import asyncio 02 03async def main(): 04 loop = asyncio.get_running_loop() 05 future = loop.create_future() 06 07 # future.result() # InvalidStateError 08 09 loop.call_later(1, future.set_result, "完成") 10 result = await future 11 print(result) 12 13asyncio.run(main())
set_result() 和 set_exception() 也只能调用一次。如果 Future 已经完成或取消,再设置结果会抛出 InvalidStateError。生产者可能晚于取消请求返回结果时,应该先检查取消状态:
set_exception()
InvalidStateError
1def complete(future, value): 2 if not future.cancelled(): 3 future.set_result(value)
这项检查主要用于底层回调适配。普通业务代码不应到处用 done() 和 cancelled() 手写一套并发状态机。
生产者无法得到正常结果时,可以使用 set_exception() 完成 Future。等待者不需要检查某个特殊返回值,直接使用 try...except 处理异常:
try...except
01import asyncio 02 03async def main(): 04 loop = asyncio.get_running_loop() 05 future = loop.create_future() 06 07 future.set_exception(ValueError("响应格式错误")) 08 09 try: 10 await future 11 except ValueError as error: 12 print(error) 13 14asyncio.run(main())
如果不等待这个 Future,也没有调用 exception() 取走异常,事件循环可能在 Future 被回收时报告 Future exception was never retrieved。这通常说明程序启动了异步工作,却没有负责处理它的失败。
Future exception was never retrieved
调用 future.cancel() 会尝试把未完成的 Future 标记为取消。等待它的代码会收到 asyncio.CancelledError:
future.cancel()
asyncio.CancelledError
01import asyncio 02 03async def main(): 04 loop = asyncio.get_running_loop() 05 future = loop.create_future() 06 07 future.cancel("用户停止了等待") 08 09 try: 10 await future 11 except asyncio.CancelledError as error: 12 print(error) 13 14 print(future.done()) # True 15 print(future.cancelled()) # True 16 17asyncio.run(main())
如果 Future 已经正常或异常完成,cancel() 不会覆盖原来的结果,并返回 False。如果取消成功,则返回 True。
False
当一个 Task 正在等待 Future,而这个 Task 被取消时,取消通常也会传播到它正在等待的 Future。取消不是普通的失败结果,而是异步调用链停止工作的控制信号;处理 CancelledError 时,完成资源清理后通常应该继续抛出。
Future 除了可以被 await,还可以通过 add_done_callback() 注册完成回调。回调只接收一个参数,也就是已经完成的 Future:
add_done_callback()
01import asyncio 02 03def print_result(future): 04 if future.cancelled(): 05 print("Future 已取消") 06 return 07 08 error = future.exception() 09 if error is not None: 10 print(f"执行失败:{error}") 11 return 12 13 print(f"收到:{future.result()}") 14 15async def main(): 16 loop = asyncio.get_running_loop() 17 future = loop.create_future() 18 future.add_done_callback(print_result) 19 20 future.set_result("消息") 21 print("结果已经设置") 22 23 await asyncio.sleep(0) 24 25asyncio.run(main())
调用 set_result() 后,回调不会嵌套在这一行中立即执行,而是通过事件循环安排执行。即使注册回调时 Future 已经完成,回调也会被安排到后续调度机会。
对于普通业务流程,await 往往更直观。add_done_callback() 常见于底层库、监控逻辑和需要兼容回调接口的代码。
Future 最重要的用途之一,就是把旧式回调 API 转换成可等待的异步 API。假设一个旧函数通过回调返回错误或数据:
01import asyncio 02 03def legacy_request(loop, callback): 04 loop.call_later(1, callback, None, {"name": "小微"}) 05 06async def request(): 07 loop = asyncio.get_running_loop() 08 future = loop.create_future() 09 10 def on_complete(error, data): 11 if future.cancelled(): 12 return 13 14 if error is not None: 15 future.set_exception(error) 16 else: 17 future.set_result(data) 18 19 legacy_request(loop, on_complete) 20 return await future 21 22async def main(): 23 result = await request() 24 print(result) 25 26asyncio.run(main())
转换过程可以分成四步:
调用者看到的是普通的 await request(),不再需要理解底层什么时候调用回调。Future 正是在这里连接了「回调世界」和 async / await 世界。
await request()
async
Task 和 Future 都是可等待对象,都能保存最终结果、异常和取消状态,但它们的职责并不相同。
Task 是一种 Future 风格的对象,它在 Future 的状态能力之上增加了「推进协程」的职责。协程 return 的值会成为 Task 的结果,协程抛出的异常会成为 Task 的异常;调用者不能使用 set_result() 或 set_exception() 任意决定 Task 的结果。
return
01import asyncio 02 03async def fetch_user(): 04 await asyncio.sleep(0.1) 05 return {"name": "小微"} 06 07async def main(): 08 task = asyncio.create_task(fetch_user()) 09 10 print(asyncio.isfuture(task)) # True 11 print(await task) # {'name': '小微'} 12 print(task.result()) # {'name': '小微'} 13 14asyncio.run(main())
asyncio.isfuture(task) 返回 True,说明 Task 符合 Future 协议,可以像 Future 一样被等待和检查状态。但 Task 的结果来源于协程执行,普通 Future 的结果则由外部生产者设置。
asyncio.isfuture(task)
asyncio.create_task()
当 Task 执行到 await future 时,可以把过程理解为:
这条链路回答了一个关键问题:Task 被创建后并不是持续占用 CPU。它遇到尚未完成的 Future 时会暂停,事件循环可以去推进其他就绪 Task。
Future 是较底层的工具。编写普通 FastAPI 或 LangChain 业务时,通常应该返回协程的结果,而不是把裸 Future 暴露给调用者:
01import asyncio 02 03async def load_user(): 04 await asyncio.sleep(0.1) 05 return {"name": "小微"} 06 07async def main(): 08 user = await load_user() 09 print(user) 10 11asyncio.run(main())
这样,Future 的创建、完成和取消都留在实现底层。调用者只需要使用稳定的异步函数接口。官方文档也建议,不要在面向业务使用者的 API 中直接暴露 Future。
ensure_future()
asyncio.ensure_future() 能接收 Future、Task、协程或其他可等待对象,并保证返回一个 Future 风格的对象:
asyncio.ensure_future()
01import asyncio 02 03async def work(): 04 return "完成" 05 06async def main(): 07 task = asyncio.ensure_future(work()) 08 print(await task) 09 10asyncio.run(main())
如果参数本来就是 Future 或 Task,它会被直接返回;如果参数是协程,则会被包装成 Task 并安排执行。现代应用代码已经明确拿到协程时,通常优先使用语义更清楚的 asyncio.create_task();管理一组相关任务时,优先考虑 TaskGroup。
TaskGroup
线程边界
asyncio.Future 不是线程安全对象。Future 应在它所属的事件循环线程中操作。如果工作在线程池或其他线程中完成,不应直接从那个线程调用 future.set_result(),而要使用线程安全的事件循环入口:
future.set_result()
01import asyncio 02import threading 03 04def worker(loop, future): 05 result = "线程中的计算结果" 06 loop.call_soon_threadsafe(future.set_result, result) 07 08async def main(): 09 loop = asyncio.get_running_loop() 10 future = loop.create_future() 11 12 thread = threading.Thread(target=worker, args=(loop, future)) 13 thread.start() 14 15 print(await future) 16 thread.join() 17 18asyncio.run(main())
Python 还有另一种 concurrent.futures.Future,用于线程池和进程池。它与 asyncio.Future 不是同一个类型,不能直接在异步代码中 await。需要桥接已有的 concurrent.futures.Future 时,可以使用 asyncio.wrap_future();调用 asyncio.to_thread() 或事件循环的执行器 API 时,库通常已经替你处理了这层转换。
concurrent.futures.Future
asyncio.wrap_future()
asyncio.to_thread()
Promise 对比
Future 经常被类比为 JavaScript Promise,因为二者都表示未来的结果,但不能把它们当成完全相同的对象:
new Promise(executor)
resolve
reject
asyncio
.then()
因此,Future 只负责承载结果,不等于 JavaScript 中会立即运行 executor 的 Promise。Python 也不使用浏览器里的宏任务、微任务规则来解释 Future 的恢复顺序。
Future 由定时回调完成,两个等待者取得同一结果,再观察重复完成与异常完成。
入口和主题代码与工作区直接共用同一份来源:
01from fastapi import FastAPI, Query 02 03from futures import run_experiment 04 05app = FastAPI(title="asyncio Future") 06 07@app.get("/future") 08async def experiment( 09 value: str = Query(default="数据已准备好", min_length=1, max_length=80), 10) -> dict[str, object]: 11 report = await run_experiment(value) 12 print(report) 13 return report 14
01import asyncio 02 03async def run_experiment(value: str) -> dict[str, object]: 04 loop = asyncio.get_running_loop() 05 future = loop.create_future() 06 events = [] 07 pending = not future.done() 08 future.add_done_callback(lambda item: events.append("完成回调")) 09 10 def complete() -> None: 11 if not future.done(): 12 events.append("生产者设置结果") 13 future.set_result(value) 14 15 async def consume(name: str) -> dict[str, str]: 16 events.append(f"{name} 等待") 17 return {"name": name, "result": await future} 18 19 handle = loop.call_later(0.02, complete) 20 try: 21 consumers = await asyncio.gather(consume("A"), consume("B")) 22 finally: 23 handle.cancel() 24 try: 25 future.set_result("不能重复完成") 26 except asyncio.InvalidStateError as error: 27 repeated_completion = type(error).__name__ 28 failed = loop.create_future() 29 failed.set_exception(ValueError("预期失败")) 30 try: 31 await failed 32 except ValueError as error: 33 failure = str(error) 34 return {"initially_pending": pending, "done": future.done(), "consumers": consumers, 35 "read_again": await future, "events": events, 36 "repeated_completion": repeated_completion, "failure": failure} 37
打开在线案例,点击运行,等待环境就绪,再发送默认 GET /future?value=数据已准备好。本篇无需密钥或外部服务。
GET /future?value=数据已准备好
initially_pending 和 done 都为 true,两个消费者取得相同文本。重复 set_result 的 InvalidStateError 与异常 Future 的 ValueError 都由实验捕获。
initially_pending
done
true
修改 value 可以看到消费者拿到新结果。每次请求只注册一个短期回调,并在请求结束时清理 TimerHandle;失败 Future 的异常已经取走。
实验事件和状态每次请求独立创建。实际定时与耗时会受到运行环境影响,不能据此承诺固定调度顺序或实时精度。日志输出本次报告,可以在修改参数后对照查看。
下载项目后,在本机终端执行:
1uv run fastapi dev main.py
然后通过 http://127.0.0.1:8000/docs 发送同一请求。文章中的 asyncio.run(...) 是独立终端脚本入口;浏览器和 FastAPI 接口已经有事件循环,这里的案例直接 await 实验函数。
http://127.0.0.1:8000/docs
asyncio.run(...)
此段落已有评论,按 Enter 查看评论及回复列表。
连接 GitHub 后查看和发表评论,也可在 GitHub 查看公开讨论。
1. Future
在异步程序中,一个操作开始时,结果往往还没有准备好。例如,网络库已经发出了请求,但响应要稍后才能到达;某个底层回调已经注册,但回调什么时候触发还不确定。
等待方需要一个可以表达「结果将来会出现」的对象,这就是
asyncio.Future。Future 本身不会执行网络请求,也不会启动一段协程。它只是保存一个尚未产生的结果,并在结果准备好时通知等待者。可以把参与者分成两端:
await等待 Future 完成代码运行到
await future时,如果 Future 尚未完成,当前的consumeTask 会暂停,并把执行机会交还给事件循环。事件循环继续推进produceTask。生产者调用set_result()后,Future 进入完成状态,事件循环随后恢复等待它的 Task。注意,
set_result()的职责是完成 Future,而不是在这一行直接跳进consume()继续执行。等待者由事件循环安排在后续调度机会中恢复。Future 与前面学过的两个对象各自负责不同的事情:
因此,不能把 Future 理解成一个「还没开始的任务」。它更像 Task 或底层异步操作正在等待的结果凭证。
2. 创建
在协程中创建 Future 时,推荐先取得当前事件循环,再调用
loop.create_future():虽然也能直接调用
asyncio.Future(),但loop.create_future()会明确地把 Future 绑定到当前事件循环,也允许第三方事件循环提供与自身适配的实现。因此,编写异步库和底层适配代码时应优先使用这种方式。刚创建的 Future 处于未完成状态。创建它不会自动安排任何工作,如果没有其他代码负责完成它,下面的程序会一直等待:
这也解释了为什么普通业务代码很少需要手动创建 Future:Future 通常由网络库、驱动程序、事件循环适配层创建,业务代码只负责等待库返回的协程或 Task。
同一个 Future 可以被多个 Task 等待。Future 完成后,所有等待者都会取得同一个结果:
Future 完成后会保留结果,所以还可以再次
await它,新的等待不会让生产者重新执行:这和直接重复等待同一个协程对象不同。协程对象只能被完整执行一次,而完成后的 Future 可以反复读取同一个最终结果。
3. 状态
Future 创建后处于
pending,也就是未完成状态。之后只能走向三种终态之一:set_result(value)await返回valueset_exception(error)await抛出该异常cancel()await抛出CancelledError正常、异常和取消都属于「已经完成」,所以这三种情况下
done()都返回True。终态不能再切换到其他状态,一个 Future 只能被完成一次。常用状态方法如下:
done()cancelled()result()exception()Noneget_loop()如果 Future 还没有完成,直接调用
result()或exception()会抛出asyncio.InvalidStateError。在业务代码中,应优先使用await future,因为await会在结果未准备好时暂停,而不是提前读取:set_result()和set_exception()也只能调用一次。如果 Future 已经完成或取消,再设置结果会抛出InvalidStateError。生产者可能晚于取消请求返回结果时,应该先检查取消状态:这项检查主要用于底层回调适配。普通业务代码不应到处用
done()和cancelled()手写一套并发状态机。4. 异常
生产者无法得到正常结果时,可以使用
set_exception()完成 Future。等待者不需要检查某个特殊返回值,直接使用try...except处理异常:如果不等待这个 Future,也没有调用
exception()取走异常,事件循环可能在 Future 被回收时报告Future exception was never retrieved。这通常说明程序启动了异步工作,却没有负责处理它的失败。调用
future.cancel()会尝试把未完成的 Future 标记为取消。等待它的代码会收到asyncio.CancelledError:如果 Future 已经正常或异常完成,
cancel()不会覆盖原来的结果,并返回False。如果取消成功,则返回True。当一个 Task 正在等待 Future,而这个 Task 被取消时,取消通常也会传播到它正在等待的 Future。取消不是普通的失败结果,而是异步调用链停止工作的控制信号;处理
CancelledError时,完成资源清理后通常应该继续抛出。5. 回调
Future 除了可以被
await,还可以通过add_done_callback()注册完成回调。回调只接收一个参数,也就是已经完成的 Future:调用
set_result()后,回调不会嵌套在这一行中立即执行,而是通过事件循环安排执行。即使注册回调时 Future 已经完成,回调也会被安排到后续调度机会。对于普通业务流程,
await往往更直观。add_done_callback()常见于底层库、监控逻辑和需要兼容回调接口的代码。Future 最重要的用途之一,就是把旧式回调 API 转换成可等待的异步 API。假设一个旧函数通过回调返回错误或数据:
转换过程可以分成四步:
await future的结果。调用者看到的是普通的
await request(),不再需要理解底层什么时候调用回调。Future 正是在这里连接了「回调世界」和async/await世界。6. Task
Task 和 Future 都是可等待对象,都能保存最终结果、异常和取消状态,但它们的职责并不相同。
Task 是一种 Future 风格的对象,它在 Future 的状态能力之上增加了「推进协程」的职责。协程
return的值会成为 Task 的结果,协程抛出的异常会成为 Task 的异常;调用者不能使用set_result()或set_exception()任意决定 Task 的结果。asyncio.isfuture(task)返回True,说明 Task 符合 Future 协议,可以像 Future 一样被等待和检查状态。但 Task 的结果来源于协程执行,普通 Future 的结果则由外部生产者设置。awaitreturn或异常loop.create_future()asyncio.create_task()当 Task 执行到
await future时,可以把过程理解为:await返回结果,或者在 Task 中抛出异常。这条链路回答了一个关键问题:Task 被创建后并不是持续占用 CPU。它遇到尚未完成的 Future 时会暂停,事件循环可以去推进其他就绪 Task。
7. 边界
Future 是较底层的工具。编写普通 FastAPI 或 LangChain 业务时,通常应该返回协程的结果,而不是把裸 Future 暴露给调用者:
这样,Future 的创建、完成和取消都留在实现底层。调用者只需要使用稳定的异步函数接口。官方文档也建议,不要在面向业务使用者的 API 中直接暴露 Future。
ensure_future()asyncio.ensure_future()能接收 Future、Task、协程或其他可等待对象,并保证返回一个 Future 风格的对象:如果参数本来就是 Future 或 Task,它会被直接返回;如果参数是协程,则会被包装成 Task 并安排执行。现代应用代码已经明确拿到协程时,通常优先使用语义更清楚的
asyncio.create_task();管理一组相关任务时,优先考虑TaskGroup。线程边界
asyncio.Future不是线程安全对象。Future 应在它所属的事件循环线程中操作。如果工作在线程池或其他线程中完成,不应直接从那个线程调用future.set_result(),而要使用线程安全的事件循环入口:Python 还有另一种
concurrent.futures.Future,用于线程池和进程池。它与asyncio.Future不是同一个类型,不能直接在异步代码中await。需要桥接已有的concurrent.futures.Future时,可以使用asyncio.wrap_future();调用asyncio.to_thread()或事件循环的执行器 API 时,库通常已经替你处理了这层转换。Promise 对比
Future 经常被类比为 JavaScript Promise,因为二者都表示未来的结果,但不能把它们当成完全相同的对象:
asyncio.Futurenew Promise(executor)会立即调用执行器resolve或rejectasyncio事件循环调度等待者和回调.then()等进入微任务队列因此,Future 只负责承载结果,不等于 JavaScript 中会立即运行 executor 的 Promise。Python 也不使用浏览器里的宏任务、微任务规则来解释 Future 的恢复顺序。
8. 在线实验
Future 由定时回调完成,两个等待者取得同一结果,再观察重复完成与异常完成。
入口和主题代码与工作区直接共用同一份来源:
打开在线案例,点击运行,等待环境就绪,再发送默认
GET /future?value=数据已准备好。本篇无需密钥或外部服务。initially_pending和done都为true,两个消费者取得相同文本。重复 set_result 的 InvalidStateError 与异常 Future 的 ValueError 都由实验捕获。修改 value 可以看到消费者拿到新结果。每次请求只注册一个短期回调,并在请求结束时清理 TimerHandle;失败 Future 的异常已经取走。
实验事件和状态每次请求独立创建。实际定时与耗时会受到运行环境影响,不能据此承诺固定调度顺序或实时精度。日志输出本次报告,可以在修改参数后对照查看。
下载项目后,在本机终端执行:
然后通过
http://127.0.0.1:8000/docs发送同一请求。文章中的asyncio.run(...)是独立终端脚本入口;浏览器和 FastAPI 接口已经有事件循环,这里的案例直接await实验函数。