Isolate Communication and Worker Pools

Isolates execute code in independent memory heaps with their own event loops. Use isolates to offload heavy CPU-bound computations without blocking Flutter's UI frame budget.

When to Use Isolates

• CPU-Heavy Tasks: Parsing large JSON payloads (>1 MB), image encoding/decoding, cryptography, compression, or complex data transformations.
• Synchronous FFI and SQLite: Native libraries and synchronous database operations (e.g., package:sqlite3 or heavy Drift batch operations) execute synchronously on the caller's thread and will block the Flutter UI thread. Run synchronous FFI databases in a dedicated background isolate (e.g., via drift/isolate.dart or NativeDatabase.createInBackground).
• Do NOT use isolates for: Ordinary asynchronous I/O (network requests, non-blocking dart:io reads, or simple data mapping) where Dart's event loop and OS threads already handle I/O without blocking the UI. Spawning isolates for simple async I/O introduces needless message-passing overhead.

Patterns

1. One-Shot Computations (Isolate.run)

Check the supported platforms and SDK constraints first. On native Dart/Flutter targets, use Isolate.run() for isolated, single-result tasks:

final processed = await Isolate.run(() => heavyTransform(rawData));

Flutter web does not support Dart isolates. compute() provides a cross-platform call shape, but executes on the main thread on web and therefore does not remove CPU jank there. For web CPU bottlenecks, measure and reduce or chunk the work, or use an explicitly supported web-worker integration when actual parallelism is required. Do not promise off-thread execution from a portable API alone. See Flutter's web isolate limitations.

• Closure must be top-level or static, or capture only sendable objects.
• Uncaught errors in the closure are propagated back to the calling isolate as asynchronous exceptions.

2. Long-Running Worker Pools (SendPort / ReceivePort)

When repeatedly dispatching tasks to avoid repeated isolate spawn overhead:

• Establish a bidirectional handshake using ReceivePort and SendPort.

• Pass a response port with each request message to correlate asynchronous replies.

• Implement explicit message typing (e.g., sealed class message protocol) for request/response contracts.

• Close ports and call isolate.kill(priority: Isolate.immediate) during lifecycle teardown.

• TransferableTypedData: For very large byte buffers, TransferableTypedData.fromList() copies bytes once into native unmanaged memory upon creation. Subsequent transfer across a SendPort is an $O(1)$ pointer move with zero serialization or message copy overhead. Once materialized by the receiver via .materialize(), ownership is transferred and the original transferable instance cannot be read again.

• Sendable Types: Primitives, null, boolean, numbers, strings, instances of SendPort, Capability, and lists/maps of sendable objects. Non-sendable types (such as open file handles, native pointers without wrappers, closures with non-transferable context) throw ArgumentError.

Error Propagation and Teardown

• Always attach an error listener (isolate.addErrorListener) or catch errors from Isolate.run.
• Clean up lingering worker isolates when the host feature or application terminates to prevent resource leaks.