Workpool

Workpool organizes async operations into prioritized queues, ensuring critical tasks execute first in Convex applications.

Installation

npm install @convex-dev/workpool

About Workpool

This Convex component pools actions and mutations to restrict parallel requests.

Configure multiple pools with different parallelism.
Retry failed actions (with backoff and jitter) for idempotent actions, fully configurable (respecting parallelism).
An onComplete callback so you can build durable, reliable workflows. Called when the work is finished, whether it succeeded, failed, or was canceled.

Benefits

Use cases

how to prioritize background tasks in Convex

Workpool lets you create separate queues with different priority levels for your Convex functions. You can route urgent operations like user-facing requests to high-priority queues while background tasks like email sending run in lower-priority queues.

Convex task queue with priority scheduling

Workpool provides priority-based task scheduling by organizing async operations into customizable queues. Each queue can have its own concurrency limits and execution priority, ensuring critical tasks aren't blocked by lower-priority work.

prevent Convex background jobs from blocking user requests

Workpool isolates user-facing operations from background jobs by running them in separate queues. This prevents heavy background processing from delaying critical user interactions in your Convex application.

Frequently asked questions

How does Workpool handle queue priorities?

Workpool allows you to define multiple queues with different priority levels and concurrency limits. Higher-priority queues are processed before lower-priority ones, ensuring critical tasks execute first while background operations run when resources are available.

Can I limit concurrent executions per queue?

Yes, Workpool supports configurable concurrency limits for each queue. This lets you control how many tasks from each queue run simultaneously, preventing resource exhaustion and ensuring fair allocation across different types of operations.

Does Workpool work with existing Convex functions?

Workpool integrates with your existing Convex functions by wrapping them in queue operations. You can route any async function through Workpool queues without changing the function's core logic, just the way it's scheduled and executed.

What happens if a high-priority queue is empty?

When high-priority queues are empty, Workpool automatically processes tasks from lower-priority queues. This ensures optimal resource utilization while maintaining the priority ordering when critical tasks are present.

Links