F17.3 — TaskPool.map_settled
| State | Closed |
| Parent | E17 |
| Iteration | Release 8 |
| Start Date | 2026-10-31 |
| Closed Date | 2026-10-31 |
| Predecessors | — |
| Source | Owner request, 2026-10-21 |
Stories: 2 Closed
| Story | State | Depends on |
|---|---|---|
S17.3.1 — Build TaskPool.map_settled |
Closed (2026-10-31) | — |
| S17.3.2 — Document mapping over items | Closed (2026-10-31) | — |
TaskPool runs Task objects, so fanning one plain function over many items
needed an adapter class and a per-item task name, which Apollo wrote for its
file scans. This feature gave TaskPool a map_settled method so no adapter is
needed; the worker count and batching stay out.
Outcome: TaskPool.map_settled, Succeeded, Failed and Settled shipped
on 2026-10-31. They are documented in the rn-forge-commons processes and tasks
guide (Mapping over items) and the map_settled docstring.
Context
Apollo does not wait for it; its adapter stays until it adopts the released method.
Design
map_settled works on the executor directly, creating no Task, and is named
for what it returns: unlike Executor.map, which is lazy and raises the first
error, it waits for every item and settles each one. TaskPool.__init__ is
unchanged because the caller sizes the pool, and batching is left to
itertools.batched. Prior art is Apollo's per-file fan-out helper.
S17.3.1 — Build TaskPool.map_settled
State: Closed (2026-10-31)
Acceptance:
TaskPool.map_settledbehaves as under Design, with every test listed there passing.Succeeded,FailedandSettledare exported fromrn_forge.commons.- Existing
TaskPooltests pass unchanged. uv run pyrightpasses.
S17.3.2 — Document mapping over items
State: Closed (2026-10-31)
Acceptance: the tasks guide has a section on mapping a function over items
that names the actor rule in F17.2 as the reason to fan
out off the owner thread and says how to size max_workers, and the package
site builds with --strict.
Acceptance
set -euo pipefail
cd packages/rn-forge-commons
uv run pytest -q tests/runtime/test_tasks.py # S17.3.1
uv run pyright # S17.3.1
uv run --group docs mkdocs build --strict # S17.3.2
Considered and rejected
- A free function
map_tasks(fn, items). It would own its pool, so a caller could not share a bounded pool across calls. - Raising an aggregate
AppExceptionon any failure. That is whatshutdown(fail_on_error=True)does; the point ofmapis that the caller decides per item. - A
batchedhelper.itertools.batchedalready exists. - A
bounded_workershelper. It is onemin(), and its ceiling of 8 tunes Apollo's ffprobe workload; capping a thread pool by CPU count is wrong for I/O-bound work in general. - A
(value, error)tuple result. Pyright does not narrowvalueonce the tuple is unpacked, so every caller would checkNonetwice. - The name
map. It promisesExecutor.map's lazy, raise-first behaviour.