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

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

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

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

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

import 'dart:async';

Future

Объект Future представляет собой вычисление, результат которого может быть ещё недоступен. Future возвращает значение вычисления, когда оно завершается в какой-то момент в будущем. Future часто используются для потенциально длительных вычислений, таких как I/O и взаимодействие с пользователями.

Многие методы в библиотеках 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 в обзоре библиотек: краткий обзор асинхронного программирования.

• Использование Future-основанных API: более подробный взгляд на 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?

@Since("2.8")

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

scheduleMicrotask(void callback()) → void

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

unawaited(Future<void>? future) → void

@Since("2.15")

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

Типы данных

ControllerCallback = void Function()

Тип обратного вызова контроллера потока данных, onListen, onPause и onResume.

ControllerCancelCallback = FutureOr<void> Function()

Тип обратного вызова отмены контроллера потока данных. 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 arg1, T2 arg2)

ZoneCallback<R> = R Function()

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

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

AsyncError

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

DeferredLoadException

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

TimeoutException

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