dart:cli

Функция waitFor<T>

Приостанавливает стек, выполняет микрозадачи и обрабатывает входящие события до тех пор, пока future не завершится.

Уведомление о устаревании

Функциональность waitFor устарела. Она была предназначена для решения конкретной проблемы в существующем коде, возникшей из-за изменения API платформных библиотек. Функция waitFor не подходит для общего использования. У неё есть недостатки, которые могут повлиять на другой код, выполняющийся в том же изоляте, включая:

• Вызов функции, который выглядит синхронным, может привести к выполнению других асинхронных событий до его возврата. Синхронный код, как правило, может этого не ожидать, и некоторый код может быть написан, полагаясь на это предположение. Такой код может потерпеть неудачу непредсказуемым образом.
• Многократные вложенные вызовы waitFor могут блокировать друг друга, так как самый последний вызов всегда должен завершиться перед завершением любого другого. Необходимо разумное использование waitFor для предотвращения неожиданных тупиков, чего не произойдёт при использовании await вместо него. Если более одной библиотеки в одной программе использует waitFor, то трудно избежать или контролировать, произойдёт ли такое блокирование.

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

Семантика вызова

Этот вызов выполняет следующие действия:

• Пока future не завершится:
  • приостанавливает текущий стек выполнения,
  • выполняет очередь микрозадач до тех пор, пока она не станет пустой,
  • ждет, пока очередь сообщений не станет непустой,
  • обрабатывает сообщения в очереди сообщений, плюс связанные с ними микрозадачи, пока очередь сообщений не станет пустой,
  • восстанавливает исходный стек.

Эта функция нарушает обычное обещание семантики Dart, что обработчики сообщений и микрозадачи выполняются до завершения следующего обработчика сообщений или микрозадачи. Особенно следует отметить, что использование этой функции в блоке finally позволит микрозадачам и обработчикам сообщений выполняться до завершения всех блоков finally для исключения, что, возможно, нарушит инварианты в вашей программе.

Использование этой функции следует рассматривать как крайнюю меру, когда невозможно полностью преобразовать программу Dart в асинхронный стиль с помощью async и await.

Если Future завершается нормально, возвращается её результат. Если Future завершается с ошибкой, ошибка и стек вызовов упаковываются в AsyncError и выбрасываются. Если микрозадача или обработчик сообщений во время этого вызова приводят к необработанному исключению, это исключение будет распространено так, как будто микрозадача или обработчик сообщений были единственным вызовом Dart в стеке. То есть, необработанные исключения в микрозадаче или обработчике сообщений пропустят приостановленные в вызове waitFor стеки.

Если необязательный параметр timeout передан, waitFor выбрасывает TimeoutException, если Future не завершается в течение указанного периода.

Вызовы waitFor могут быть вложенными. Более ранние вызовы не завершатся до завершения последующих, но завершение последующего вызова заставит предыдущий вызов проснуться и проверить свой Future на завершение.

Пожалуйста, будьте осторожны, так как вложение вызовов waitFor может привести к тупику, если последующие вызовы заблокируют ожидание условия, которое выполняется только при возврате более раннего вызова.

Реализация

@Deprecated(
    "This functionality is incomplete and may be removed in a later version")
T waitFor<T>(Future<T> future, {Duration? timeout}) {
  late T result;
  bool futureCompleted = false;
  Object? error;
  StackTrace? stacktrace;
  future.then((T r) {
    futureCompleted = true;
    result = r;
  }, onError: (e, st) {
    error = e;
    stacktrace = st;
  });

  late Stopwatch s;
  if (timeout != null) {
    s = new Stopwatch()..start();
  }
  Timer.run(() {}); // Ensure there is at least one message.
  while (!futureCompleted && (error == null)) {
    Duration? remaining;
    if (timeout != null) {
      if (s.elapsed >= timeout) {
        throw new TimeoutException("waitFor() timed out", timeout);
      }
      remaining = timeout - s.elapsed;
    }
    _WaitForUtils.waitForEvent(timeout: remaining);
  }
  if (timeout != null) {
    s.stop();
  }
  Timer.run(() {}); // Ensure that previous calls to waitFor are woken up.

  if (error != null) {
    throw new AsyncError(error!, stacktrace);
  }

  return result;
}