Queues

Queue background jobs in ColdBox with cbq — dispatch, workers, and providers.

cbq brings Laravel-style job queues to ColdBox: dispatch work now, execute it later on a worker, with pluggable providers.

box install cbq

📖 Full documentation: cbq.ortusbooks.com

Quick Example

BoxLang

// models/jobs/WelcomeEmailJob.bx
class extends="cbq.models.Jobs.AbstractJob" {

    property name="userId"

    function handle(){
        var user = getInstance( "UserService" ).get( variables.userId )
        getInstance( "MailService@cbmailservices" ).send( buildWelcomeMail( user ) )
    }
}

CFML

// models/jobs/WelcomeEmailJob.cfc
component extends="cbq.models.Jobs.AbstractJob" {

    property name="userId"

    function handle(){
        var user = getInstance( "UserService" ).get( variables.userId )
        getInstance( "MailService@cbmailservices" ).send( buildWelcomeMail( user ) )
    }
}

// Dispatch from anywhere
property name="queue" inject="QueueProvider@cbq";

queue.job( "WelcomeEmailJob" )
    .setUserId( user.getId() )
    .dispatch()

Workers

Run a worker process to consume the queue:

box cbq work

Workers are long-running processes — supervise them in production (systemd, Docker restart policies, or your platform's process manager) and restart them on deploys.

When to Use It

• Anything slow that shouldn't block a request: mail, PDFs, report generation, third-party API calls

• Retryable work — failed jobs can be released and retried with backoff

• Smoothing traffic spikes by deferring heavy work

Alternatives

• Scheduled Tasks — time-based recurring work, not request-driven jobs

• Async Programming — in-process parallelism when you don't need persistence or retries

See Also

• Mail — the classic first job to queue

• Deployment — supervising workers in production