dart:async

Future абстрактный класс

Объект, представляющий отложенное вычисление.

Future используется для представления потенциального значения или ошибки, которые будут доступны в будущем. Получатели Future могут регистрировать обратные вызовы, которые обрабатывают значение или ошибку, как только они станут доступны. Например:

Future<int> future = getFuture();
future.then((value) => handleValue(value))
      .catchError((error) => handleError(error));

Future может завершиться двумя способами: со значением («будущее выполняется успешно») или с ошибкой («будущее завершается с ошибкой»). Пользователи могут установить обратные вызовы для каждого случая. Результатом регистрации пары обратных вызовов является новый Future («преемник»), который в свою очередь завершается результатом вызова соответствующего обратного вызова. Преемник завершается с ошибкой, если вызванный обратный вызов вызывает исключение. Например:

Future<int> successor = future.then((int value) {
    // Invoked when the future is completed with a value.
    return 42;  // The successor is completed with the value 42.
  },
  onError: (e) {
    // Invoked when the future is completed with an error.
    if (canHandle(e)) {
      return 499;  // The successor is completed with the value 499.
    } else {
      throw e;  // The successor is completed with the error e.
    }
  });

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

var future = getFuture();
new Timer(new Duration(milliseconds: 5), () {
  // The error-handler is not attached until 5 ms after the future has
  // been received. If the future fails before that, the error is
  // forwarded to the global error-handler, even though there is code
  // (just below) to eventually handle the error.
  future.then((value) { useValue(value); },
              onError: (e) { handleError(e); });
});

При регистрации обратных вызовов часто удобнее зарегистрировать два обратных вызова отдельно, сначала используя then с одним аргументом (обработчик значения) и используя второй catchError для обработки ошибок. Каждый из них будет пересылать результат, который они не обрабатывают, своим преемникам, и вместе они обрабатывают как результат значения, так и результат ошибки. Это также имеет дополнительное преимущество в том, что catchError обрабатывает ошибки в обратном вызове then. Использование последовательных обработчиков вместо параллельных часто приводит к более легко читаемому коду. Это также делает асинхронный код очень похожим на синхронный код:

// Synchronous code.
try {
  int value = foo();
  return bar(value);
} catch (e) {
  return 499;
}

Эквивалентный асинхронный код, основанный на futures:

Future<int> future = new Future(foo);  // Result of foo() as a future.
future.then((int value) => bar(value))
      .catchError((e) => 499);

Подобно синхронному коду, обработчик ошибок (зарегистрированный с помощью catchError) обрабатывает любые ошибки, выброшенные либо foo или bar. Если обработчик ошибок был зарегистрирован как параметр onError вызова then, он не поймал бы ошибки из вызова bar.

Future может иметь более одной пары обратных вызовов. Каждый преемник обрабатывается независимо и обрабатывается так, как будто это единственный преемник.

Future также может не завершиться никогда. В этом случае никакие обратные вызовы не вызываются.

Статические методы

any<T>(Iterable<Future<T>> futures) → Future<T>

Возвращает результат первого будущего в futures для завершения.

doWhile(dynamic f()) → Future

Повторяет операцию до тех пор, пока она не вернёт false.

forEach<T>(Iterable<T> input, dynamic f(T element)) → Future

Выполняет операцию для каждого элемента итерируемого объекта.

wait<T>(Iterable<Future<T>> futures, { bool eagerError: false, void cleanUp(T successValue) }) → Future<List<T>>

Ожидает завершения всех заданных futures и собирает их значения.

Конструкторы

Future(dynamic computation())

factory

Создает будущее, содержащее результат вызова computation асинхронно с помощью Timer.run.

Future.delayed(Duration duration, [ dynamic computation() ])

factory

Создает будущее, которое выполняет вычисление после задержки.

Future.error(Object error, [ StackTrace stackTrace ])

factory

Future, который завершается с ошибкой в следующей итерации цикла событий.

Future.microtask(dynamic computation())

factory

Создает будущее, содержащее результат вызова computation асинхронно с помощью scheduleMicrotask.

Future.sync(dynamic computation())

factory

Возвращает будущее, содержащее результат немедленного вызова computation.

Future.value([result ])

factory

Future, чьё значение доступно в следующей итерации цикла событий.

Свойства

hashCode → int

только для чтения, унаследованное

Хэш-код этого объекта.

runtimeType → Type

только для чтения, унаследованное

Представление типа объекта в момент выполнения.

Операторы

operator ==(other) → bool

унаследованное

Оператор равенства.

Методы

asStream() → Stream<T>

Создаёт Stream, содержащий результат этого будущего.

catchError(Function onError, { bool test(Object error) }) → Future<T>

Обрабатывает ошибки, испускаемые этим Future.

then<S>(dynamic onValue(T value), { Function onError }) → Future<S>

Регистрирует обратные вызовы, которые будут вызваны, когда это будущее завершится.

timeout(Duration timeLimit, { dynamic onTimeout() }) → Future<T>

Останавливает вычисление будущего после истечения timeLimit.

whenComplete(dynamic action()) → Future<T>

Регистрирует функцию, которая будет вызвана, когда это будущее завершится.

noSuchMethod(Invocation invocation) → dynamic

унаследованное

Вызывается при обращении к несуществующему методу или свойству.

toString() → String

унаследованное

Возвращает строковое представление этого объекта.