Jobs and timers

jobs and timers run a function later: once, or again and again. This page shows both in one script, then says how they differ and what happens when one fails.

A first script

-- once, in the background
jobs.enqueue(function()
  log.info("ran once, in the background")
end)

-- every five minutes; the name must be unique
jobs.every("cleanup", 5, function()
  log.info("every five minutes")
end)

-- once, after ten seconds
timers.after(10, function()
  log.info("ten seconds passed")
end)

-- every two seconds, until the third time
local ticks = 0
local id
id = timers.every(2, function()
  ticks = ticks + 1
  log.info("tick {Count}", ticks)
  if ticks == 3 then
    timers.cancel(id)
  end
end)

tcli scripts

tcli scripts loads this script and runs none of the functions, because it does not start the services. To see them run, set log_to_file = true in [logging] (see Logging and jobs), start tcli watch, stop it with Ctrl-c and read logs/tilde-<date>.log in the Tilde folder. tt runs them too.

Jobs

• jobs.enqueue(fn) runs fn once, in the background, as soon as a worker is free.
• jobs.every(name, minutes, fn) runs fn every minutes minutes. minutes is greater than zero and at most about 49 days, and may have a fraction (0.5). The first run is one interval from now. The name must be new: a second job with the same name is an error.
• jobs.remove(name) stops a recurring job that your scripts created. An unknown name is ignored.
• jobs.list() returns one table for each job of the scheduler: name, kind (queued, recurring or tracked), state (pending, running or idle), and when they apply interval_minutes, last_error and progress. It also lists the jobs that Tilde runs for itself.

Jobs run on the workers of the scheduler. workers in the [jobs] table of config.toml says how many.

Timers

• timers.after(seconds, fn) runs fn once after seconds seconds.
• timers.every(seconds, fn) runs fn every seconds seconds, the first time after one interval. A tick that finds the previous run still going is skipped.
• Both return the id of the timer, a text. timers.cancel(id) cancels it, also a run that is waiting to start, and returns true. It returns false when there is no such timer, when a one-shot timer has run already or when the id is not one of yours.
• seconds is greater than zero and at most 49 days.

What they share

• Lua runs one function at a time. A job or a timer that has to wait for its turn waits, and a Lua job that waits still occupies a worker.
• Each run has the limit on instructions of its own.
• A function that fails is reported as a script_error; the source is jobs.every NAME, jobs.enqueue #N, timers.after #N or timers.every #N. A job also raises job_failed with the name, the kind and a generic error; the real message is in the script_error (see Events). A recurring job or timer runs again at its next tick.
• A reload of the scripts removes the recurring jobs, cancels the queued jobs that have not started and cancels every timer, also a run that was waiting.

The functions are listed in the Lua API reference.