class Worker

Traits

Constants

EXIT_SUCCESS

EXIT_ERROR

EXIT_MEMORY_LIMIT

RESTART_SIGNAL_CACHE_KEY

The cache key for the restart signal.

IMPORTANT: Uses Laravel's key for cross-framework queue interoperability.

protected HANDLED_SIGNALS

Signals installed when the worker daemon starts.

protected SHUTDOWN_WAIT_SECONDS

The interval between graceful shutdown checks.

Properties

protected string|null $name

The name of the worker.

protected Repository|null $cache

The cache repository implementation.

protected callable $isDownForMaintenance

The callback used to determine if the application is in maintenance mode.

protected array $runningJobs

The running jobs.

protected array $timeoutJobIds

The timeout job IDs.

protected int|null $monitorId

The job monitor's ID.

protected Timer $timer

The timer that owns the timeout monitor.

protected bool $monitorLocked

Indicates if the job monitor is checking for timeout jobs.

protected int $jobsProcessed

The number of jobs completed by the worker.

protected float|null $lastJobProcessedAt

The timestamp of the last completed job.

protected WorkerOptions}> $pendingSignals

Signals awaiting delivery outside the asynchronous PCNTL handler.

bool $shouldQuit

Indicates if the worker should exit.

bool $lostConnection

Indicates if the worker lost its connection.

bool $paused

Indicates if the worker is paused.

protected array<int, string> $pausedQueues

The queues the worker last observed to be paused.

protected string|null $lastPolledConnection

The connection used for the last pause-state observation.

protected string|null $lastPolledQueues

The queue list used for the last pause-state observation.

static protected callable[] $popCallbacks

The callbacks used to pop jobs from queues.

static int|null $memoryExceededExitCode

The custom exit code to be used when memory is exceeded.

static int|null $timedOutExitCode

The custom exit code to be used when a job times out.

static protected null|callable(int): mixed $killCallback

The callback used to kill the worker process.

static bool $reportJobExceptions

Indicates if the worker should report job exceptions.

static bool $stopOnLostConnection

Indicates if the worker should stop when a lost connection is detected.

static bool $restartable

Indicates if the worker should check for the restart signal in the cache.

static bool $pausable

Indicates if the worker should check for the paused signal in the cache.

Methods

bool
causedByLostConnection(Throwable $e)

Determine if the given exception was caused by a lost connection.

__construct(Factory $manager, Dispatcher $events, ExceptionHandler $exceptions, callable $isDownForMaintenance, Timer|null $timer = null)

Create a new queue worker.

int
daemon(string $connectionName, string $queue, WorkerOptions $options)

Listen to the given queue in a loop.

createPopWaiter()

Create the waiter used to pop jobs.

void
waitForRunningJobs(WaitConcurrent $concurrent)

Wait for every admitted job coroutine to finish.

void
drainPendingSignals(Waiter $lifecycleWaiter)

Deliver pending signals outside their asynchronous handlers.

void
monitorTimeoutJobs(WorkerOptions $options, string $connectionName, string $queue)

Monitor the jobs for timeout.

void
terminateTimeoutJobs(WorkerOptions $options)

Scanning the running jobs and terminate the timeout jobs.

bool
hasTimeoutJobs()

Determine if there are any timeout jobs.

void
handleTimeoutJob(Job $job, WorkerOptions $options)

Handle a job that exceeded its timeout.

int
timeoutForJob(Job|null $job, WorkerOptions $options)

Get the appropriate timeout for the given job.

bool
daemonShouldRun(WorkerOptions $options, string $connectionName, string $queue)

Determine if the daemon should process on this iteration.

array|null
pauseWorker(WorkerOptions $options, int|null $lastRestart, float|int $startTime, int $jobsAdmitted)

Pause the worker for the current loop.

array|null
stopIfNecessary(WorkerOptions $options, int|null $lastRestart, float|int $startTime, int $jobsAdmitted, mixed $job = null, bool $checkQueueEmpty = true, bool $hasRunningJobs = false)

Determine the exit code to stop the process if necessary.

null
runNextJob(string $connectionName, string $queue, WorkerOptions $options)

Process the next job on the queue.

Job|null
getNextJob(Queue $connection, string $queue)

Get the next job from the queue connection.

array
getPausedQueues(string $connectionName, array $queues)

Determine which of the given queues are currently paused.

void
raisePausedQueueEvents(string $connectionName, array $paused)

Raise events for any queues that have been paused or resumed since the last check.

