Skip to content

F17.2 — Single-owner thread actor

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.2.1 — Build ThreadActor Closed (2026-10-31) —
S17.2.2 — Document the rule Closed (2026-10-31) —

Some libraries must be created, used and closed on one thread: those that wrap a SQLite connection (the beets music library, for one), and single-session SDKs. Apollo serialised every call onto one dedicated owner thread; nothing in that code is specific to the library it owns, so this feature added the generic version to rn-forge-commons.

Outcome: rn_forge.commons.ThreadActor shipped on 2026-10-31. It is documented in the rn-forge-commons processes and tasks guide (docs/guides/processes-and-tasks.md, Thread actor) and its API reference.

Context

Apollo does not wait for it; it keeps its own actor on today's pins and adopts this one after release and a pin bump.

Design

ThreadActor lives in rn_forge.commons.runtime.actor and is re-exported from the rn_forge.commons facade. The rule never to hold the actor during a network call or other long external work is guidance in the runtime guide, not a docstring, because the kit cannot detect a violation. Prior art is Apollo's library actor.

S17.2.1 — Build ThreadActor

State: Closed (2026-10-31)

Acceptance:

  • rn_forge.commons.runtime.actor.ThreadActor behaves as under Design, with every test listed there passing.
  • It is exported from rn_forge.commons.
  • uv run pyright and uv run lint-imports pass.

S17.2.2 — Document the rule

State: Closed (2026-10-31)

Acceptance: the commons runtime guide has a thread-actor section stating the owner-thread guarantee and the rule about never holding the actor during long external work, and the package site builds with --strict.

Acceptance

set -euo pipefail
cd packages/rn-forge-commons
uv run pytest -q tests/runtime/test_actor.py                  # S17.2.1
uv run pyright && uv run lint-imports                         # S17.2.1
rg -q 'never hold the actor' docs/guides                      # S17.2.2
uv run --group docs mkdocs build --strict                     # S17.2.2

Considered and rejected

  • A ThreadPoolExecutor(max_workers=1). It cannot run the factory and the teardown on the owner thread, and it gives no startup-error contract.
  • An asyncio-only actor on a task. The wrapped library blocks, so the event loop would stall; a dedicated thread is the point.