From 2829b2cfced306aac982c8d63a840dc51ad8d02f Mon Sep 17 00:00:00 2001 From: Nate Bosch Date: Tue, 9 May 2023 20:44:54 +0000 Subject: [PATCH] Mention non-sent Done event for paused listeners Closes #19095 The current doc implies that the future will complete before listeners have received the events, but a paused listener will instead block completion. Change-Id: Ic24ff9e46d269664f89c670eb60084821a824278 CoreLibraryReviewExempt: Doc change without behavior changes. Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/302101 Commit-Queue: Nate Bosch Reviewed-by: Lasse Nielsen --- sdk/lib/async/stream_controller.dart | 20 ++++++++++++++------ 1 file changed, 14 insertions(+), 6 deletions(-) diff --git a/sdk/lib/async/stream_controller.dart b/sdk/lib/async/stream_controller.dart index 9aee9da1369..d9fb9994870 100644 --- a/sdk/lib/async/stream_controller.dart +++ b/sdk/lib/async/stream_controller.dart @@ -256,9 +256,13 @@ abstract interface class StreamController implements StreamSink { /// This happens either when the done event has been sent, /// or when the subscriber on a single-subscription stream is canceled. /// - /// A broadcast stream controller will send the done event - /// even if listeners are paused, so some broadcast events may not have been - /// received yet when the returned future completes. + /// A stream controller will not complete the returned future until all + /// listeners present when the done event is sent have stopped listening. + /// A listener will stop listening if it is cancelled, or if it has handled + /// the done event. + /// A paused listener will not process the done even until it is resumed, so + /// completion of the returned Future will be delayed until all paused + /// listeners have been resumed or cancelled. /// /// If no one listens to a non-broadcast stream, /// or the listener pauses and never resumes, @@ -271,9 +275,13 @@ abstract interface class StreamController implements StreamSink { /// This happens either when the done event has been sent, or if the /// subscriber on a single-subscription stream is canceled. /// - /// A broadcast stream controller will send the done event - /// even if listeners are paused, so some broadcast events may not have been - /// received yet when the returned future completes. + /// A stream controller will not complete the returned future until all + /// listeners present when the done event is sent have stopped listening. + /// A listener will stop listening if it is cancelled, or if it has handled + /// the done event. + /// A paused listener will not process the done even until it is resumed, so + /// completion of the returned Future will be delayed until all paused + /// listeners have been resumed or cancelled. /// /// If there is no listener on a non-broadcast stream, /// or the listener pauses and never resumes,