null
runJob(Job $job, string $connectionName, WorkerOptions $options)

Process the given job.

mixed
withCoroutineContext(WorkerOptions $options, callable $callback)

Run the callback with the worker option context active.

void
stopWorkerIfLostConnection(Throwable $e)

Stop the worker if we have lost connection to a database.

void
process(string $connectionName, Job $job, WorkerOptions $options)

Process the given job from the queue.

void
handleInvalidPayload(string $connectionName, Job $job, InvalidPayloadException $e)

Fail a job whose payload cannot be consumed.

string
registerCoroutineJob(Job $job, WorkerOptions $options)

Register a coroutine job to running jobs.

void
handleJobException(string $connectionName, Job $job, WorkerOptions $options, Throwable $e)

Handle an exception that occurred while the job was running.

void
markJobAsFailedIfAlreadyExceedsMaxAttempts(string $connectionName, Job $job, int $maxTries)

Mark the given job as failed if it has exceeded the maximum allowed attempts.

void
markJobAsFailedIfWillExceedMaxAttempts(string $connectionName, Job $job, int $maxTries, Throwable $e)

Mark the given job as failed if it has exceeded the maximum allowed attempts.

void
markJobAsFailedIfWillExceedMaxExceptions(string $connectionName, Job $job, Throwable $e)

Mark the given job as failed if it has exceeded the maximum allowed attempts.

void
markJobAsFailedIfItShouldntBeRetried(string $connectionName, Job $job, Throwable $e)

Mark the given job as failed if the exception handler determines it should not be retried.

void
markJobAsFailedIfItShouldFailOnTimeout(string $connectionName, Job $job, Throwable $e)

Mark the given job as failed if it should fail on timeouts.

void
failJob(Job $job, Throwable $e)

Mark the given job as failed and raise the relevant event.

int
calculateBackoff(Job $job, WorkerOptions $options)

Calculate the backoff for the given job.

void
raiseWorkerStartingEvent(string $connectionName, string $queue, WorkerOptions $options)

Raise an event indicating the worker is starting.

void
raiseBeforeJobPopEvent(string $connectionName, string|null $queue = null)

Raise the before job has been popped.

void
raiseAfterJobPopEvent(string $connectionName, Job|null $job)

Raise the after job has been popped.

void
raiseBeforeJobEvent(string $connectionName, Job|null $job)

Raise the before queue job event.

void
raiseAfterJobEvent(string $connectionName, Job $job)

Raise the after queue job event.

void
raiseExceptionOccurredJobEvent(string $connectionName, Job|null $job, Throwable $e)

Raise the exception occurred queue job event.

bool
queueShouldRestart(int|null $lastRestart)

Determine if the queue worker should restart.

int|null
getTimestampOfLastQueueRestart()

Get the last queue restart timestamp, or null.

void
listenForSignals(string $connectionName, string $queue, WorkerOptions $options)

Enable async signals for the process.

void
handleInterruptionSignal(int $signal, string $connectionName, string $queue, WorkerOptions $options)

Handle a worker interruption signal.

void
handlePauseSignal(string $connectionName, string $queue, WorkerOptions $options)

Handle a worker pause signal.

void
handleResumeSignal(string $connectionName, string $queue, WorkerOptions $options)

Handle a worker resume signal.

void
notifyJobsOfSignal(int $signal)

Pass the signal to the running jobs.

bool
supportsAsyncSignals()

Determine if "async" signals are supported.

bool
memoryExceeded(float $memoryLimit)

Determine if the memory limit has been exceeded.

float
currentMemoryUsage()

Get the current memory usage in megabytes.

float
currentTime()

Get the current monotonic time.

int
stop(string $connectionName, string $queue, int $status = 0, WorkerOptions|null $options = null, WorkerStopReason|null $reason = null)

Stop listening and bail out of the script.

never
kill(string $connectionName, string $queue, int $status = 0, WorkerOptions|null $options = null, WorkerStopReason|null $reason = null)

Kill the process.

never
terminateProcess(int $status)

Terminate the current worker process immediately.

maxAttemptsExceededException(Job $job)

Create an instance of MaxAttemptsExceededException.

timeoutExceededException(Job|null $job)

Create an instance of TimeoutExceededException.

void
sleep(float|int $seconds)

Sleep the script for a given number of seconds.

setCache(Repository $cache)

Set the cache repository implementation.

setName(string $name)

Set the name of the worker.

static void
popUsing(string $workerName, callable|null $callback)

