Библиотека dart:async

Поддержка асинхронного программирования с помощью таких классов, как Future и Stream.

Future и Stream — основные строительные блоки асинхронного программирования в Dart. Они поддерживаются непосредственно в языке с помощью функций async и async* и доступны во всех библиотеках через библиотеку dart:core.

Эта библиотека предоставляет дополнительные инструменты для создания, использования и преобразования объектов Future и Stream, а также прямой доступ к другим асинхронным примитивам, таким как Timer, scheduleMicrotask и Zone.

Чтобы использовать эту библиотеку в коде:

import 'dart:async';

Future

Объект Future представляет вычисление, результат которого может быть ещё недоступен. Future возвращает результат вычисления, когда оно завершается в некоторый момент в будущем. Объекты Future часто используются в API, реализованных с помощью другого потока или изолята (например, для асинхронных операций ввода-вывода в dart:io или HTTP-запросов в dart:html).

Многие методы библиотек Dart возвращают объекты Future при выполнении задач. Например, при привязке HttpServer к хосту и порту метод bind() возвращает Future.

HttpServer.bind('127.0.0.1', 4444)
     .then((server) => print('${server.isBroadcast}'))
     .catchError(print);

Future.then регистрирует функцию обратного вызова, которая выполняется после успешного завершения операции Future — в данном случае метода bind(). Значение, возвращённое операцией, передаётся функции обратного вызова. В этом примере метод bind() возвращает объект HttpServer. Функция обратного вызова выводит одно из его свойств. Future.catchError регистрирует функцию обратного вызова, которая выполняется при возникновении ошибки в Future.

Stream

Stream предоставляет асинхронную последовательность данных. Примеры таких последовательностей — отдельные события, например щелчки мышью, или последовательные фрагменты больших объёмов данных, например несколько списков байтов с содержимым файла. В следующем примере файл открывается для чтения. Stream.listen регистрирует функции обратного вызова, которые выполняются каждый раз, когда становятся доступны новые данные, происходит ошибка или завершается поток. Дополнительные возможности доступны в Stream и реализованы посредством вызова Stream.listen для получения фактических данных.

Stream<List<int>> stream = File('quotes.txt').openRead();
stream.transform(utf8.decoder).forEach(print);

Этот поток выдаёт последовательность списков байтов. Затем программа должна каким-либо образом обработать эти списки байтов. Здесь код использует декодер UTF-8 (предоставляемый библиотекой dart:convert), чтобы преобразовать последовательность байтов в последовательность строк Dart.

Ещё один распространённый вариант использования потоков — события, создаваемые пользователями в веб-приложении. Следующий код отслеживает щелчки мышью по кнопке.

querySelector('#myButton')!.onClick.forEach((_) => print('Click.'));

Другие ресурсы

• Раздел dart:async в обзоре библиотек: краткий обзор асинхронного программирования.

• Использование API на основе Future: подробный разбор объектов Future и их применения для написания асинхронного кода Dart.

• Future и обработка ошибок: всё, что вы хотели знать об обработке ошибок и исключений при работе с Future (но боялись спросить).

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

• Пакет test: асинхронные тесты: как тестировать асинхронный код.

Классы

Completer<T>

Способ создавать объекты Future и позднее завершать их значением или ошибкой.

DeferredLibrary

Указывает, что загрузка libraryName отложена.

EventSink<T>

Sink, поддерживающий добавление ошибок.

Future<T>

Результат асинхронного вычисления.

FutureOr<T>

Тип, представляющий значения, которые являются либо Future<T>, либо T.

MultiStreamController<T>

Расширенный контроллер потока, предоставляемый методом Stream.multi.

Stream<T>

Источник асинхронных событий данных.

StreamConsumer<S>

Абстрактный интерфейс для «приёмника», принимающего несколько потоков целиком.

StreamController<T>

Контроллер и управляемый им поток.

StreamIterator<T>

Интерфейс, подобный Iterator, для значений Stream.

StreamSink<S>

Объект, принимающий события потока как синхронно, так и асинхронно.

StreamSubscription<T>

Подписка на события из Stream.

StreamTransformer<S, T>

Преобразует Stream.

StreamTransformerBase<S, T>

Базовый класс для реализации StreamTransformer.

StreamView<T>

Обёртка для Stream, предоставляющая только интерфейс Stream.

SynchronousStreamController<T>

Контроллер потока, который доставляет события синхронно.

