dart:async

Класс SynchronousStreamController<T>

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

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

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

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

Единственное преимущество использования SynchronousStreamController перед обычным StreamController — уменьшение задержки. Используйте синхронную версию, только если это улучшение существенно и её применение безопасно. В противном случае используйте обычный контроллер потока, который всегда будет вести себя правильно для Stream и не приведёт к случайному нарушению работы другого кода.

События в синхронный контроллер следует добавлять только в самой последней части обработки исходного события. В этот момент добавление события в поток эквивалентно возврату в цикл событий и добавлению события в следующей микрозадаче.

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

Если событие добавлено в контексте, который заведомо не является другим событием, слушатель потока может получить это событие до того, как будет готов его обработать. Мы гарантируем, что после вызова Stream.listen события не будут поступать, пока не завершится код, вызвавший listen. Вызов add в ответ на вызов функции неизвестного происхождения может нарушить эту гарантию.

Callback onListen контроллера не является асинхронным событием, поэтому добавлять события в контроллер в callback-функции onListen всегда неправильно. События будут доставлены ещё до того, как слушатель получит подписку.

Синхронный контроллер широковещательного потока также имеет ограничение, которого нет у обычного контроллера потока: методы add, addError, close и addStream нельзя вызывать во время доставки события. То есть если callback подписки на поток контроллера вызывает любую из перечисленных выше функций, вызов завершится ошибкой. У широковещательного потока может быть несколько слушателей, и если событие добавляется синхронно, пока другое событие также находится в процессе добавления, последнее событие может достичь некоторых слушателей раньше первого. Чтобы этого избежать, нельзя добавлять событие, пока отправляется предыдущее. Это гарантирует, что событие будет полностью доставлено к моменту возврата из первого вызова add, addError или close, а последующие события будут доставлены в правильном порядке.

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

Добавление события в синхронный контроллер небroadcast-потока, пока обрабатывается другое событие, может привести к задержке второго события и к тому, что оно не будет доставлено синхронно. Пока это событие не будет доставлено, контроллер не будет работать синхронно.

Реализуемые типы

• StreamController<T>

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

SynchronousStreamController()

Свойства

done → Future

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

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

hashCode → int

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

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

hasListener → bool

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

Есть ли у Stream подписчик.

isClosed → bool

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

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

isPaused → bool

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

Нужно ли подписке буферизовать события.

onCancel ↔ (FutureOr<void> Function()?)

чтение / записьунаследовано

Callback, вызываемый при отмене подписки на поток.

onListen ↔ (void Function()?)

чтение / записьунаследовано

Callback, вызываемый при подписке на поток.

onPause ↔ (void Function()?)

чтение / записьунаследовано

Callback, вызываемый при приостановке потока.

onResume ↔ (void Function()?)

чтение / записьунаследовано

Callback, вызываемый при возобновлении потока.

runtimeType → Type

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

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

sink → StreamSink<T>

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

Возвращает представление этого объекта, предоставляющее только интерфейс StreamSink.

stream → Stream<T>

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

Поток, которым управляет этот контроллер.

Методы

add(T data) → void

переопределение

Добавляет событие в поток контроллера.

addError(Object error, [StackTrace? stackTrace]) → void

переопределение

Добавляет ошибку в поток контроллера.

addStream(Stream<T> source, {bool? cancelOnError}) → Future

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

Получает события из source и помещает их в поток этого контроллера.

close() → Future

переопределение

Закрывает поток контроллера.

noSuchMethod(Invocation invocation) → dynamic

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

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

toString() → String

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

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

Операторы

operator ==(Object other) → bool

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

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