StreamQueue<T> class

An asynchronous pull-based interface for accessing stream events.

Wraps a stream and makes individual events available on request.

You can request (and reserve) one or more events from the stream, and after all previous requests have been fulfilled, stream events go towards fulfilling your request.

For example, if you ask for next two times, the returned futures will be completed by the next two unrequested events from the stream.

The stream subscription is paused when there are no active requests.

Some streams, including broadcast streams, will buffer events while paused, so waiting too long between requests may cause memory bloat somewhere else.

This is similar to, but more convenient than, a StreamIterator. A StreamIterator requires you to manually check when a new event is available and you can only access the value of that event until you check for the next one. A StreamQueue allows you to request, for example, three events at a time, either individually, as a group using take or skip, or in any combination.

You can also ask to have the rest of the stream provided as a new stream. This allows, for example, taking the first event out of a stream and continuing to use the rest of the stream as a stream.

Example:

var events = new StreamQueue<String>(someStreamOfLines);
var first = await events.next;
while (first.startsWith('#')) {
  // Skip comments.
  first = await events.next;
}

if (first.startsWith(MAGIC_MARKER)) {
  var headerCount =
      first.parseInt(first.substring(MAGIC_MARKER.length + 1));
  handleMessage(headers: await events.take(headerCount),
                body: events.rest);
  return;
}
// Error handling.

When you need no further events the StreamQueue should be closed using cancel. This releases the underlying stream subscription.