QueueIt

Pub Version codecov

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 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 with cancel, cancelById or cancelAll.
  • removed: Removed from the queue with remove, removeById or removeAll.

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: (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. 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, 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 failed instead of canceled, and item.error and item.stackTrace hold the last error. If you looked for canceled items to find failures, look for failed ones instead.
  • add throws an ArgumentError if the queue already has an item with that id. Use hasItemById to check first.
  • add and start throw a StateError once the queue is disposed.
  • cancel only cancels pending and processing items, and returns false for 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.
  • onUpdate listeners can now call the queue. If you delayed those calls to get around the Cannot fire new event error, you don't need to anymore.
  • items.cancelled is now items.canceled, and the unused OnUpdateCallback is deprecated.
  • QueueIt now requires Dart 3.5 or later.

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.