Python ThreadPoolExecutor 的有界提交:为什么 max_workers 不等于内存上限
把 ThreadPoolExecutor(max_workers=3) 放进批处理脚本,很容易产生一个直觉:最多三个任务同时执行,任务相关的内存应该也只对应三份数据。然而,如果主线程先遍历全部输入,把每个任务都 submit 进去,再慢慢取结果,限制的只是工作线程,不是提前创建的任务数量。
这不是线程池失效,而是两个问题被同一个参数掩盖了:谁控制同时执行的数量,谁控制尚未消费的任务数量?本文用一个小型合成实验拆开它们。不访问网络、不读业务文件,只分配固定大小的字节串,并用 Event 建立检查点。我们核对任务数量和结果,不做速度排行,也不把逻辑字节数冒充进程内存实测。
一、先把三个数量分开
第一个数量是正在执行的任务。线程池至多使用 max_workers 个工作线程,正在运行的调用受到这个约束。第二个数量是已经提交、尚未完成的任务,既包括运行中的,也包括等待执行的。第三个数量是已经提交、尚未被调用方成功消费结果的任务,还包括已经完成却未读取的 Future。
本文选择第三个作为窗口口径,记为 submitted - consumed。只有 future.result() 成功返回,且消费函数成功接收结果,才增加 consumed。因此,max_in_flight 不只是“正在跑”的上限,也覆盖完成结果等待消费的阶段。Future 已完成,不代表它持有的结果已经无人引用。
还要区分“累计提交”与“当前窗口”。有界执行器最后仍然应该完成全部二十四项任务;它不是把任务总数截成五项,而是分批向前推进。只看到最终 submitted=24,无法判断过程中是否施加背压,必须观察峰值,或一个具有明确时序含义的中间检查点。
二、为什么不用 sleep 猜测队列积压
如果先提交一批任务,等待几十毫秒,再打印“当前完成多少项”,结论会受机器负载和线程调度影响。快机器可能提前跑完,慢机器可能尚未调度到工作线程。这样的输出可以描述某次运行,却不适合证明一个数量上限。
本例改用关闭的 Event。每个工作函数拿到参数后,第一件事就是等待事件。提交器完成首轮填充后,在调用 gate.set() 之前执行检查:事件仍关闭,输入源已生成多少项,提交计数是多少,成功消费计数是否为零。工作线程是否已经获得时间片不影响判断,因为它们不可能越过关闭的门。
全量提交分支在检查点之前遍历全部输入;窗口分支只填满首个窗口。两者使用相同的线程数、任务数和载荷大小。检查结束后才放行,随后核验结果完整性。事件在异常清理中也会打开,防止验证器自身的断言失败后,工作线程永远停在门外。实验没有用睡眠长短来推断队列状态。
三、合成数据要让保留关系清楚
输入源每次被取出时,才新建一个三十二 KiB 的字节串,返回任务编号与载荷。它不是提前构建的列表,也不是让全部任务共享同一份大对象。这样,generated 能说明上游被拉取到了哪里;首轮已提交任务的参数也确实对应各自独立的载荷。
载荷中每个字节由编号决定,工作函数返回编号和一个可独立核对的整数。消费器检查编号范围、拒绝重复,再验证计算公式。最后将收到的编号集合与完整集合比较,既查漏项,也查重项;校验和只是辅助读数,不代替逐项核验。
为便于审阅,消费器保存全部已见编号。这个测试集合有随任务总数增长的空间开销,不能反过来证明整份程序内存恒定。真正业务中可把消费器替换成逐条写出或受控聚合,同时单独约束输出端。窗口解决提交链路的一层,不会自动替整个程序完成内存审计。
四、完整代码:先取结果,再补空位
将代码保存为 bounded-futures-demo.py,运行 python bounded-futures-demo.py。只用标准库,无须联网、安装依赖或管理员权限。不要加 -O,因为示例使用 assert 作为验证判据。本次实际运行版本为 Python 3.12.14;程序会打印执行时的真实版本。
"""Deterministic standard-library experiment; no RSS or timing claims."""
from concurrent.futures import FIRST_COMPLETED, ThreadPoolExecutor, wait
from dataclasses import dataclass
from threading import Event
import platform
N = 24
WORKERS = 3
WINDOW = 5
PAYLOAD_BYTES = 32768
@dataclass
class Stats:
submitted: int = 0
consumed: int = 0
peak: int = 0
def added(self):
self.submitted += 1
self.peak = max(self.peak, self.submitted - self.consumed)
class Source:
def __init__(self, n=N):
self.n = n
self.generated = 0
def __iter__(self):
return self
def __next__(self):
if self.generated == self.n:
raise StopIteration
i = self.generated
self.generated += 1
return i, bytes([i % 256]) * PAYLOAD_BYTES
class Sink:
def __init__(self):
self.seen = set() # Test oracle only: deliberately retains O(N) IDs.
self.total = 0
def __call__(self, result):
i, value = result
assert 0 <= i < N and i not in self.seen
assert value == i * i + (i % 256) * PAYLOAD_BYTES
self.seen.add(i)
self.total += value
def eager(pool, fn, source, consume, stats, limit, on_filled):
futures = []
try:
for item in source:
futures.append(pool.submit(fn, item))
stats.added()
on_filled()
for future in futures:
consume(future.result())
stats.consumed += 1
finally:
for future in futures:
future.cancel()
def bounded(pool, fn, source, consume, stats, limit, on_filled):
if type(limit) is not int or limit < 1:
raise ValueError("max_in_flight must be a positive integer")
source = iter(source)
pending = set()
exhausted = False
def fill():
nonlocal exhausted
while not exhausted and len(pending) < limit:
try:
item = next(source)
except StopIteration:
exhausted = True
break
pending.add(pool.submit(fn, item))
stats.added()
assert stats.submitted - stats.consumed <= limit
try:
fill()
on_filled()
while pending:
done = wait(pending, return_when=FIRST_COMPLETED).done
for future in done:
consume(future.result()) # Retrieve failures before any refill.
stats.consumed += 1
pending.remove(future)
del done, future # Release this batch before submitting replacements.
fill()
finally:
for future in pending:
future.cancel() # Running threads cannot be force-cancelled.
class PlannedFailure(RuntimeError):
pass
def run_case(runner, label, window, fail=False):
source, sink, stats, gate = Source(), Sink(), Stats(), Event()
target = N if runner is eager else min(window, N)
snapshot = None
def work(item):
gate.wait()
i, payload = item
if fail and i == 0:
raise PlannedFailure("boom:0")
return i, i * i + sum(payload)
def on_filled():
nonlocal snapshot
assert not gate.is_set()
assert source.generated == stats.submitted == target
assert stats.consumed == 0
snapshot = (source.generated, stats.submitted, target * PAYLOAD_BYTES)
gate.set()
caught = None
try:
with ThreadPoolExecutor(max_workers=WORKERS) as pool:
try:
runner(pool, work, source, sink, stats, window, on_filled)
finally:
gate.set() # Also release workers when a harness assertion fails.
except PlannedFailure as exc:
caught = str(exc)
if fail:
assert caught == "boom:0"
assert stats.submitted == target and stats.consumed == 0
assert source.generated == target
print(f"{label} error={caught} submitted={stats.submitted} "
f"consumed={stats.consumed} generated={source.generated}")
else:
assert caught is None and sink.seen == set(range(N))
assert stats.submitted == stats.consumed == source.generated == N
assert stats.peak == target
generated, submitted, held_bytes = snapshot
print(f"{label} blocked_generated={generated} "
f"blocked_submitted={submitted} held_input_bytes={held_bytes}")
print(f"{label} total={stats.submitted} consumed={stats.consumed} "
f"peak_unconsumed={stats.peak} checksum={sink.total}")
def main():
print(f"Python {platform.python_version()}")
print(f"tasks={N} workers={WORKERS} window={WINDOW} "
f"payload_bytes={PAYLOAD_BYTES}")
run_case(eager, "eager", WINDOW)
run_case(bounded, "bounded", WINDOW)
run_case(eager, "eager", WINDOW, fail=True)
run_case(bounded, "bounded", 1, fail=True)
print("ALL CHECKS PASSED")
if __name__ == "__main__":
main()
eager 先生成并提交全部任务,再按提交顺序读取结果,这是有意设置的对照组。bounded 先填满窗口,随后调用 wait(..., return_when=FIRST_COMPLETED)。这个参数表示至少一个 Future 完成或取消即可返回,并不保证每次只拿到一个,所以代码处理整个 done 集合。
处理一批完成项时,先调用 result(),再交给消费器,成功后才移出 pending。整批处理结束,释放这批局部引用后再补位。慢消费器会延迟下一次输入拉取,背压可以沿提交器传回输入源,而不是只有工作线程在等待。on_filled 仅用于实验的首轮检查,普通调用可传入不做事的函数。
五、真实输出与对照结果
以下是 Python 3.12.14 本地执行所得完整标准输出,退出码为零;正文代码也被独立抽取执行并交叉核验。没有删掉失败分支,也没有把设计预期改写成测量值。
Python 3.12.14
tasks=24 workers=3 window=5 payload_bytes=32768
eager blocked_generated=24 blocked_submitted=24 held_input_bytes=786432
eager total=24 consumed=24 peak_unconsumed=24 checksum=9048292
bounded blocked_generated=5 blocked_submitted=5 held_input_bytes=163840
bounded total=24 consumed=24 peak_unconsumed=5 checksum=9048292
eager error=boom:0 submitted=24 consumed=0 generated=24
bounded error=boom:0 submitted=1 consumed=0 generated=1
ALL CHECKS PASSED
| 核验项目 | 一次性提交 | 窗口提交 |
|---|---|---|
| 工作线程数 | 3 | 3 |
| 正常分支窗口设置 | 全量 | 5 |
| 开门前已生成、已提交 | 24 | 5 |
| 开门前逻辑载荷字节数 | 786432 | 163840 |
| 正常结束成功消费 | 24 | 24 |
| 提交减消费的峰值 | 24 | 5 |
| 逐项校验后的校验和 | 9048292 | 9048292 |
| 首项失败测试提交数 | 24 | 1(单项窗口) |
两组线程数相同,但开门前提交量不同,说明线程数量没有替提交端建立窗口。放行后两组结果都完整;窗口降低的是同时占用名额的任务数,不是偷偷丢弃任务。
held_input_bytes 按检查点处已提交任务的载荷长度求和,不包括 Future、任务包装对象、线程栈、集合、解释器分配器和操作系统其他开销。它说明参数包含多少逻辑载荷字节,不是 RSS,不能据此声称整个进程内存按相同比例下降。实验没有测量实际驻留内存,也没有推导生产容量。
六、异常传播与“停止补位”不是一回事
任务函数抛出的异常,不会因为调用 wait 就自动在主线程里抛出。wait 告诉我们哪些 Future 到达终态,读取 future.result() 才会把任务异常带回调用方。如果只等完成、从不取结果,批处理可能表面结束,却未正确报告失败。
示例让编号零抛出 PlannedFailure,并在验证器外层捕获同类型异常、核对消息。为使失败分支的生成数量不依赖完成顺序,窗口分支专门使用单项窗口;它必须先看到首项异常,才能继续拉取输入,因此失败后不能生成后续任务。全量分支则在开门之前已经提交完全部输入。
这不等于“任意窗口遇错都只执行一项”。窗口大于一时,其他任务可能早已开始,甚至先完成并被消费;done 是集合,没有输入顺序承诺。示例先处理已取到的整批,再补位,能在观察到本批异常后避免下一轮提交,但不是对异常实际发生瞬间的抢占式通知。
finally 中的 cancel() 只尝试取消尚未运行的 Future,不能强制结束运行中的线程。线程池上下文退出会等待已启动任务收尾,因此“异常被发现”“停止提交”“函数返回”是不同时间点。工作函数若永久阻塞,这个提交器不会凭空获得安全终止线程的能力;实际 I/O 仍需自身的超时或协作停止机制。
七、输入惰性不等于执行器惰性
把列表换成生成器很重要,但还不够。提交端若仍遍历生成器直到结束,依然会把上游拉空,只是输入列表不再单独保存。类似地,内置 map 返回迭代器,不保证下游不会主动将其一次性吃完。惰性是整条链路的性质,不是某个对象名字的属性。
还要分清内置 map 与 Executor.map。依据 Python 官方《concurrent.futures — Launching parallel tasks》的 Python 3.14 文档,Executor.map 在 3.14 新增 buffersize:指定缓冲时,限制已提交但结果尚未由迭代器产出的任务数量,缓冲满会暂停继续迭代输入。默认 None 仍立即收集输入,不能因为结果是迭代器,就认为输入也按需拉取。
不要把该参数直接复制到未确认支持的旧解释器上。本次实验运行于 3.12.14,手工窗口不依赖 buffersize;版本差异依据官方文档核对,没有在本次运行环境测试 3.14 接口。部署时应查对应版本文档或实际签名,而不是把新版示例当作通用语法。
手工窗口也不全面优于官方接口:Executor.map 按输入次序交付结果,本例按完成批次消费,两者顺序语义不同。若要求严格按输入顺序输出,后续任务即使先完成,也可能等待慢前项。增加一个不受限的重排字典会重新引入增长点,不能只是把积压从 Future 集合挪到别处。
八、这个窗口究竟保证了什么
在提交器独占计数、输入按需生成、消费成功才释放名额的前提下,窗口限制本调用链内已提交而未成功消费的任务数。它不限制其他线程的提交,也不限制工作函数内部再创建的队列,更不限制单个任务申请多少内存。
若单项载荷可能非常大,数量上限就不是字节上限;还应限制单项大小,或引入按权重计算的容量预算。输入源若内部预取大量数据,消费器若把全部结果追加到列表,闭包若长期保留原始对象,都需要分别约束。计数器帮助定位边界,却不能代替对象生命周期分析。
本例的 Source、Sink 与 run_case 是围绕固定二十四项设计的测试器,不是可直接替换任意业务的数据框架。bounded 没有保存结果全集,但没有关闭调用方传入的输入源;生成器若持有文件等资源,所有者应使用上下文或显式关闭,并定义输入迭代异常与消费失败后的恢复策略。
还应避免让工作函数在同一个小线程池中等待自己提交的其他 Future。线程全被占满,又都等待未获调度的任务时,提交窗口不会消除依赖死锁。由调用线程维护窗口,让工作函数保持清楚的输入输出与退出约定,比调度和业务计算无意间相互嵌套更容易审计。
窗口值如何选择,也不能只从这个小实验照搬。五是为了让窗口大于线程数、又明显小于总任务数,便于展示等待执行与等待消费共同占用名额;它不是推荐的生产参数。窗口过小可能让可用线程得不到足够工作,窗口增加又会容纳更多参数和结果。真实选择应结合单项大小、下游消费速度、允许的排队量与失败后的剩余工作量,并用自身负载验证,不能凭本例推出吞吐提升百分比。
从代码结构也能检查上限,而不只相信一次输出:初始集合为空,填充循环只在集合长度小于窗口时提交,每次增加一个 Future;处理完成项只减少集合;下一轮仍由相同条件补齐。成功路径中集合长度与“提交减消费”同步,因此计数不会越过窗口。这个推理依赖只有当前线程维护集合,不能把同一个集合交给多个提交者同时修改后仍声称条件成立。
本地验证还覆盖了窗口为一、二、三、五和大于任务总数,以及空输入、无效窗口、输入迭代异常和消费器异常。后两类错误同样必须传回调用者,而不是被误当成任务已全部完成。它们补充的是接口边界,不是生产可靠性认证;取消成功率、长时间运行和外部服务行为均不在这次验收范围。
九、小结:限制线程,也限制提前承诺的工作
max_workers 回答“最多安排多少工作线程”,max_in_flight 回答“允许多少任务占着尚未消费的名额”。前者不是后者的替代品,后者也不是全进程内存硬上限。
可信实验需要交代检查点为何成立、上游拉取到哪里、结果是否完整、异常在哪重新抛出,以及计数之外有哪些保留对象。本例用事件消除短暂等待的猜测,用明确计数定义背压,再用逐项检查和正文代码交叉运行核验结论。应用时应沿输入、提交、计算、消费四段继续寻找边界,而不是只调整一个线程数。
参考资料:Python 官方文档《concurrent.futures — Launching parallel tasks》中的 Executor.map、ThreadPoolExecutor、Future.result、Future.cancel、wait 与 FIRST_COMPLETED;buffersize 版本信息依据 Python 3.14 文档。本文仅为本地合成实验,未做吞吐压测、RSS 测量或生产环境验证。
- 点赞
- 收藏
- 关注作者
评论(0)