Register a callback to be executed to pick jobs.

static void
killUsing(callable|null $callback)

Register a callback to be used to kill the worker process.

getManager()

Get the queue manager instance.

void
setManager(Factory $manager)

Set the queue manager instance.

static void
flushState()

Flush all static state.

Details

protected bool causedByLostConnection(Throwable $e)

Determine if the given exception was caused by a lost connection.

Parameters

Throwable $e

Return Value

bool

at line 241
__construct(Factory $manager, Dispatcher $events, ExceptionHandler $exceptions, callable $isDownForMaintenance, Timer|null $timer = null)

Create a new queue worker.

Parameters

Factory $manager

the queue manager instance

Dispatcher $events

the event dispatcher instance

ExceptionHandler $exceptions

the exception handler instance

callable $isDownForMaintenance

the callback used to determine if the application is in maintenance mode

Timer|null $timer

at line 255
int daemon(string $connectionName, string $queue, WorkerOptions $options)

Listen to the given queue in a loop.

Parameters

string $connectionName
string $queue
WorkerOptions $options

Return Value

int

at line 438
protected Waiter createPopWaiter()

Create the waiter used to pop jobs.

Return Value

Waiter

at line 446
protected void waitForRunningJobs(WaitConcurrent $concurrent)

Wait for every admitted job coroutine to finish.

Parameters

WaitConcurrent $concurrent

Return Value

void

at line 460
protected void drainPendingSignals(Waiter $lifecycleWaiter)

Deliver pending signals outside their asynchronous handlers.

Parameters

Waiter $lifecycleWaiter

Return Value

void

at line 508
protected void monitorTimeoutJobs(WorkerOptions $options, string $connectionName, string $queue)

Monitor the jobs for timeout.

Parameters

WorkerOptions $options
string $connectionName
string $queue

Return Value

void

at line 549
protected void terminateTimeoutJobs(WorkerOptions $options)

Scanning the running jobs and terminate the timeout jobs.

Parameters

WorkerOptions $options

Return Value

void

at line 564
protected bool hasTimeoutJobs()

Determine if there are any timeout jobs.

Return Value

bool

at line 572
protected void handleTimeoutJob(Job $job, WorkerOptions $options)

Handle a job that exceeded its timeout.

Parameters

Job $job
WorkerOptions $options

Return Value

void

at line 605
protected int timeoutForJob(Job|null $job, WorkerOptions $options)

Get the appropriate timeout for the given job.

Parameters

Job|null $job
WorkerOptions $options

Return Value

int

at line 613
protected bool daemonShouldRun(WorkerOptions $options, string $connectionName, string $queue)

Determine if the daemon should process on this iteration.

Parameters

WorkerOptions $options
string $connectionName
string $queue

Return Value

bool

at line 624
protected array|null pauseWorker(WorkerOptions $options, int|null $lastRestart, float|int $startTime, int $jobsAdmitted)

Pause the worker for the current loop.

Parameters

WorkerOptions $options
int|null $lastRestart
float|int $startTime
int $jobsAdmitted

Return Value

array|null

at line 644
protected array|null stopIfNecessary(WorkerOptions $options, int|null $lastRestart, float|int $startTime, int $jobsAdmitted, mixed $job = null, bool $checkQueueEmpty = true, bool $hasRunningJobs = false)

Determine the exit code to stop the process if necessary.

Parameters

WorkerOptions $options
int|null $lastRestart
float|int $startTime
int $jobsAdmitted
mixed $job
bool $checkQueueEmpty
bool $hasRunningJobs

Return Value

array|null

at line 673
null runNextJob(string $connectionName, string $queue, WorkerOptions $options)

Process the next job on the queue.

Parameters

string $connectionName
string $queue
WorkerOptions $options

Return Value

null

at line 698
protected Job|null getNextJob(Queue $connection, string $queue)

Get the next job from the queue connection.

Parameters

Queue $connection
string $queue

Return Value

Job|null

at line 759
protected array getPausedQueues(string $connectionName, array $queues)

Determine which of the given queues are currently paused.

Parameters

string $connectionName
array $queues

Return Value

array

at line 778
protected void raisePausedQueueEvents(string $connectionName, array $paused)

Raise events for any queues that have been paused or resumed since the last check.

Parameters

string $connectionName
array $paused

Return Value

void

at line 798
protected null runJob(Job $job, string $connectionName, WorkerOptions $options)

Process the given job.

Parameters

Job $job
string $connectionName
WorkerOptions $options

