andrelucassvt/flutter-isolates

Flutter Isolates — Skill Especializado

Princípio Central

Isolate não é padrão — é otimização pontual. async/await resolve ~90% dos casos. Isolate só se justifica quando há trabalho CPU-intensivo que está causando (ou pode causar) jank na UI.

---

1. Critério de Decisão — Usar ou Não Usar?

Sempre responda essa pergunta antes de sugerir Isolate:

A tarefa bloqueia a thread por mais de ~4ms?
         |
        NÃO → async/await é suficiente
         |
        SIM → É trabalho de I/O (rede, disco)?
                   |
                  SIM → async/await é suficiente (já é não-bloqueante)
                   |
                  NÃO → É cálculo CPU-intensivo?
                              |
                             SIM → Use Isolate ✅

✅ Casos onde Isolate FAZ sentido

| Situação | Exemplo concreto | |---|---| | JSON grande (> ~1MB) | Parsear resposta de API volumosa | | Criptografia / hashing | bcrypt, SHA em loop | | Compressão | gzip de arquivos grandes | | Processamento de imagem | Filtros manuais, resize sem lib nativa | | Algoritmos pesados | Pathfinding, simulações, ML local | | Parsing de arquivos | CSV/XML grande linha a linha |

❌ Casos onde Isolate NÃO faz sentido

| Situação | Por quê não | |---|---| | Chamadas HTTP | http.get() já é async, não bloqueia | | Queries ao banco (sqflite, Drift) | I/O assíncrono por natureza | | Leitura de arquivo pequeno | File.readAsString() é async | | Cálculos simples | Overhead do Isolate > tempo da tarefa | | Atualizar estado / chamar setState | Impossível — Isolate não acessa UI |

---

2. APIs disponíveis — Quando usar cada uma

compute() — Mais simples, uso mais comum

// Ideal para: tarefa única, sem comunicação contínua
// Restrição: a função DEVE ser top-level ou static

import 'package:flutter/foundation.dart';

// ✅ Top-level — obrigatório
List<Produto> _parsearProdutos(String jsonStr) {
  final lista = jsonDecode(jsonStr) as List;
  return lista.map((e) => Produto.fromJson(e)).toList();
}

// Na UI:
final produtos = await compute(_parsearProdutos, responseBody);

Quando preferir: tarefa pontual, sem necessidade de progresso ou múltiplas mensagens.

---

Isolate.run() — Flutter 3+ / Dart 2.19+

// Mais moderno que compute(), sintaxe mais limpa
import 'dart:isolate';

final resultado = await Isolate.run(() {
  // código pesado aqui
  return _processarDados(dados);
});

Quando preferir: mesmos casos que compute(), mas com sintaxe mais ergonômica.

---

Isolate.spawn + SendPort/ReceivePort — Controle total

// Ideal para: comunicação contínua, progresso, múltiplas mensagens
import 'dart:isolate';

Future<void> processarComProgresso(List<int> dados) async {
  final receivePort = ReceivePort();

  await Isolate.spawn(_worker, receivePort.sendPort);

  // Recebe SendPort do worker para comunicação bidirecional
  final workerPort = await receivePort.first as SendPort;
  final respostaPort = ReceivePort();

  workerPort.send({'dados': dados, 'reply': respostaPort.sendPort});

  await for (final msg in respostaPort) {
    if (msg is double) {
      print('Progresso: ${(msg * 100).toStringAsFixed(0)}%');
    } else if (msg is List<int>) {
      print('Concluído: $msg');
      break;
    }
  }
}

// Roda no Isolate separado
void _worker(SendPort mainPort) async {
  final port = ReceivePort();
  mainPort.send(port.sendPort);

  await for (final msg in port) {
    final dados = msg['dados'] as List<int>;
    final reply = msg['reply'] as SendPort;
    final resultado = <int>[];

    for (int i = 0; i < dados.length; i++) {
      resultado.add(dados[i] * 2);
      if (i % 100 == 0) {
        reply.send(i / dados.length); // progresso
      }
    }

    reply.send(resultado); // resultado final
  }
}

Quando preferir: precisa de progresso em tempo real, múltiplas tarefas no mesmo Isolate, ou ciclo de vida longo.

---

3. Limitações importantes — Sempre mencionar

• Sem acesso ao contexto Flutter: Isolates não podem chamar setState, BuildContext, Provider, Riverpod, etc.
• Memória isolada: objetos são copiados ao serem enviados, não compartilhados. Exceto TransferableTypedData.
• Sem plugins nativos (em geral): a maioria dos plugins usa platform channels que só funcionam na main isolate.
• Overhead de criação: criar um Isolate leva alguns milissegundos — não compensa para tarefas rápidas.
• Sem acesso a singletons: instâncias como SharedPreferences, Hive, etc. precisam ser reinicializadas dentro do Isolate.

---

4. Como identificar se precisa de Isolate

Via Flutter DevTools (método correto)

1. Rode o app em profile mode: flutter run --profile
2. Abra Flutter DevTools → aba Performance
3. Procure frames acima de 16ms (60fps) ou 8ms (120fps)
4. Se o tempo alto é em UI thread (não GPU), é candidato para Isolate

Sinal de alerta no código

// 🚨 Isso PROVAVELMENTE vai causar jank:
void _aoClicar() {
  final resultado = jsonDecode(respostaGigante); // síncrono, pesado
  setState(() => _itens = resultado);
}

// ✅ Correto:
void _aoClicar() async {
  final resultado = await compute(jsonDecode, respostaGigante);
  setState(() => _itens = resultado);
}

---

5. Padrão recomendado para produção

Para apps reais, encapsule o Isolate em um serviço:

class ProcessamentoService {
  // Reutiliza o mesmo Isolate para múltiplas tarefas
  Isolate? _isolate;
  SendPort? _sendPort;

  Future<void> inicializar() async {
    final receivePort = ReceivePort();
    _isolate = await Isolate.spawn(_entryPoint, receivePort.sendPort);
    _sendPort = await receivePort.first;
  }

  Future<T> executar<T>(Map<String, dynamic> tarefa) async {
    final replyPort = ReceivePort();
    _sendPort!.send({...tarefa, 'reply': replyPort.sendPort});
    return await replyPort.first as T;
  }

  void dispose() {
    _isolate?.kill(priority: Isolate.immediate);
  }

  static void _entryPoint(SendPort mainPort) async {
    final port = ReceivePort();
    mainPort.send(port.sendPort);
    await for (final msg in port) {
      // processar tarefas
    }
  }
}

---

6. Tabela resumo de escolha de API

| Necessidade | API recomendada | |---|---| | Tarefa simples e pontual | compute() | | Tarefa simples, Dart 2.19+ | Isolate.run() | | Progresso em tempo real | Isolate.spawn + ReceivePort | | Isolate de longa vida / reutilizável | Isolate.spawn com loop | | Worker pool (múltiplos paralelos) | Pacote worker_manager ou flutter_isolate |

---

7. Packages úteis (mencionar quando relevante)

• worker_manager — pool de Isolates reutilizáveis
• flutter_isolate — Isolate com suporte a plugins nativos
• isolate_handler — abstração de alto nível

---

Checklist ao responder sobre Isolates

• [ ] Verificar se o caso realmente justifica Isolate (usar critério da seção 1)
• [ ] Se não justifica, explicar por quê e mostrar a alternativa correta
• [ ] Se justifica, indicar qual API é mais adequada (seção 2)
• [ ] Mencionar limitações relevantes para o contexto (seção 3)
• [ ] Código de exemplo com função top-level ou static quando usar compute()

---

Última atualização: 28 de março de 2026