Queue Management

Queues organize jobs by type and control how many jobs run concurrently. Each queue has its own worker pool and configuration.

Creating Queues

using namespace framework;
using namespace framework::jobs;

auto& queues = app.get_state()->of_jobs();

queue_config config;
config.name_ = "emails";
config.workers_ = 3;
config.max_attempts_ = 3;
config.retry_delay_ms_ = 5000;
config.max_job_timeout_ms_ = 30000;
config.retention_seconds_ = 86400;
config.backoff_exponential_ = true;

queues.create_queue("emails", 3, config);

The queue_config struct controls all queue behavior:

Field	Default	Description
name_	(required)	Queue name, must match the name passed to create_queue().
workers_	1	Number of concurrent worker threads processing jobs from this queue.
max_attempts_	3	Maximum retry attempts before a job is marked as failed.
retry_delay_ms_	5000	Base delay in milliseconds before retrying a failed job.
max_job_timeout_ms_	0	Maximum execution time per job. 0 = no timeout.
retention_seconds_	86400	How long completed jobs are kept in memory (24h default).
backoff_exponential_	true	If true, retry delay doubles after each attempt.

---

Queue Operations

Pause / Resume

Stop processing new jobs from a queue without losing queued items. In-flight jobs continue to completion.

queues.pause_queue("emails");
queues.resume_queue("emails");

Cancel a Job

Cancel a pending or running job by its UUID.

queues.cancel(job_id);

Pause / Resume a Specific Job

Temporarily prevent a specific job from being processed.

queues.pause_job(job_id);
queues.resume_job(job_id);

List and Inspect

// List all queue names
auto names = queues.get_queue_names();

// Get a queue by name
auto* queue = queues.get_queue("emails");

// Get a specific job entry
auto entry = queues.get_entry(job_id);
if (entry) {
    fmt::println("Job {} status: {}", entry->id_, to_string(entry->status_));
}

---

Queue Metrics

auto metrics = queues.get_queue_metrics("emails");
// metrics.jobs_dispatched_, metrics.jobs_completed_,
// metrics.jobs_failed_, metrics.jobs_cancelled_,
// metrics.jobs_timed_out_, metrics.jobs_retried_,
// metrics.execution_latency_ms_

---

Job Entry

Every job dispatch creates a job_entry that tracks the job through its lifecycle.

struct job_entry {
    boost::uuids::uuid id_;                      // Job UUID
    std::string job_name_;                       // From job->name()
    std::string queue_name_;                     // From job->queue()
    std::vector<uint8_t> payload_;               // Serialized job data
    job_ptr job_;                                // The job instance
    job_status status_;                          // pending, running, completed, failed, cancelled, expired
    int attempts_;                               // Current attempt number
    int max_attempts_;                           // Max retries before giving up
    std::chrono::system_clock::time_point created_at_;
    std::optional<std::chrono::system_clock::time_point> started_at_;
    std::optional<std::chrono::system_clock::time_point> completed_at_;
    bool paused_;                                // True if manually paused
    bool timed_out_;                             // True if job exceeded timeout
    std::string error_;                          // Last error message
};

Job Statuses

Status	Meaning
pending_	Waiting to be processed
running_	Currently executing on a worker
completed_	Finished successfully
failed_	Exhausted all retry attempts
cancelled_	Cancelled before or during execution
expired_	Removed due to retention policy

---

Queue Config Reference

struct queue_config {
    std::string name_;                     // Queue name
    uint16_t workers_{1};                  // Worker thread count
    uint8_t max_attempts_{3};              // Retry limit
    uint32_t retry_delay_ms_{5000};        // Delay before first retry (ms)
    uint32_t max_job_timeout_ms_{0};       // Job timeout (0 = no timeout)
    uint32_t retention_seconds_{86400};    // Completed job retention
    bool backoff_exponential_{true};       // Exponential backoff for retries
};