Go 风格协程池snow-The/dsh-goroutine

@snow-the/goroutine

Go 的并发词汇，用于 JS 运行时——goroutine、channel、WaitGroup 和
errgroup——仅构建在 node:worker_threads 之上，因此同一份代码可在 Node、
Deno 以及（从构造上而言）Bun 上运行。没有原生插件，没有 AsyncResource，没有阻塞式等待。

import { Pool, go, WaitGroup, Group, Channel, parallel } from '@snow-the/goroutine';

const pool = new Pool({ size: 4 });                    // worker 线程（“M”）
await pool.run('./jobs.mjs', 'parseLog', [path]);      // 模块通道：无 eval，导入可用
await pool.spawn(() => heavyMath());                   // 内联通道：goroutine 手感（无闭包）

const ch = new Channel(16);                            // 带缓冲；0 = 会合
const wg = new WaitGroup();
for (const file of files) wg.go(() => pool.run('./jobs.mjs', 'hash', [file]));
await wg.wait();
for await (const value of ch) { / for v := range ch / }

const group = new Group();                             // errgroup：首个错误取消其余任务
group.go(() => fetchA(group.signal));
group.go(() => fetchB(group.signal));
await group.wait();

await pool.shutdown({ timeout: 5000 });
async function heavyMath() { return 6  7; }

API

| 导出 | 说明 |
|---|---|
| Pool | 有界 worker 池：run（模块通道）、spawn（内联通道）、drain、shutdown、stats；选项 size/minThreads/maxQueue/overflow/idleTimeout/concurrentTasksPerWorker/retryOnCrash |
| Channel | Go channel：带缓冲环形队列、FIFO 发送者/接收者、send/recv/trySend/tryRecv/close、可异步迭代 |
| WaitGroup | add/done/wait 外加 go(fn)（Go 1.25 的 WaitGroup.Go） |
| Group | errgroup：go(fn)、signal，首个错误胜出并中止同级任务 |
| go(fn) | 微通道即发即忘（面向 IO 型工作的“go func()”） |
| parallel | 对列表进行有界扇出，结果按输入顺序返回 |
| sleep | 可中止的 sleep |

运行时矩阵（本仓库的测试套件，17 个测试）

| 运行时 | 结果 |
|---|---|
| Node v26.7.0（npm test） | 17/17 通过 |
| Deno 2.4.4（deno test --no-check --allow-read --allow-env test/） | 17/17 通过 |

Bun 注意事项：裸 bun test 还会收集被 git 忽略的、位于
ref/piscina/ 下的研究检出，其测试期望一个并不存在的构建产物。请运行
bun test ./test 来执行本库自身的测试套件。
| Bun 1.4.2（bun test ./test） | 17/17 通过（已于 2026-09-11 验证） |

设计

参见 DESIGN.md，了解 Go→JS 的映射（G/M/P、hchan、sync.WaitGroup、
sync.Pool）、从 piscina 采纳了什么、
有意拒绝了什么，以及兼容性规则。所研究的源码检出在 ref/ 下（被 git 忽略）：
ref/piscina 和 ref/go（稀疏：src/runtime + src/sync）。

测量改变了什么

调度器的工作由数字驱动，而非感觉（见 RESEARCH-scheduling.md）：

批量派发曾实现，随后被删除——它让每种工作负载都变慢了
（2000 个微小任务：4 个 worker 上 38.5 ms -> 97.7 ms，1 个 worker 上 74.6 ms -> 348 ms）。Go 采用批处理
以避免每个 P 的队列锁竞争；这个池只有一个共享队列和约 20 µs 的
调度开销，因此批处理只会牺牲并行性。
* 它暴露出的真正 bug 已被修复：overflow: 'wait' 的生产者以
setTimeout(1) 挂起，将突发限制在约 1 个任务/ms。生产者现在挂起在等待者队列上，
并由释放空间的出队操作唤醒——2000 个微小任务从 74.6 ms -> 48 ms
（1 个 worker）以及 38.5 ms -> 29.4 ms（4 个 worker）。

尖锐边缘（已记录，而非隐藏）

* JS 无法抢占：每个“goroutine”在 await 边界处都是协作式的。
* pool.spawn(fn) 将 fn.toString() 发送到 worker——闭包不会捕获。
当你需要导入或捕获状态时，请使用模块通道。
* 任务参数和结果必须可结构化克隆；传递 { transfer: [...] }
以实现零拷贝的 ArrayBuffer 交接。