flutter-squadron-concurrency-engineering

Flutter Squadron Concurrency Engineering

Mission

Move only the right computation off Flutter's main isolate, using the smallest justified worker boundary, message volume, concurrency, and lifecycle cost. Use this decision loop:

measure the slow stage
→ classify CPU vs I/O
→ estimate transfer/startup cost
→ choose main/Future/compute/Worker/Pool/server
→ define coarse worker API + wire types
→ bound concurrency/backpressure
→ add cancellation + stale-result protection
→ own worker lifecycle
→ test native and web separately
→ profile end-to-end + UI frames + memory/thermals

Squadron is structured worker/RPC infrastructure, not a generic wrapper around every Future.

Non-negotiable rules

1. Measure before offloading.
2. Use workers mainly for meaningful CPU-bound or long-running isolated work.
3. Do not offload ordinary HTTP, socket, storage, or timer waits merely because they are asynchronous.
4. Measure total worker cost, including startup, marshaling, transfer, queue wait, compute, and result handling.
5. Treat every worker method as a serialization boundary API.
6. Keep messages compact and task APIs coarse-grained.
7. Batch tiny operations rather than issuing thousands of RPC calls.
8. Reuse persistent workers when recurring work justifies startup amortization.
9. Use a pool only when true parallel throughput is needed.
10. Bound maxWorkers; do not unintentionally leave CPU burst workloads unbounded.
11. For CPU-heavy pool tasks, default to maxParallel: 1 unless measurement and semantics prove otherwise.
12. Do not set pool size mechanically to processor count.
13. Preserve CPU headroom for Flutter UI/raster work and the operating system.
14. Keep worker computation pure and platform-independent where practical.
15. Never pass BuildContext, Widgets, RenderObjects, controllers, or other UI/runtime objects across workers.
16. Verify any Flutter plugin used from workers explicitly supports the required background-isolate/platform behavior.
17. Use supported wire types or explicit SquadronMarshalers for custom DTOs.
18. Do not claim zero-copy unless the exact platform/type path truly provides transfer semantics.
19. Use cooperative cancellation when expensive running CPU work must actually stop.
20. Reject stale results even when cancellation exists.
21. Treat one worker's async methods as potentially interleaving across await points.
22. Do not assume pool calls hit the same worker; use a dedicated worker or pool.execute() for state affinity.
23. Own worker/pool lifecycle explicitly and call stop().
24. Build and deploy web worker artifacts explicitly; native success does not prove web correctness.
25. Optimize user responsiveness, memory, battery, and thermals—not just raw throughput.