asyncio.wait是Python异步编程中用于管理多个并发任务的核心函数之一，它提供了灵活的机制来等待一组协程或任务的完成，并支持不同的等待模式与超时控制，与asyncio.gather不同，wait更侧重于对任务完成状态的精细化管理，允许开发者根据需求选择等待所有任务完成、任意任务完成或首个异常抛出的场景,是构建复杂异步逻辑的重要工具。
基本概念与核心功能
asyncio.wait的主要作用是等待一组可等待对象（协程、Task对象或Future对象）达到特定完成状态，并返回两个集合：已完成任务（done）和未完成任务（pending），其函数签名如下：
asyncio.wait(fs, *, timeout=None, return_when=ALL_COMPLETED)
fs是可等待对象的迭代器，timeout是可选的超时时间（单位秒），return_when控制等待行为的枚举值，默认为asyncio.ALL_COMPLETED（等待所有任务完成），通过调整return_when参数，开发者可以实现多样化的等待策略，例如在首个任务完成时立即返回,或在首个异常抛出时终止等待。
核心参数详解
return_when：等待模式控制
return_when是asyncio.wait的关键参数，定义了何时停止等待并返回结果，其可选值包括：
- ALL_COMPLETED（默认）：等待所有任务完成（无论成功或失败）。
- FIRST_COMPLETED：只要有一个任务完成（成功或失败），立即返回。
- FIRST_EXCEPTION：只要有一个任务因异常终止，立即返回；若无异常，则等待所有任务完成。
在需要“快速失败”的场景中（如多个API请求，只要有一个出错即可终止后续等待），使用FIRST_EXCEPTION能避免不必要的资源消耗；而在需要汇总所有结果的场景（如批量数据处理），ALL_COMPLETED则更合适。
timeout：超时机制
timeout参数用于限制最大等待时间，若在指定时间内未达到return_when的条件，函数会立即返回当前已完成的任务和未完成的任务，需要注意的是，超时后未完成的任务不会自动取消，需开发者手动处理（如调用task.cancel()），否则可能导致资源泄漏。
设置timeout=5时，若5秒内无任务完成，wait会返回空的done集合和完整的pending集合；若部分任务已完成,则返回这些已完成任务及剩余未完成任务。
使用场景与示例
场景1：等待首个任务完成（FIRST_COMPLETED）
假设需要并发发起多个网络请求，只要有一个返回结果即可继续后续处理，无需等待其他请求完成，此时可使用FIRST_COMPLETED模式：
import asyncio
async def fetch(url):
await asyncio.sleep(1) # 模拟网络请求
return f"Result from {url}"
async def main():
urls = ["url1", "url2", "url3"]
tasks = [asyncio.create_task(fetch(url)) for url in urls]
done, pending = await asyncio.wait(tasks, return_when=asyncio.FIRST_COMPLETED)
result = done.pop().result() # 获取首个完成的任务结果
print(f"First completed: {result}")
# 取消剩余未完成的任务
for task in pending:
task.cancel()
asyncio.run(main())
上述代码中，三个fetch协程并发执行，假设其中一个最先完成（如url1），wait会立即返回，后续pending中的任务被取消，避免资源浪费。
场景2：处理首个异常（FIRST_EXCEPTION）
在批量任务中，若某个任务因异常失败，可能需要立即终止并处理错误，而非等待所有任务完成，FIRST_EXCEPTION模式适用于此场景：
async def task_with_error():
await asyncio.sleep(0.5)
raise ValueError("Something went wrong")
async def normal_task():
await asyncio.sleep(2)
return "Normal task completed"
async def main():
tasks = [
asyncio.create_task(task_with_error()),
asyncio.create_task(normal_task())
]
done, pending = await asyncio.wait(tasks, return_when=asyncio.FIRST_EXCEPTION)
for task in done:
try:
task.result() # 检查任务是否异常
except Exception as e:
print(f"Error caught: {e}")
# 取消剩余任务
for task in pending:
task.cancel()
asyncio.run(main())
运行后，task_with_error会在0.5秒后抛出异常，wait立即返回，异常被捕获并处理，normal_task被取消,避免无效等待。
注意事项与最佳实践
- 任务结果获取：asyncio.wait返回的是任务对象集合，需通过task.result()获取结果，若任务抛出异常，直接调用result()会重新抛出异常，需用try-except处理。
- 资源清理：超时或提前返回时，未完成的任务需手动取消（task.cancel()），否则协程可能继续运行，导致资源浪费。
- 与gather的区别：asyncio.gather会收集所有任务的结果（无论成功或失败），并返回结果列表或抛出聚合异常；而wait只返回任务状态，需手动处理结果，灵活性更高但代码稍复杂。
- 避免阻塞事件循环：wait本身是非阻塞的，但若在任务中执行同步阻塞操作（如time.sleep()），会阻塞事件循环，需用asyncio.sleep()替代。
最佳实践示例
结合asyncio.wait和asyncio.shield实现“超时保护+任务取消”：
import asyncio
async def protected_task():
try:
await asyncio.sleep(3)
return "Protected task completed"
except asyncio.CancelledError:
print("Task cancelled due to timeout")
raise
async def main():
task = asyncio.create_task(protected_task())
try:
# 使用shield保护任务不被外部取消，同时设置超时
done, pending = await asyncio.wait(
[asyncio.shield(task)],
timeout=2,
return_when=asyncio.ALL_COMPLETED
)
if pending:
task.cancel() # 超时后取消任务
await task # 等待任务处理取消逻辑
except Exception as e:
print(f"Unexpected error: {e}")
asyncio.run(main())
此示例中，shield确保任务在超时前不会被意外取消，超时后手动取消任务并等待其清理资源,实现健壮的异步任务管理。
相关问答FAQs
Q1: asyncio.wait和asyncio.gather有什么区别？如何选择？
A: asyncio.wait和asyncio.gather均可管理多个任务，但核心区别在于：
- gather：收集所有任务的结果，返回结果列表（成功）或抛出第一个异常（失败），适合需要汇总所有结果的场景；
- wait：返回任务集合（done/pending），需手动获取结果，支持灵活的等待模式（如FIRST_COMPLETED），适合需要精细控制任务完成逻辑的场景。
选择时，若只需“所有任务结果”用gather；若需“部分任务完成”“异常处理”等复杂控制用wait。
Q2: 使用asyncio.wait时，如何正确处理任务异常和超时？
A: 处理异常需遍历done集合，对每个任务调用task.result()并用try-except捕获；超时需检查pending集合，手动取消未完成任务并等待其清理（如task.cancel() + await task），示例见上文“最佳实践示例”,通过shield和超时机制确保任务安全终止。
原创文章，发布者：酷番叔，转转请注明出处：https://cloud.kd.cn/ask/55104.html