Return Value

null

at line 820
protected mixed withCoroutineContext(WorkerOptions $options, callable $callback)

Run the callback with the worker option context active.

Parameters

WorkerOptions $options
callable $callback

Return Value

mixed

at line 851
protected void stopWorkerIfLostConnection(Throwable $e)

Stop the worker if we have lost connection to a database.

Parameters

Throwable $e

Return Value

void

at line 863
void process(string $connectionName, Job $job, WorkerOptions $options)

Process the given job from the queue.

Parameters

string $connectionName
Job $job
WorkerOptions $options

Return Value

void

Exceptions

Throwable

at line 954
protected void handleInvalidPayload(string $connectionName, Job $job, InvalidPayloadException $e)

Fail a job whose payload cannot be consumed.

Parameters

string $connectionName
Job $job
InvalidPayloadException $e

Return Value

void

at line 963
protected string registerCoroutineJob(Job $job, WorkerOptions $options)

Register a coroutine job to running jobs.

Parameters

Job $job
WorkerOptions $options

Return Value

string

at line 980
protected void handleJobException(string $connectionName, Job $job, WorkerOptions $options, Throwable $e)

Handle an exception that occurred while the job was running.

Parameters

string $connectionName
Job $job
WorkerOptions $options
Throwable $e

Return Value

void

Exceptions

Throwable

at line 1048
protected void markJobAsFailedIfAlreadyExceedsMaxAttempts(string $connectionName, Job $job, int $maxTries)

Mark the given job as failed if it has exceeded the maximum allowed attempts.

This will likely be because the job previously exceeded a timeout.

Parameters

string $connectionName
Job $job
int $maxTries

Return Value

void

Exceptions

Throwable

at line 1070
protected void markJobAsFailedIfWillExceedMaxAttempts(string $connectionName, Job $job, int $maxTries, Throwable $e)

Mark the given job as failed if it has exceeded the maximum allowed attempts.

Parameters

string $connectionName
Job $job
int $maxTries
Throwable $e

Return Value

void

at line 1086
protected void markJobAsFailedIfWillExceedMaxExceptions(string $connectionName, Job $job, Throwable $e)

Mark the given job as failed if it has exceeded the maximum allowed attempts.

Parameters

string $connectionName
Job $job
Throwable $e

Return Value

void

at line 1110
protected void markJobAsFailedIfItShouldntBeRetried(string $connectionName, Job $job, Throwable $e)

Mark the given job as failed if the exception handler determines it should not be retried.

Parameters

string $connectionName
Job $job
Throwable $e

Return Value

void

at line 1121
protected void markJobAsFailedIfItShouldFailOnTimeout(string $connectionName, Job $job, Throwable $e)

Mark the given job as failed if it should fail on timeouts.

Parameters

string $connectionName
Job $job
Throwable $e

Return Value

void

at line 1131
protected void failJob(Job $job, Throwable $e)

Mark the given job as failed and raise the relevant event.

Parameters

Job $job
Throwable $e

Return Value

void

at line 1139
protected int calculateBackoff(Job $job, WorkerOptions $options)

Calculate the backoff for the given job.

Parameters

Job $job
WorkerOptions $options

Return Value

int

at line 1153
protected void raiseWorkerStartingEvent(string $connectionName, string $queue, WorkerOptions $options)

Raise an event indicating the worker is starting.

Parameters

string $connectionName
string $queue
WorkerOptions $options

Return Value

void

at line 1163
protected void raiseBeforeJobPopEvent(string $connectionName, string|null $queue = null)

Raise the before job has been popped.

Parameters

string $connectionName
string|null $queue

Return Value

void

at line 1173
protected void raiseAfterJobPopEvent(string $connectionName, Job|null $job)

Raise the after job has been popped.

Parameters

string $connectionName
Job|null $job

Return Value

void

at line 1186
protected void raiseBeforeJobEvent(string $connectionName, Job|null $job)

Raise the before queue job event.

Parameters

string $connectionName
Job|null $job

Return Value

void

at line 1199
protected void raiseAfterJobEvent(string $connectionName, Job $job)

Raise the after queue job event.

Parameters

string $connectionName
Job $job

Return Value

void

at line 1212
protected void raiseExceptionOccurredJobEvent(string $connectionName, Job|null $job, Throwable $e)

Raise the exception occurred queue job event.

Parameters

string $connectionName
Job|null $job
Throwable $e

Return Value

void

at line 1226
protected bool queueShouldRestart(int|null $lastRestart)

