Go Ants 预分配池调用 Tune 为什么不改变容量

如果 Go Ants 初始化时用了 ants.WithPreAlloc(true)，随后调用 pool.Tune(128) 但 pool.Cap() 仍返回原来的容量，这通常不是调用失败，而是预分配池的设计边界。官方项目地址：https://github.com/panjf2000/ants。预分配模式在创建池时按初始容量建立 loop queue，Tune 会主动避开这类池。

预分配池解决的是大容量 worker 队列的内存准备问题，不等于允许运行中调整容量；如果目标是动态扩容，应关闭预分配，或在配置变化时安全地重建池。

• 固定容量：需要大容量且任务生命周期较长时，使用 WithPreAlloc(true)，把容量当作初始化约束。
• 动态调优：不使用预分配，让 Tune(size) 修改普通池的容量上限。
• 替换配置：预分配池必须换容量时，准备新池、切换引用，再释放旧池，不能只改一个配置字段。

先把现象和目标分开

项目里最容易混淆的是“池容量”“当前运行 worker 数”和“队列里等待的任务”。Cap() 是容量上限，Running() 是当前运行 worker 数，Free() 是容量减去运行数，Waiting() 是正在等待提交的调用数。调用 Tune 后观察错指标，可能会把容量没有变化误判成所有调优都没有生效。

package main

import (
    "fmt"

    "github.com/panjf2000/ants/v2"
)

func main() {
    // 预分配模式在创建时准备固定大小的 worker 队列。
    pool, err := ants.NewPool(64, ants.WithPreAlloc(true))
    if err != nil {
        // 初始化失败时不要继续提交任务。
        panic(err)
    }
    defer pool.Release() // 主流程结束后释放池资源。

    fmt.Println("before:", pool.Cap())
    pool.Tune(128) // 预分配池会忽略这次调优请求。
    fmt.Println("after:", pool.Cap())
}

这段示例的重点不是某个运行输出，而是配置关系：初始容量为 64 时，预分配队列已经按这个边界建立，Tune(128) 不会把它变成可伸缩队列。

为什么 Tune 在预分配池上直接返回

Ants 官方源码中的 poolCommon.Tune 先读取当前容量，再检查几个无需修改的条件：无限池、非正的新容量、容量没有变化，以及 p.options.PreAlloc 为真。只要命中其中一项，方法就直接返回；预分配池正是最后一种情况。

因此，Tune 并不是“先修改 capacity，再尝试扩容 loop queue”。它在预分配模式下连容量字段也不会改。这个判断同时适用于普通 Pool 和接收统一函数的 PoolWithFunc；当前 v2 文档也明确说明，Tune 对无限池或预分配池无效。

这条边界的好处是避免只改上限却没有同步调整底层预分配队列。代价是容量和队列大小必须在创建时一起决定，不能把预分配池当作动态配置容器。

需要动态调优时应该怎么改

如果业务确实需要根据负载改变容量，最小改法是不要启用 WithPreAlloc(true)。普通池使用可伸缩的 worker 队列，Tune 才能更新容量并唤醒等待者；缩小容量时，已经运行的 worker 不会被强行中断，新的提交会按新的上限等待。

package main

import (
    "fmt"

    "github.com/panjf2000/ants/v2"
)

func resize(pool *ants.Pool, target int) {
    // 先过滤无效值，避免把配置错误伪装成调优结果。
    if target 

如果必须保留预分配带来的内存特性，就采用重建池：先创建目标容量的新池，停止向旧池接收新任务，完成引用切换后再释放旧池。切换过程需要由业务层的互斥、原子引用或配置中心保证一致性，不能让提交方同时拿到两个生命周期不明的池。

一套可复用的排查与迁移流程

第一阶段先记录初始化选项，确认是否开启了 PreAlloc，同时记录初始容量。第二阶段分别读取 Cap、Running、Free 和 Waiting，不要只看任务吞吐量猜测容量。第三阶段把目标分成“固定大容量”或“运行期调优”：前者保留预分配，后者关闭预分配。第四阶段若要改变预分配容量，按新池创建、引用切换、旧池释放的生命周期处理，并给配置变更留下日志。

常见问题

调用 Tune 后 Cap 一定应该变化吗？

不一定。无限池、非正容量、相同容量和预分配池都会让 Tune 直接返回。先检查初始化选项和目标值，再判断是否真的需要调整。

关闭预分配会不会立刻创建所有 worker？

不会。关闭预分配只是允许普通队列按运行需求管理 worker；它不等于一次性启动目标容量的全部 goroutine。任务执行仍由提交量和池的调度逻辑决定。