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.ThreadActorbehaves as under Design, with every test listed there passing.- It is exported from
rn_forge.commons. uv run pyrightanduv run lint-importspass.
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.