blocking_queue 0.1.0
blocking_queue: ^0.1.0 copied to clipboard
Dart queues that wait for items, with either FIFO buffering or a buffer that keeps only the latest item.
Blocking Queue #
Hand off items from a producer to one or more asynchronous consumers in the
same Dart isolate. Call dequeue() to wait for the next item when the buffer is
empty.
Choose a buffer #
| Queue | When to use it | What happens with a slow consumer |
|---|---|---|
UnboundedBlockingQueue<T> |
Jobs or events that must all be delivered | Items accumulate in FIFO order. Size and memory use can grow. |
SingleCapacityBlockingQueue<T> |
State snapshots or refresh signals that supersede earlier values | One item can stay pending. Each new buffered item replaces the previous one. |
Process every queued item #
import 'package:blocking_queue/blocking_queue.dart';
Future<void> main() async {
final queue = UnboundedBlockingQueue<String>();
try {
queue.enqueue('first');
queue.enqueue('second');
print(await queue.dequeue()); // first
print(await queue.dequeue()); // second
} finally {
queue.dispose();
}
}
Keep the latest pending value #
import 'package:blocking_queue/blocking_queue.dart';
Future<void> main() async {
final queue = SingleCapacityBlockingQueue<String>();
final waiting = queue.dequeue();
queue.enqueue('Starting');
print(await waiting); // Starting
queue.enqueue('Refreshing');
queue.enqueue('Ready');
print(await queue.dequeue()); // Ready
queue.dispose();
}
Delivery and lifecycle #
enqueue()is synchronous. It hands the item directly to the oldest waiter when there is one. This applies to both queues, including when several consumers are waiting on a single-capacity queue.dequeue()returns aFuture<T>. Each item goes to one consumer, and waiting consumers receive items in the order they calleddequeue(). Consumers can finish processing at different times.- Queues are for a single Dart isolate, and
Tis non-nullable. An empty queue waits until an item arrives or the owner disposes it. A caller-sideFuture.timeoutleaves the underlying dequeue pending, so that waiter can still consume a later item. dispose()is idempotent. It discards buffered items, fails outstanding waits withAlreadyDisposedException, and leaves delivered items with their consumers. To finish buffered work, drain it before disposal.- After disposal,
enqueue()throws synchronously anddequeue()returns a failed future. Handle errors from outstanding dequeue futures during shutdown.