Anwaydocsv0.5.3

Jobs

The fields of a job, and the states that a job goes through.

A job is one unit of work: a type, a list of args, and options. This page shows how to make a job, which fields it has, and what happens to it after a push.

Make a job

Anway.push('report.build', [42], queue: 'reports', retry: 5)

job = Anway::Job.new('report.build', [42], queue: 'reports', retry: 5)

Anway.client.push(job)
job, err := anway.NewJob("report.build", []any{42}, anway.Options{
	Queue: "reports",
	Retry: anway.Int(5),
})
if err != nil {
	return err
}

return client.Push(ctx, job)
const job = new Anway.Job('report.build', [42], { queue: 'reports', retry: 5 });

await client.push(job);

The first argument is the event. It goes to the server as the job type (jobtype), and it tells the worker which handler to run. In a Ruby Anway::Worker class, the default event is the class name.

The client makes a new jid for each job. Args must be JSON types, because a worker in another language reads them. In Ruby, hash keys must be strings.

Fields

The server reads these fields of a job. The client sets them from the options that you give. See the option names of each language in Versions.

FieldDefaultMeaning
jidMade by the clientThe job id, 1 to 256 bytes. It must be unique. A push with a jid that exists fails.
jobtypeRequiredThe event. The worker runs the handler for it.
argsRequiredA JSON array. null becomes [].
queuedefaultThe queue name. See Queues.
reserve_for1800Seconds that a worker can hold the job. The minimum is 60.
atNowA time to run the job later. See Scheduled jobs.
retry25Retries after a failure. 0 discards the job at the first failure. -1 sends it to the Dead set at once. See Retries.
backtrace0Lines of the error backtrace to keep. The Ruby Anway::Worker default is 30.
created_atServer timeWhen the job was made.
customNoneA JSON hash for your own keys, and for the options of some features.
enqueued_atSet by the serverWhen the job entered its queue.
failureSet by the serverData of the last failure.

Custom keys with a meaning

The server reads some keys in custom. The clients set them from options, so you do not write them by hand.

KeyOptionEffect
unique_for, unique_untilunique_for, unique_untilBlock a duplicate job. See Unique jobs.
expires_in, expires_atexpires_in, expires_atDiscard a job that waits too long. See Unique jobs.
on_deadon_deadPush a notice job when this job dies. See Retries.
bidNoneAdd the job to a batch. See Batches.
tracktrackRecord the progress of the job. See Batches.

The keys from options win over a key with the same name in your own custom hash.

States

PUSH --> SCHEDULED (future "at")
  |          |
  |          v  time arrives
  +----> ENQUEUED <-------------- RETRIES
             |                       ^  |
             | FETCH                 |  | no retries remain
             v                       |  v
          WORKING ---- FAIL or ------+  DEAD
             |         reservation
             | ACK     expires
             v
          removed
StateMeaning
ScheduledThe job has an at time in the future. It waits until that time.
EnqueuedThe job waits in its queue for a worker.
WorkingA worker fetched the job and holds a reservation for reserve_for seconds.
RetriesThe job failed. It waits for its next attempt.
DeadThe job failed and has no retries left. It stays until you requeue, kill, or discard it.
  • ACK removes the job. The server does not keep finished jobs.
  • FAIL and an expired reservation follow the same path.
  • An ACK or FAIL for a job that is not in Working returns an error. This can occur after the reservation expired, or after an operator killed the running job.
  • The first fetch of a job has no failure field.

Delivery

Delivery is at least once. A worker can get the same job again, for example when it crashed before its ACK, or when its reservation expired. Make each handler idempotent: a second run must not do the work two times.

Set reserve_for above the longest time that a job can run. If a job runs longer, the server gives it to another worker while the first one still runs it.

On this page