dart:async

Completer<T>.sync конструктор

Асинхронно завершает будущее.

Этот конструктор следует избегать, если завершение будущего известно как конечный результат другой асинхронной операции. В случае сомнений используйте стандартный конструктор Completer.

Использование обычного, асинхронного, completer никогда не приведет к неправильному поведению, но неправильное использование синхронного completer может привести к ошибке в корректных программах.

Синхронный completer предназначен только для оптимизации распространения событий, когда одно асинхронное событие немедленно вызывает другое. Он не должен использоваться, если вызовы complete и completeError гарантированно выполняются в местах, где это не нарушит Future инварианты.

Синхронное завершение означает, что будущее completer будет завершено немедленно при вызове метода complete или completeError для синхронного completer, который также вызывает все зарегистрированные обратные вызовы на этом будущем.

Синхронное завершение не должно нарушать правило, что при добавлении обратного вызова к будущему, этот обратный вызов не должен вызываться до завершения кода, который добавил обратный вызов. По этой причине синхронное завершение должно происходить только в самом конце (в "хвостовой позиции") другого синхронного события, потому что в этот момент немедленное завершение будущего равнозначно возврату в цикл событий и завершению будущего в следующей микрозадаче.

Пример:

var completer = Completer.sync();
// The completion is the result of the asynchronous onDone event.
// No other operation is performed after the completion. It is safe
// to use the Completer.sync constructor.
stream.listen(print, onDone: () { completer.complete("done"); });

Плохой пример. Не используйте этот код. Только для иллюстративных целей:

var completer = Completer.sync();
completer.future.then((_) { bar(); });
// The completion is the result of the asynchronous onDone event.
// However, there is still code executed after the completion. This
// operation is *not* safe.
stream.listen(print, onDone: () {
  completer.complete("done");
  foo();  // In this case, foo() runs after bar().
});

Реализация

factory Completer.sync() => new _SyncCompleter<T>();