running-flutter-isolates

Flutter Isolate

Goal

Move heavy computations off the main isolate to prevent UI jank (>16ms frame gaps), using the simplest API that fits the use case.

Decision: Which API to Use?

Use compute() when:	Use Isolate.spawn() when:
✅ One-off computation	✅ Long-lived worker needed
✅ Simple serializable data	✅ Multiple messages over time
✅ Auto-cleanup desired	✅ Custom messaging protocol
✅ Web compatibility required	✅ Avoid repeated spawn overhead
❌ NOT for long-running tasks	❌ NOT for single one-shot tasks

Additional Scenarios	API
One-shot, single return value (Dart 2.19+)	Isolate.run()
Need platform plugins in background	BackgroundIsolateBinaryMessenger

---

1. Short-lived Isolate: Isolate.run()

Best for single, one-off computations. The isolate spawns, runs the task, returns the value, then shuts down automatically.

// Decode a large JSON file without blocking the UI thread
Future<List<Photo>> getPhotos() async {
  // Load asset on the main isolate first (rootBundle not accessible in isolate)
  final String jsonString = await rootBundle.loadString('assets/photos.json');

  // Offload CPU-heavy decoding to a new isolate
  final List<Photo> photos = await Isolate.run<List<Photo>>(() {
    final List<Object?> photoData = jsonDecode(jsonString) as List<Object?>;
    return photoData.cast<Map<String, Object?>>().map(Photo.fromJson).toList();
  });

  return photos;
}

Key behavior: The result is transferred (not copied) back to the main isolate via Isolate.exit internally — zero-copy for the return value.

---

2. Cross-platform: compute()

compute() is Flutter's wrapper that falls back gracefully on Flutter Web (runs on the main thread there, since web doesn't support isolates).

// Equivalent to Isolate.run on mobile/desktop, runs on main thread on web
Future<List<Photo>> getPhotos(String jsonString) async {
  return compute(_parsePhotos, jsonString);
}

// Top-level or static function only — closures are NOT supported by compute()
List<Photo> _parsePhotos(String jsonString) {
  final data = jsonDecode(jsonString) as List<Object?>;
  return data.cast<Map<String, Object?>>().map(Photo.fromJson).toList();
}