Design decision — pick the concurrency primitive #89

New issue

Closed

opened 2026-06-26 20:38:30 +00:00 by Mark · 1 comment

Mark commented

2026-06-26 20:38:30 +00:00

Owner

Phase 1: Design decision — pick the concurrency primitive

Goal: Lock the design before code. Two sub-decisions:

Async wrapper strategy: run_in_executor (offload to thread pool,
no progress events) vs progress_cb parameter on process() (allows
yield-between-stages progress reporting, requires process() to be
refactored to call the callback).
Progress event shape: what does the callback receive? Plain log
strings? Structured dicts with stage name + percentage? SSE event
format if going through FastAPI?

Files:

New: docs/design/async-pipeline.md with the decision, the rejected
alternatives, and the API contract.

Acceptance:

The decision is committed to a doc with a clear yes/no on each of
the two sub-decisions.
The API contract is spelled out (signature of process_async or
process(progress_cb=...), what the callback receives, when it
fires, how cancellation works).
The ThreadCraft team signs off on the choice (their progress UI
depends on it).

Why first: the API shape of P2/P3 follows from this. Doing P2/P3
without a locked decision risks rework.

Decomposed from easystitch#34

Decomposed from easystitch#51

## Phase 1: Design decision — pick the concurrency primitive **Goal:** Lock the design before code. Two sub-decisions: 1. **Async wrapper strategy:** `run_in_executor` (offload to thread pool, no progress events) vs `progress_cb` parameter on `process()` (allows yield-between-stages progress reporting, requires `process()` to be refactored to call the callback). 2. **Progress event shape:** what does the callback receive? Plain log strings? Structured dicts with stage name + percentage? SSE event format if going through FastAPI? **Files:** - New: `docs/design/async-pipeline.md` with the decision, the rejected alternatives, and the API contract. **Acceptance:** - The decision is committed to a doc with a clear yes/no on each of the two sub-decisions. - The API contract is spelled out (signature of `process_async` or `process(progress_cb=...)`, what the callback receives, when it fires, how cancellation works). - The ThreadCraft team signs off on the choice (their progress UI depends on it). **Why first:** the API shape of P2/P3 follows from this. Doing P2/P3 without a locked decision risks rework. --- --- _Decomposed from [easystitch#34](https://forgejo.tail018ac4.ts.net/Mark/easystitch/issues/34)_ --- _Decomposed from [easystitch#51](https://forgejo.tail018ac4.ts.net/Mark/easystitch/issues/51)_

Mark referenced this issue

2026-06-26 20:38:31 +00:00

Decompose: Make EmbroideryPipeline.process() async with progress reporting — Phase 1: Design decision — pick the concurrency primitive #51

Mark added the

triage-approved

needs-decompose

labels

2026-06-26 20:38:42 +00:00

Mark commented

2026-06-26 20:38:42 +00:00

Author

Owner

Auto-triage: needs decompose

Marked triage-approved + needs-decompose. decompose-executor will pick this up and break it into implementable sub-issues.

## Auto-triage: needs decompose Marked `triage-approved` + `needs-decompose`. decompose-executor will pick this up and break it into implementable sub-issues.

Mark

2026-06-26 20:50:39 +00:00