Python ThreadPoolExecutor 的有界提交:为什么 max_workers 不等于内存上限

举报
yd_215017870 发表于 2026/11/11 15:32:19 2026/11/11
【摘要】 max_workers 限制工作线程数,却不限制调用方提前提交多少任务。本文用 Python 标准库和 Event 构造可重复实验,对比全量 submit 与 FIRST_COMPLETED 窗口,核验提交上限、结果完整及异常传播,并说明输入惰性、结果保留与版本边界。

把 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 测量或生产环境验证。

【声明】本内容来自华为云开发者社区博主,不代表华为云及华为云开发者社区的观点和立场。转载时必须标注文章的来源(华为云社区)、文章链接、文章作者等基本信息,否则作者和本社区有权追究责任。如果您发现本社区中有涉嫌抄袭的内容,欢迎发送邮件进行举报,并提供相关证据,一经查实,本社区将立刻删除涉嫌侵权内容,举报邮箱: cloudbbs@huaweicloud.com
  • 点赞
  • 收藏
  • 关注作者

评论(0)

0/1000
抱歉,系统识别当前为高风险访问,暂不支持该操作

全部回复

上滑加载中

设置昵称

在此一键设置昵称,即可参与社区互动!

*长度不超过10个汉字或20个英文字符,设置后3个月内不可修改。

*长度不超过10个汉字或20个英文字符,设置后3个月内不可修改。