`concurrent.futures.Future.result`的timeout参数作用及行为不符问题

1. Future.result(timeout)未触发预期TimeoutError #

根据Python官方文档，concurrent.futures.Future.result的timeout参数定义为：若调用未完成，该方法最多等待timeout秒；若调用在timeout秒内仍未完成，则抛出TimeoutError。

但实际测试中未触发预期的TimeoutError，测试代码如下：

from concurrent.futures import ThreadPoolExecutor, as_completed
from time import sleep


def my_worker(sleep_time, expected_timeout):
    sleep(sleep_time)
    print(f'slept for {sleep_time} | expected timeout: {expected_timeout}')


if __name__ == '__main__':
    timeout = 1
    with ThreadPoolExecutor(2) as executor:
        futures = [executor.submit(my_worker, 3, timeout)]
        for future in as_completed(futures):
            future.result(timeout=timeout)

执行结果：

slept for 3 | expected timeout: 1

问题原因 #

as_completed(futures)的迭代器只会返回已经完成的Future对象，当调用future.result(timeout=1)时，任务已经执行完毕，结果处于就绪状态，因此不会触发TimeoutError。result()的timeout参数仅在任务未完成时生效，此处调用时机晚于任务完成时间，超时检查失去意义。

2. as_completed(timeout)的行为不符合文档预期 #

根据Python官方文档，concurrent.futures.as_completed的timeout参数定义为：若调用next()时，自as_completed调用起timeout秒后仍无结果可用，返回的迭代器会抛出TimeoutError。timeout可以是整数或浮点数。

但实际测试中，设置timeout=1后，5个耗时3秒的任务全部完成后才抛出错误，且错误信息与实际任务状态矛盾：

测试代码：

timeout = 1
with ThreadPoolExecutor(2) as executor:
    futures = [executor.submit(my_worker, 3, timeout) for _ in range(5)]
    for future in as_completed(futures, timeout):  # should timeout after one second
        future.result()

执行结果：

slept for 3 | expected timeout: 1
slept for 3 | expected timeout: 1
slept for 3 | expected timeout: 1
slept for 3 | expected timeout: 1
slept for 3 | expected timeout: 1
Traceback (most recent call last):
  File "my_file.py", line 16, in <module>
    completed.__next__()
  File "/usr/local/Cellar/python@3.11/3.11.3/Frameworks/Python.framework/Versions/3.11/lib/python3.11/concurrent/futures/_base.py", line 239, in as_completed
    raise TimeoutError(
TimeoutError: 5 (of 5) futures unfinished

问题原因 #

as_completed的timeout逻辑存在易误解的细节：

1. 迭代器会优先返回所有在超时窗口内完成的Future；若超时后仍有Future陆续完成，迭代器会继续返回这些已完成的对象，直到所有Future都被处理完毕。
2. 错误信息“5 (of 5) futures unfinished”是逻辑偏差导致的：当所有Future都完成后，迭代器尝试获取下一个元素时才触发超时检查，此时未正确更新已完成的Future计数，导致描述与实际状态矛盾。

内容的提问来源于stack exchange，提问作者nlblack323