Programação assíncrona

As bibliotecas Dart são repletas de funções que retornam objetos Future ou Stream. Essas funções são assíncronas: elas retornam após configurar uma operação possivelmente demorada (como I/O), sem aguardar a conclusão dessa operação.

As keywords async e await suportam programação assíncrona, permitindo que você escreva código assíncrono que se parece com código síncrono.

Quando você precisa do resultado de um Future concluído, você tem duas opções:

• Use async e await, conforme descrito aqui e no tutorial de programação assíncrona.
• Use a API Future, conforme descrito na documentação dart:async.

O código que usa async e await é assíncrono, mas parece muito com código síncrono. Por exemplo, aqui está algum código que usa await para aguardar o resultado de uma função assíncrona:

await lookUpVersion();

Para usar await, o código deve estar em uma função async—uma função marcada como async:

Future<void> checkVersion() async {
  var version = await lookUpVersion();
  // Do something with version
}

Use try, catch e finally para lidar com erros e limpeza em código que usa await:

try {
  version = await lookUpVersion();
} catch (e) {
  // React to inability to look up the version
}

Você pode usar await várias vezes em uma função async. Por exemplo, o código a seguir aguarda três vezes pelos resultados de funções:

var entrypoint = await findEntryPoint();
var exitCode = await runExecutable(entrypoint, args);
await flushThenExit(exitCode);

Em await expression, o valor de expression geralmente é um Future; se não for, então o valor é automaticamente encapsulado em um Future. Este objeto Future indica uma promessa de retornar um objeto. O valor de await expression é esse objeto retornado. A expressão await faz a execução pausar até que esse objeto esteja disponível.

Se você receber um erro de compilação ao usar await, certifique-se de que await está em uma função async. Por exemplo, para usar await na função main() do seu aplicativo, o corpo de main() deve ser marcado como async:

void main() async {
  checkVersion();
  print('In main: version is ${await lookUpVersion()}');
}

Para uma introdução interativa ao uso de futures, async e await, veja o tutorial de programação assíncrona.

Uma função async é uma função cujo corpo é marcado com o modificador async.

Adicionar a keyword async a uma função faz com que ela retorne um Future. Por exemplo, considere esta função síncrona, que retorna uma String:

String lookUpVersion() => '1.0.0';

Se você mudá-la para ser uma função async—por exemplo, porque uma implementação futura será demorada—o valor retornado é um Future:

Future<String> lookUpVersion() async => '1.0.0';

Observe que o corpo da função não precisa usar a API Future. Dart cria o objeto Future se necessário. Se sua função não retorna um valor útil, torne seu tipo de retorno Future<void>.

Para uma introdução interativa ao uso de futures, async e await, veja o tutorial de programação assíncrona.

Quando você precisa obter valores de um Stream, você tem duas opções:

• Use async e um loop for assíncrono (await for).
• Use a API Stream, conforme descrito na documentação dart:async.

Um loop for assíncrono tem a seguinte forma:

await for (varOrType identifier in expression) {
  // Executes each time the stream emits a value.
}

O valor de expression deve ter tipo Stream. A execução procede da seguinte forma:

1. Aguarde até que o stream emita um valor.
2. Execute o corpo do loop for, com a variável definida para esse valor emitido.
3. Repita 1 e 2 até que o stream seja fechado.

Para parar de escutar o stream, você pode usar uma instrução break ou return, que sai do loop for e cancela a inscrição no stream.

Se você receber um erro de compilação ao implementar um loop for assíncrono, certifique-se de que o await for está em uma função async. Por exemplo, para usar um loop for assíncrono na função main() do seu aplicativo, o corpo de main() deve ser marcado como async:

void main() async {
  // ...
  await for (final request in requestServer) {
    handleRequest(request);
  }
  // ...
}

Para mais informações sobre o suporte de programação assíncrona do Dart, consulte a documentação da biblioteca dart:async.