Timer

Таймер обратного отсчёта, который можно настроить на однократное или повторяющееся срабатывание.

Zone

Зона представляет среду, остающуюся неизменной при асинхронных вызовах.

ZoneDelegate

Адаптированное представление родительской зоны.

ZoneSpecification

Объект параметров с пользовательскими обработчиками функций зоны для Zone.fork.

Расширения

FutureExtensions

Вспомогательные методы для объектов Future.

Функции

runZoned<R>(R body(), {Map<Object?, Object?>? zoneValues, ZoneSpecification? zoneSpecification, Function? onError}) → R

Выполняет body в собственной зоне.

runZonedGuarded<R>(R body(), void onError(Object error, StackTrace stack), {Map<Object?, Object?>? zoneValues, ZoneSpecification? zoneSpecification}) → R?

Выполняет body в собственной зоне обработки ошибок.

scheduleMicrotask(void callback()) → void

Выполняет функцию асинхронно.

unawaited(Future<void>? future) → void

Явно игнорирует Future.

Псевдонимы типов

ControllerCallback = void Function()

Тип callback-функций контроллера потока: onListen, onPause и onResume.

ControllerCancelCallback = FutureOr<void> Function()

Тип callback-функций onCancel контроллера потока.

CreatePeriodicTimerHandler = Timer Function(Zone self, ZoneDelegate parent, Zone zone, Duration period, void f(Timer timer))

Тип пользовательской функции реализации Zone.createPeriodicTimer.

CreateTimerHandler = Timer Function(Zone self, ZoneDelegate parent, Zone zone, Duration duration, void f())

Тип пользовательской функции реализации Zone.createTimer.

ErrorCallbackHandler = AsyncError? Function(Zone self, ZoneDelegate parent, Zone zone, Object error, StackTrace? stackTrace)

Тип пользовательской функции реализации Zone.errorCallback.

ForkHandler = Zone Function(Zone self, ZoneDelegate parent, Zone zone, ZoneSpecification? specification, Map<Object?, Object?>? zoneValues)

Тип пользовательской функции реализации Zone.fork.

HandleUncaughtErrorHandler = void Function(Zone self, ZoneDelegate parent, Zone zone, Object error, StackTrace stackTrace)

Тип пользовательской функции реализации Zone.handleUncaughtError.

PrintHandler = void Function(Zone self, ZoneDelegate parent, Zone zone, String line)

Тип пользовательской функции реализации Zone.print.

RegisterBinaryCallbackHandler = ZoneBinaryCallback<R, T1, T2> Function<R, T1, T2>(Zone self, ZoneDelegate parent, Zone zone, R f(T1 arg1, T2 arg2))

Тип пользовательской функции реализации Zone.registerBinaryCallback.

RegisterCallbackHandler = ZoneCallback<R> Function<R>(Zone self, ZoneDelegate parent, Zone zone, R f())

Тип пользовательской функции реализации Zone.registerCallback.

RegisterUnaryCallbackHandler = ZoneUnaryCallback<R, T> Function<R, T>(Zone self, ZoneDelegate parent, Zone zone, R f(T arg))

Тип пользовательской функции реализации Zone.registerUnaryCallback.

RunBinaryHandler = R Function<R, T1, T2>(Zone self, ZoneDelegate parent, Zone zone, R f(T1 arg1, T2 arg2), T1 arg1, T2 arg2)

Тип пользовательской функции реализации Zone.runBinary.

RunHandler = R Function<R>(Zone self, ZoneDelegate parent, Zone zone, R f())

Тип пользовательской функции реализации Zone.run.

RunUnaryHandler = R Function<R, T>(Zone self, ZoneDelegate parent, Zone zone, R f(T arg), T arg)

Тип пользовательской функции реализации Zone.runUnary.

ScheduleMicrotaskHandler = void Function(Zone self, ZoneDelegate parent, Zone zone, void f())

Тип пользовательской функции реализации Zone.scheduleMicrotask.

ZoneBinaryCallback<R, T1, T2> = R Function(T1, T2)

ZoneCallback<R> = R Function()

ZoneUnaryCallback<R, T> = R Function(T)

Исключения / ошибки

AsyncError

Ошибка и трассировка стека.

DeferredLoadException

Выбрасывается, если не удаётся загрузить отложенную библиотеку.

TimeoutException

Выбрасывается, если во время ожидания асинхронного результата срабатывает запланированный тайм-аут.