QueueIt
QueueIt makes dealing with queues in your Flutter and Dart apps easy, like uploading or downloading files a few at a time.
Features
- Queue management: Easily add, cancel and remove items.
- Event listeners: Listen for updates to the queue and receive snapshots.
- Concurrency: Control the number of items processed simultaneously.
- Retries: Automatically retry failed items.
- Progress: See each item's status and how much is done.
- Flutter: Rebuild your widgets when the queue changes, with flutter_queue_it.
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 it runs out of items, whether they were processed, canceled or removed, 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.
Only the queue changes an item, so status, error and stackTrace are read-only. To change
what happens to an item, use the queue's methods, or nextStatus from the item handler.
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. Retries go ahead of the
other pending items, in the order they're due. 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: (item, retry) => Duration(seconds: 1 << (retry - 1)),
/// Only retry errors that might go away
retryIf: (item, 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. And a listener can cancel an item
in its failed update, so it isn't retried.
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, and counts
towards parallel until it returns, 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. Make sure the queue is started, or the item won't be processed:
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.willRetry is true for those, and false once an item has failed for good. New events may
come in minor versions, so in a switch over snapshot.event, handle the ones you need and use a
default case for the rest.
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. Counting the queue's own items is quick however many there are: length, progress,
summary and counts like items.completed.length.
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. There are only a few hundred of those, so the id of a removed item can come up
again. queue.itemById(id) gives you the item, or null if the queue doesn't have it.
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, and waitFor futures
that are still waiting fail with a StateError.
For a more in-depth look at how to use QueueIt, check out the example project.
Migrating from 0.10
- An item's
status,errorandstackTraceare now read-only. To cancel or remove an item, use the queue'scancelandremovemethods, and to choose what happens to an item when its handler returns, setitem.nextStatusin the handler. To fail an item with an error, throw it from the handler. - Items you make yourself, for example in tests, get their status from the constructor, which
records when they got there, and their
errorandstackTracefromcopyWith:QueueItem(data: 'a', batchId: 'b', status: QueueItemStatus.failed).copyWith(error: e). items.cancelledandOnUpdateCallback, deprecated in 0.10.0, are gone. Useitems.canceled, and listen toqueue.onUpdatefor updates. If you usedOnUpdateCallbackas a type, declare your own:typedef OnUpdateCallback<T> = void Function(QueueItemStatus status, QueueItem<T> item);nextStatusonly counts when it's set while the item is processing, usually by its handler. A value set before then, for example on a pending item, is ignored.QueueEvent.cancelledAllis nowQueueEvent.canceledAll, anditems.summarysaysCanceledinstead ofCancelled.retryDelayandretryIfnow get the item first:retryDelay: (item, retry) => ...andretryIf: (item, error) => ....
Migrating from 0.9
These come on top of the changes from 0.10 above.
- 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.- The first item added after every item has finished starts a new batch, 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 gone.- QueueIt now requires Dart 3.5 or later.
If QueueIt is useful to you, give it a like on pub.dev.
License
QueueIt is licensed under the MIT License.
Libraries
- callbacks
- The function types a queue takes.
- extensions
- Filters and progress for collections of queue items.
- models
- The items, statuses, events and snapshots of a queue.
- queue_it
- Queues that process items with a handler, a few at a time, with retries, item statuses and a stream of snapshots.