gisila_queue

gisila_queue runs work in the background. You register named tasks, enqueue them from anywhere with .delay() or .applyAsync(), and worker processes run them. A broker (Redis, RabbitMQ or in-memory) carries the messages, and an optional result backend stores each task’s state and return value. If you know Celery, you already know the shape.

Alongside the core it has retries with exponential backoff, countdown/ETA and expiry, named queues with routing, periodic tasks (beat) with leader election, chain/group/chord workflows, revocation and queue pause, deduplication, and an optional web dashboard (GisilaRose).

This section also covers gisila_redis, a small separate package that gives gisila web apps a Redis-backed rate-limit store and cache.

Install

dependencies:
  gisila_queue: ^0.3.0

30-second example

One process (in-memory)

import 'dart:async';

import 'package:gisila_queue/gisila_queue.dart';

Future<void> main() async {
  final app = GisilaQueue(broker: InMemoryBroker(), backend: InMemoryResultBackend());

  final add = app.task<int>(
    'math.add',
    (ctx) async => (ctx.arg(0) as int) + (ctx.arg(1) as int),
    maxRetries: 3,
  );

  final worker = app.worker(concurrency: 4);
  unawaited(worker.run());

  final r = await add.delay([2, 3]);
  print(await r.get()); // 5

  await worker.stop();
  await app.close();
}

Distributed (Redis)

import 'package:gisila_queue/gisila_queue.dart';

// Shared by the web process and the worker process.
final app = GisilaQueue.redis(namespace: 'shop', host: 'localhost');
final add = app.task<int>(
  'math.add',
  (ctx) async => (ctx.arg(0) as int) + (ctx.arg(1) as int),
  maxRetries: 3,
);

// Producer (e.g. in a request handler):
Future<void> produce() async {
  final r = await add.applyAsync(args: [2, 3], countdown: const Duration(seconds: 10));
  print(await r.get(timeout: const Duration(seconds: 30)));
}

// Worker process:
Future<void> work() => app.worker(queues: ['default'], concurrency: 8).run();

When to use it

• Work that would slow a request down: email, PDFs, image processing, third-party APIs.
• Work that must survive crashes and deploys: Redis and RabbitMQ give at-least-once delivery.
• Work that runs later or on a schedule: countdown, eta, and beat with cron expressions.
• Spreading load across processes and machines.

When not to use it

• Fast work you must finish before responding: just await it.
• Event streaming with replay or consumer groups: use a log such as Kafka or Redis Streams; queue messages are consumed once.
• Exactly-once side effects with no way to make the handler idempotent: tasks can run more than once (see Delivery guarantees).

Tip

Give every app its own namespace (GisilaQueue.redis(namespace: 'myapp')). Two apps on the default gq namespace on one Redis take each other’s tasks.

Map of this section

Concepts

Architecture, delivery guarantees, choosing a broker, retries, results, concurrency, namespaces, workflows.

Guides

First task, run workers, delayed tasks, periodic tasks, retries, results, routing, Redis and RabbitMQ, testing, workflows, gisila apps, deploying, monitoring.

API referenceEvery public symbol, grouped by area.

gisila_redisRedis rate limiting and cache for gisila web apps.