Cloud Jobs

You can set up a job which runs outside of the initial client request scope for however long you determine.

Take care when setting up too many jobs, or stabitity may suffer. Each one takes up processing and memory, so the least amount of jobs, the better.

cloud.job

Limitations

Jobs are performed outside of the client lifecycle, so some functionality is not available in the job file scope.

Heads Up!

Most importantly, you can't pass any client connections to a job file. A Job basically runs in a bubble, with limited access to the outside world.

Running Jobs

Job files are initialized at each load of Cloud server process. During the process initialization, any job files residing in the /home/cloud/jobs folder will be run. You can use this time to kickstart your job related processes.

Additionally, you'll need to add the job filename to the /home/cloud/jobs/run.lua file, to "whitelist" it.

Heads Up!

Any job files not listed in the run.lua will not be triggered when the cloud process is loaded.

Creating a Job

Jobs are set up in files very similar the api files. They live in the /home/cloud/jobs directory and are built with the job module.

An example job file might look like:

--jobs/change_prize.lua
local job_proc = function(log)
  log('change prize')
end
cloud.job.run(1000, 5000, 5, job_proc, cloud.log)

After this job file is initialized, it will:

  1. Wait 1 second.
  2. Run the job_proc
  3. Wait 5 seconds.
  4. Run the job_proc
  5. Repeat steps 3 and 4, four times.

You can use enclosures in a job file, but remember that you cannot access any functions that rely on a client connection. Though a 'job' runs "headless", you can create stand-alone network connections from within the job process.

Example

local request = cloud.network.request
local log = cloud.log
local job_proc = function()
  local res, err = request("https://google.com")
  if not err then
    log(res)
  end
end
cloud.job.run(5, 5000, 100, job_proc)

This job pings "google.com" 100 times, about once every 5 seconds.

Run

.run

Signature

cloud.job.run( start_delay, update_interval, loop_count, proc_func[, arg[, ...]] )

Parameters

Name Description Type Default Required
start_delay Milliseconds before starting the first process run. number 0 Y
update_interval Milliseconds between process runs, after first run. number 0 Y
loop_count Process loops. Can be -1 for infinite looping. number 0 Y
proc_func The job process function to run. function nil Y
args A comma delimited list of args to pass to the process. string nil N

Returns

A jobid that can be passed to job.stop if needed.

Example

local log = cloud.log
local proc = function()
  log('proc tick')
end
local jobid = cloud.job.run(100, 2000, 10, proc)

Stop

.stop

Signature

cloud.job.stop( jobid )

Parameters

Name Description Type Default Required
jobid The jobid returned from the job.run command. string nil Y

Returns

A success boolean, or nil and an error

Example

local success, err = cloud.job.stop( jobid )
if success then
  cloud.log('job stopped')
end

Refreshing Jobs

If you add new job files to the run.lua, you will need to run, from the command line:

sudo cloud up