Skip to content

docs: publish measured p-map parity numbers in the migration guide #403

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
ppeeou wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: publish measured p-map parity numbers in the migration guide #403

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 12 additions & 0 deletions website/docs/guide/migrate-from-p-map.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,18 @@ evaluates in fixed windows of `n` (the next window starts after the previous one
finishes), which is useful for batch semantics but has different throughput
characteristics than a `p-map`-style pool on uneven workloads.

## Measured

Same pool semantics should mean the same wall-clock behavior. Measured on the published packages (median of 5 runs, Node 24, `@fxts/core` 2.0.1 vs `p-map` 7):

| Scenario | p-map | `concurrentPool` | `concurrent` |
| -------------------------------------------- | ----- | ---------------- | ------------ |
| Uneven durations (6 tasks, concurrency 2) | 455ms | 455ms | 654ms |
| Uniform 50 × 50ms, concurrency 5 | 510ms | 511ms | 511ms |
| 5,000 already-resolved tasks, concurrency 10 | 4ms | 9ms | 2ms |

Migrating is not a performance trade: on I/O-bound workloads — the reason a concurrency limiter exists at all — `concurrentPool` matches p-map. The last row is the honest fine print: on no-op tasks the pool's order-preserving bookkeeping costs about a microsecond more per item, which disappears as soon as tasks do real work. The `concurrent` column shows the window behavior described above.

## p-limit over a collection → concurrentPool

The common `p-limit` pattern — limiting a mapped collection — is the same
Expand Down
12 changes: 12 additions & 0 deletions website/docs/ja/guide/migrate-from-p-map.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,18 @@ const results = await pipe(
次が始まる)。バッチのセマンティクスが必要な場合には有用ですが、処理時間が不均一な
ワークロードでは `p-map` 方式のプールとスループット特性が異なります。

## 実測

同じプールセマンティクスなら、実際の所要時間も同じはずです。公開パッケージでの実測です(5 回実行の中央値、Node 24、`@fxts/core` 2.0.1 vs `p-map` 7):

| シナリオ | p-map | `concurrentPool` | `concurrent` |
| -------------------------------------- | ----- | ---------------- | ------------ |
| 不均一な所要時間(6 タスク、並行数 2) | 455ms | 455ms | 654ms |
| 均一 50 × 50ms、並行数 5 | 510ms | 511ms | 511ms |
| resolve 済みタスク 5,000 件、並行数 10 | 4ms | 9ms | 2ms |

移行はパフォーマンスのトレードオフではありません: 並行数リミッターの存在理由である I/O バウンドのワークロードでは、`concurrentPool` は p-map と同等です。最後の行は正直な注記です — no-op タスクではプールの順序保持の管理コストが 1 件あたり約 1 マイクロ秒余分にかかりますが、タスクが実際の処理を行った瞬間に消える規模です。`concurrent` 列は上で説明したウィンドウ動作を示しています。

## コレクションに対する p-limit → concurrentPool

最も一般的な `p-limit` パターン — マッピングされたコレクションへの制限 — も同じ
Expand Down
12 changes: 12 additions & 0 deletions website/docs/ko/guide/migrate-from-p-map.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,18 @@ const results = await pipe(
윈도우가 시작), 배치 의미론이 필요할 때는 유용하지만 작업 시간이 불균일한
워크로드에서는 `p-map` 방식의 풀과 처리량 특성이 다릅니다.

## 실측

같은 풀 의미론이라면 실제 소요 시간도 같아야 합니다. 배포된 패키지 기준 실측입니다(5회 실행 중앙값, Node 24, `@fxts/core` 2.0.1 vs `p-map` 7):

| 시나리오 | p-map | `concurrentPool` | `concurrent` |
| -------------------------------------- | ----- | ---------------- | ------------ |
| 불균일 작업시간 (6개 작업, 동시성 2) | 455ms | 455ms | 654ms |
| 균일 50개 × 50ms, 동시성 5 | 510ms | 511ms | 511ms |
| 이미 resolve된 작업 5,000개, 동시성 10 | 4ms | 9ms | 2ms |

마이그레이션은 성능 트레이드가 아닙니다: 동시성 리미터가 존재하는 이유인 I/O 바운드 워크로드에서 `concurrentPool`은 p-map과 동일합니다. 마지막 행은 정직한 각주입니다 — no-op 작업에서는 풀의 순서 보존 장부 관리가 항목당 약 1마이크로초를 더 쓰는데, 작업이 실제 일을 하는 순간 사라지는 수준입니다. `concurrent` 열은 위에서 설명한 윈도우 동작을 보여줍니다.

## 컬렉션에 대한 p-limit → concurrentPool

가장 흔한 `p-limit` 패턴 — 매핑된 컬렉션에 제한을 거는 것 — 도 같은 방식으로
Expand Down
12 changes: 12 additions & 0 deletions website/docs/zh/guide/migrate-from-p-map.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,18 @@ const results = await pipe(
单位的固定窗口求值(前一个窗口结束后下一个才开始),需要批处理语义时很有用,但在任务
耗时不均匀的场景下,其吞吐特性与 `p-map` 式的池不同。

## 实测

相同的池语义应当意味着相同的实际耗时。以下是基于已发布包的实测(5 次运行取中位数,Node 24,`@fxts/core` 2.0.1 vs `p-map` 7):

| 场景 | p-map | `concurrentPool` | `concurrent` |
| --------------------------------- | ----- | ---------------- | ------------ |
| 耗时不均(6 个任务,并发 2) | 455ms | 455ms | 654ms |
| 均匀 50 × 50ms,并发 5 | 510ms | 511ms | 511ms |
| 5,000 个已 resolve 的任务,并发 10 | 4ms | 9ms | 2ms |

迁移不是性能上的交换:在 I/O 密集型负载 — 并发限制器存在的根本原因 — 上,`concurrentPool` 与 p-map 持平。最后一行是坦诚的注脚 — 对 no-op 任务,池的保序簿记每项多花约 1 微秒,一旦任务做真实工作,这个差异就消失了。`concurrent` 列展示了上文所述的窗口行为。

## 针对集合的 p-limit → concurrentPool

最常见的 `p-limit` 模式 — 对映射后的集合施加限制 — 也是同样的迁移方式:
Expand Down
Loading