A programação assíncrona é algo que certamente está presente no dia-a-dia de todo desenvolvedor e necessitamos frequentemente gerenciar Futures.

E é bem simples, na verdade, controlar o fluxo de uma Future para garantir que não executemos a Future antes de um código que dependa de seu resultado quando executamos a partir de uma interação do usuário, entretanto as vezes essa execução foge um pouco de nosso controle. Mas calma, no Dart existe com Completers e serve justamente para esses casos.

O Completer é uma forma de executar Futures, que podem ser completadas ou disparar um error, e gerencia-las manualmente. O Completer te dará uma maior flexibilidade no controle das Futures.

No Completer teremos 5 propriedades importantes0

/// INICIALIZAÇÃO	
final Completer<T> completer = Completer<T>();

/// RETORNA O FUTURO EM EXECÃO
final Future<T> future = completer.future;

/// RETORNA SE O FUTURO FOI CONCLUÍDO
bool completer.isCompleted

/// COMPLETA O FUTURO COM UM VALOR
completer.complete(...);

// COMPLETA O FUTURO COM UM ERRO
completer.completeError(...);

Então para usarmos o Completer podemos executar o complete(T) para quando queremos completar com sucesso e o .completeError(Object) quando queremos completar com algum error.

Future<String> fetchData() async {
  final completer = Completer<String>();
  try {
    await Future.delayed(
        const Duration(seconds: 2)); // Simulating network latency

    completer.complete('Data fetched successfully');
  } on Exception {
    completer.completeError('Data fetched successfully');
  }

  return completer.future;
}

A partir dai conseguimos utilizar a Future normalmente

Um exemplo pratico que podemos fazer é a de criar um Timeout para chamada de uma API, no exemplo a seguir estou simulando a chamada em uma API que demora 5 segundos e configurei um Timeout de 3 segundos.

E o Resultado será

Se eu mudar o timeout para 10 segundos obterei

Agora imagine que necessitemos executar alguma função assíncrona no construtor de uma classe, como por exemplo, iremos utilizar o Hive e necessitamos abrir o box no construtor para que utilizemos nos outros métodos.

class HiveRepository {
  late final Box<Map<String, dynamic>> box;
  HiveRepository(String boxName) {
    _init(boxName);
  }

  _init(String boxName) async {
    if (completer.isCompleted) return;

    try {
      final directory = await getApplicationDocumentsDirectory();

      Hive.init('${directory.path}/$boxName.db.hive');

      box = await Hive.openBox<Map<String, dynamic>>(boxName);
    } catch (e) {
      throw Exception(e);
    }
  }

  add(Map<String, dynamic> item) async {
    await box.add(item);
  }

  Future<List<Map<String, dynamic>>> getAll() async {
    return box.values.toList();
  }
}

O problema dessa abordagem é que não conseguimos controlar o fluxo de execução das Futures e não conseguimos garantir que o _init() seja executado antes do add() por exemplo.

Dai que entra os completers, utilizando o Completer conseguimos facilmente garantir que o box do Hive está aberto antes de chamarmos o add() ou até mesmo o values.

class HiveRepository {
  late final Box<Map<String, dynamic>> box;
  final completer = Completer<Box<Map<String, dynamic>>>();

  HiveRepository(String boxName) {
    _init(boxName);
  }

  _init(String boxName) async {
    if (completer.isCompleted) return;

    try {
      final directory = await getApplicationDocumentsDirectory();

      Hive.init('${directory.path}/$boxName.db.hive');

      var box = await Hive.openBox<Map<String, dynamic>>(boxName);
      box.clear();
      completer.complete(box);
    } catch (e) {
      completer.completeError(e);
    }
  }

  add(Map<String, dynamic> item) async {
    final box = await completer.future;
    await box.add(item);
  }

  Future<List<Map<String, dynamic>>> getAll() async {
    final box = await completer.future;
    return box.values.toList();
  }
}

E para utilizarmos basta criar uma instancia do repositório e chamar os métodos add() e getAl()

Press enter or click to view image in full size

Legal, ne? Essa abordagem eu utilizo bastante quando crio uma adaptação do Hive por exemplo e preciso registrar no meu gerenciador de injeção de dependência como o getIt e o modular, é uma forma muito eficaz de trabalhar