queue_it 0.10.0
queue_it: ^0.10.0 copied to clipboard
QueueIt makes dealing with queues easy. You can add multiple listeners, specify the number of concurrent items to process, view queue progress and more.
QueueIt #
QueueIt is designed to simplify the process of managing and processing queues in your Flutter and Dart applications.
Features #
- Queue management: Easily add, remove, cancel, and process items in a queue.
- Event listeners: Listen for updates to the queue and receive snapshots.
- Concurrency: Control the number of items processed simultaneously.
- Retries: Automatically retry failed items, with an optional delay between attempts.
- Item statuses: See where each item is at, when it got there, and why it failed.
- Waiting: Wait for a single item, or the whole queue, to finish.
Getting started #
dart pub add queue_it
QueueIt requires Dart 3.5 or later.
Usage #
Here's a basic example of how to use QueueIt:
// lib/main.dart
import 'package:queue_it/queue_it.dart';
Future<void> main() async {
final queue = QueueIt<int>(
parallel: 1,
retries: 3,
itemHandler: (item) async {
print('Handling item: ${item.data}');
/// Fake processing time
await Future<void>.delayed(const Duration(seconds: 1));
},
);
queue.onUpdate.listen((snapshot) {
print('Queue updated: ${snapshot.event.name}');
});
/// Add some items to the queue
queue.add(1);
queue.add(2);
queue.add(3);
/// Start processing the queue
queue.start();
/// You can continue adding more items to the queue after it starts processing
queue.add(4);
queue.add(5);
/// Wait for every item to be processed
await queue.running;
queue.dispose();
}
For Flutter projects you will want to use flutter_queue_it, which listens to queue changes and rebuilds your widget tree:
QueueItWidget(
queue: _queue,
builder: (context, snapshot) {
/// `builder` will be called each time the queue updates
final items = _queue.items().toList();
return ListView.builder(
itemCount: items.length,
itemBuilder: (context, index) {
final item = items[index];
return ListTile(
title: Text('Item status: ${item.status.name}'),
);
},
);
},
);
Starting and stopping #
start() processes items in the order they were added, parallel at a time. By default the queue
stops by itself once every item is processed, and items added after that wait for the next
start(). If you start a queue with no items, it waits for its first one.
/// Keep the queue running, so items added later are processed right away
queue.start(stopAutomatically: false);
/// Stop starting new items. Items being processed will finish, and pending items
/// wait for the next `start()`
queue.stop();
/// Completes once the queue has stopped and its items have finished
await queue.running;
queue.isStarted tells you whether the queue is started, and queue.isProcessing whether it's
working through items.
Item statuses #
Every item has a status:
pending: Waiting to be processed, for the first time or for a retry.processing: The item handler is running.completed: The item handler returned.failed: The item handler threw, and there are no retries left.canceled: Canceled withcancel,cancelByIdorcancelAll.removed: Removed from the queue withremove,removeByIdorremoveAll.
Items also record when they got to each status (queuedAt, startedProcessingAt, completedAt,
failedAt, canceledAt and removedAt), and any list of items has some helpers:
final items = queue.items();
/// Items with a given status
print(items.failed.length);
/// How much of the work is done, from 0 to 1
print(items.progress);
/// A count of the items in each status
print(items.summary);
Retries #
When the item handler throws, the item is retried up to retries times, ahead of the other pending
items. Once there are no retries left the item is failed, and item.error and item.stackTrace
tell you why.
final queue = QueueIt<Uri>(
retries: 3,
/// Wait 1, 2, then 4 seconds before each retry. Other items keep
/// processing in the meantime
retryDelay: (retry) => Duration(seconds: 1 << (retry - 1)),
/// Only retry errors that might go away
retryIf: (error) => error is! FormatException,
itemHandler: (item) => download(item.data),
);
The item handler can also set item.nextStatus to choose what happens to the item when it returns,
for example QueueItemStatus.pending to process it again later.
Canceling and removing items #
final id = queue.add(6);
/// The item won't be processed
queue.cancelById(id);
/// Same as canceling, and the item is also taken out of the queue
queue.removeById(id);
An item that's already processing can't be interrupted, so its handler keeps running, but QueueIt
ignores the result and won't retry it. If your handler does a lot of work, it can check
item.status to stop early. cancel and remove take an item instead of an id, including the
copies you get in snapshots, and cancelAll and removeAll work on every item.
Waiting for an item #
waitFor completes with a copy of the item once it's completed, canceled or removed, or failed
with no retries left:
final item = await queue.waitFor(queue.add(7));
if (item.status == QueueItemStatus.failed) {
print('Item failed: ${item.error}');
}
Listening for updates #
onUpdate sends a QueueSnapshot every time the queue changes:
queue.onUpdate.listen((snapshot) {
/// What happened, such as `itemAdded` or `stoppedProcessing`
print(snapshot.event.name);
/// A copy of the item the update is about, if there is one
final item = snapshot.eventItem;
/// You can call the queue from a listener, like stopping at the first failure
if (item?.status == QueueItemStatus.failed) queue.stop();
});
Every failed attempt sends a failed update, including the ones that will be retried.
snapshot.items holds the items of the current batch. These are the queue's own items, so they keep
changing after the update. If you need them as they were at the time, create the queue with
deepCopyItemsInSnapshot: true, but copying them costs time on every update, especially for big
batches.
Batches #
Items added while the queue still has unfinished items share a batchId. Once every item has
finished, the next item you add starts a new batch. queue.currentBatchItems gives you the current
batch, queue.items() every item, and queue.items(batchId) a single batch. Finished items stay in
the queue until you remove them.
Item ids #
add returns the item's id. It's a UUID, unless you pass your own with queue.add(data, id: 'my-id').
Ids must be unique within the queue. Set useFriendlyIds: true for readable ids like
big wizard cat.
Disposing #
Call dispose() when you're done with a queue. It stops the queue and closes onUpdate. Handlers
that are still running aren't interrupted, but their results are ignored.
For a more in-depth look at how to use QueueIt, check out the example project.
Migrating from 0.9 #
- Items that run out of retries are now
failedinstead ofcanceled, anditem.erroranditem.stackTracehold the last error. If you looked for canceled items to find failures, look for failed ones instead. addthrows anArgumentErrorif the queue already has an item with that id. UsehasItemByIdto check first.addandstartthrow aStateErroronce the queue is disposed.cancelonly cancels pending and processing items, and returnsfalsefor items that have already finished.- A new batch starts as soon as every item has finished, instead of only when the queue is empty.
- Canceled and removed items now stay that way, even if they were processing at the time.
onUpdatelisteners can now call the queue. If you delayed those calls to get around theCannot fire new eventerror, you don't need to anymore.items.cancelledis nowitems.canceled, and the unusedOnUpdateCallbackis deprecated.- QueueIt now requires Dart 3.5 or later.
License #
QueueIt is licensed under the MIT License.