/ 
Punk-Queue-0.01
/ Punk::Queue::Job

NAME

Punk::Queue::Job - a claimed job

SYNOPSIS

$q->task('report.build' => sub {
    my ($job, $year) = @_;

    warn "job ", $job->id, " on ", $job->queue;
    return { pages => build_report($year) };
});

DESCRIPTION

What dequeue returns and what a task body receives as its first argument. A thin reader over the claimed row, plus the two methods that settle it.

A job object is a blessed hashref rather than the IV-ref-to-a-struct pattern used elsewhere in this ecosystem. That is deliberate: one is constructed per job run, which already costs a database round trip, so the allocation is noise - and a hashref needs no DESTROY, cannot leak, and can be subclassed by a hand-written runner. The IV-ref pattern earns its keep on per-request objects; this is not one.

METHODS

id / task / queue / state / priority / retries / attempts

Fields of the claimed row.

retries is the count so far and attempts the maximum, so $job->retries + 1 == $job->attempts means this is the last try - useful for a task that wants to escalate rather than fail quietly.

args

The decoded argument list as an arrayref. The same values are passed to the task body directly, so a body rarely needs this.

notes

The decoded notes hashref.

note

$job->note(pct => 50);
$job->note(stale_key => undef);      # deletes the key

Merge into the job's notes - the progress mechanism. A key set to undef is removed. The in-memory row is updated too, so $job->notes reflects the write without a re-read. Works while the job is active, which is the point.

log

$job->log('resizing image 3 of 10');
$job->log(warn => 'thumbnail source missing, using placeholder');

Append a line to the job's persistent log, readable later via $q->job_log($id), punk-queue job ID --log, and the admin UI's job page. One argument is an info line; two make the first the level (debug, info, warn or error). The queue writes the lifecycle rows around these automatically - claim, finish, failures with their retries - so a task only logs what the lifecycle cannot know. Always writes, whatever the queue's logging option says: a call the task author typed is not lifecycle noise.

info

The whole row as a plain hashref, without a round trip.

queue_object

The Punk::Queue this job was claimed from.

finish

$job->finish;
$job->finish($result);

Record the job as finished. Returns true when the transition applied. A task body does not need to call this: returning a value from the body does it, with the return value as the result.

fail

$job->fail($error);

Record the job as failed. As with finish, a body can simply die instead.

Both carry the row's retry count as an optimistic guard, so a job that was requeued while this worker was busy cannot be settled by the stale attempt.

SEE ALSO

Punk::Queue.

AUTHOR

LNATION <email@lnation.org>

LICENSE AND COPYRIGHT

This software is Copyright (c) 2026 by LNATION <email@lnation.org>.

This is free software, licensed under:

The Artistic License 2.0 (GPL Compatible)