Skip to content

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_settled behaves as under Design, with every test listed there passing.
  • Succeeded, Failed and Settled are exported from rn_forge.commons.
  • Existing TaskPool tests pass unchanged.
  • uv run pyright passes.

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 AppException on any failure. That is what shutdown(fail_on_error=True) does; the point of map is that the caller decides per item.
  • A batched helper. itertools.batched already exists.
  • A bounded_workers helper. It is one min(), 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 narrow value once the tuple is unpacked, so every caller would check None twice.
  • The name map. It promises Executor.map's lazy, raise-first behaviour.