Determine if the queue worker should restart.

Parameters

int|null $lastRestart

Return Value

bool

at line 1238
protected int|null getTimestampOfLastQueueRestart()

Get the last queue restart timestamp, or null.

Return Value

int|null

at line 1256
protected void listenForSignals(string $connectionName, string $queue, WorkerOptions $options)

Enable async signals for the process.

Parameters

string $connectionName
string $queue
WorkerOptions $options

Return Value

void

at line 1282
protected void handleInterruptionSignal(int $signal, string $connectionName, string $queue, WorkerOptions $options)

Handle a worker interruption signal.

Parameters

int $signal
string $connectionName
string $queue
WorkerOptions $options

Return Value

void

at line 1291
protected void handlePauseSignal(string $connectionName, string $queue, WorkerOptions $options)

Handle a worker pause signal.

Parameters

string $connectionName
string $queue
WorkerOptions $options

Return Value

void

at line 1305
protected void handleResumeSignal(string $connectionName, string $queue, WorkerOptions $options)

Handle a worker resume signal.

Parameters

string $connectionName
string $queue
WorkerOptions $options

Return Value

void

at line 1319
protected void notifyJobsOfSignal(int $signal)

Pass the signal to the running jobs.

Parameters

int $signal

Return Value

void

at line 1356
protected bool supportsAsyncSignals()

Determine if "async" signals are supported.

Return Value

bool

at line 1364
bool memoryExceeded(float $memoryLimit)

Determine if the memory limit has been exceeded.

Parameters

float $memoryLimit

Return Value

bool

at line 1372
protected float currentMemoryUsage()

Get the current memory usage in megabytes.

Return Value

float

at line 1380
protected float currentTime()

Get the current monotonic time.

Return Value

float

at line 1388
int stop(string $connectionName, string $queue, int $status = 0, WorkerOptions|null $options = null, WorkerStopReason|null $reason = null)

Stop listening and bail out of the script.

Parameters

string $connectionName
string $queue
int $status
WorkerOptions|null $options
WorkerStopReason|null $reason

Return Value

int

at line 1415
never kill(string $connectionName, string $queue, int $status = 0, WorkerOptions|null $options = null, WorkerStopReason|null $reason = null)

Kill the process.

Parameters

string $connectionName
string $queue
int $status
WorkerOptions|null $options
WorkerStopReason|null $reason

Return Value

never

at line 1446
protected never terminateProcess(int $status)

Terminate the current worker process immediately.

Parameters

int $status

Return Value

never

at line 1458
protected MaxAttemptsExceededException maxAttemptsExceededException(Job $job)

Create an instance of MaxAttemptsExceededException.

Parameters

Job $job

Return Value

MaxAttemptsExceededException

at line 1466
protected TimeoutExceededException timeoutExceededException(Job|null $job)

Create an instance of TimeoutExceededException.

Parameters

Job|null $job

Return Value

TimeoutExceededException

at line 1474
void sleep(float|int $seconds)

Sleep the script for a given number of seconds.

Parameters

float|int $seconds

Return Value

void

at line 1485
Worker setCache(Repository $cache)

Set the cache repository implementation.

Boot-only. The repository persists on the singleton worker for the worker lifetime and is read by every subsequent pause or restart check.

Parameters

Repository $cache

Return Value

Worker

at line 1498
Worker setName(string $name)

Set the name of the worker.

Boot-only. The name persists on the singleton worker for the worker lifetime and selects the static pop callback used by every job pop.

Parameters

string $name

Return Value

Worker

at line 1512
static void popUsing(string $workerName, callable|null $callback)

Register a callback to be executed to pick jobs.

Boot-only. The callback persists in a static property for the worker process lifetime and runs on every job pop for the named worker. Passing null removes the callback.

Parameters

string $workerName
callable|null $callback

Return Value

void

at line 1529
static void killUsing(callable|null $callback)

Register a callback to be used to kill the worker process.

Boot-only. The callback persists for the worker lifetime and runs before forced process termination. Passing null clears it.

Parameters

callable|null $callback

Return Value

void

at line 1537
Factory getManager()

Get the queue manager instance.

Return Value

Factory

at line 1548
void setManager(Factory $manager)

Set the queue manager instance.

Tests only. Swaps the manager reference on the singleton worker; runtime use races across coroutines and changes every concurrent queue lookup.

Parameters

Factory $manager

Return Value

void

at line 1556
static void flushState()

Flush all static state.

Return Value

void