Queue

mash.queue · Platform

mash.queue looks at the background jobs that scripts have started. You make a job with mash.scripts.queue(...), which hands you a job object straight away. mash.queue is for coming back to it later, by id, or for listing what’s waiting.

How it works

A job is a handle, not the work. The job runs on a worker, apart from your script. The handle tells you how it’s going. Its status is queued, started, completed, failed, stopping or stopped, and unknown for an id it can’t find. There are true/false shortcuts as well: queued (or waiting), processing (or started), completed, done (completed or stopped), failed (or errored), cancelled (or stopped).

result is what the script returned. It’s null until the job is finished, and also null if the script returned nothing.

You only see your own tenant’s jobs. On a shared Foldr, jobs() lists the queued, delayed and running jobs for your own organisation only. A job id from another organisation reads as unknown.

cancel() removes a job that hasn’t started, or asks a running one to stop. It returns false for a job that isn’t your organisation’s.

Common tasks

Start a job, remember its id and check on it later (in another run):

set job to mash.scripts.queue("Rebuild index", null, null, {share: "Finance"})
printline "Started job {{job.id}}"

set job to mash.queue.get("the-id-you-saved")
if job.completed
    printline "Finished: {{job.result}}"
elseif job.failed
    printline "It failed"
else
    printline "Still going ({{job.status}})"
end

See what’s waiting:

set jobs to mash.queue.jobs()
printline "{{jobs.count()}} jobs in the queue"
each jobs as job
    printline "{{job.id}}: {{job.status}}"
end

Watch out for

• A job isn’t a promise. If the workers are busy or stopped, it waits. A script that needs the answer now should use mash.scripts.run, which waits for it.
• Don’t poll in a tight loop. Check once per run and let the next run pick it up.
• A job can be refused as a duplicate. Queueing a script that is already queued or running stops with an “already queued or running” error.
• A queue is shared by every script. jobs() lists them all, so a busy tenant shows a long list.

See also

mash.scripts, and Reacting to events for how scripts start.

Methods

get

queue.get(jobId: mixed)

Get a queued job by ID

jobs

queue.jobs() → Collection

List all queued, delayed, and reserved jobs.