The Job class is a structure for scheduling and performing background jobs in Platform. In order for the Job class to work, one must set up a cronjob running /Platform/Job/php/scheduler.php every minute. The Job class depends on running in a Linux environment with commands such as ps and kill being available.

A job is basically a function in a class and can be scheduled like this:

$job = Job::getJob('User', 'checkExpireDate', 60);
$job->save();

This will ensure that the function User::checkExpireDate() will be called once each hour.

Another way to schedule a job, could be:

$job = Job::getJob('User', 'sendEmailNotice', Job::FREQUENCY_ONCE);
$job->next_start = new Timestamp('2019-12-31 23:59:00');
$job->save();

This will schedule the job to run once at the given date and time.

The key to a given job is the class and the function (and the instance it is running from). So when you use getJob you will get an existing job if such a job exists or a new job if no existing job existed.

The frequency property described how often the job should run, and if it is a positive number, then it is considered the number of minutes between each run. In addition to this, one can specify the frequency_offset_from_end. If this is set to true, the frequency is counted from when the job have finished executing - otherwise it is counted from when the job started executing.

There are some special constants one can put as the frequency.

Job::FREQUENCY_PAUSED: This will create the job but make it paused meaning it will never execute. Job::FREQUENCY_ONCE: This will create a job which will run exactly once, and then become paused. If no specific runtime is given (through the next_time property) then as soon as possible is assumed. Job::FREQUENCY_ALWAYS: This will create a job which will always run, meaning that if it isn't running, it will be started. This can be used for daemons which should always be available.

The function which is called from a job, will always be passed the job as the first parameter. This can be used to reschedule the job or totally delete the job.

The property max_runtime can be used to specify for how long the job is allowed to run (in minutes). If not provided this defaults to 10 minutes. This is measured in real time and not processor time. If the time is exceeded the job is killed.

A basic capacity system is included, where one can set the number of slots a job takes. A slot is an abstract value, but the job system ensures that it will only execute jobs with a combined slot value of 100 at the same time. So if five jobs are running and they each have a slot size of 20, then no more jobs are allowed to run before one of these jobs terminates. This can ensure that the server doesn't become overloaded by running to many jobs when setting slot size correctly.

When using this, a job can also become delayed if there isn't any slot capacity available, when it is supposed to run. When there are delayed jobs, jobs are prioritized accordingly to when they were supposed to run, so earlier jobs are executed before later jobs.

If a job doesn't fit into available slot space, then no more jobs will be started, even though there could be another pending job, which could fit. This is to prevent smaller jobs from saturating the schedulation so there never becomes room for larger jobs.

Job is expected to produce no output if everything goes well and provide error output if something goes wrong, as the output from the job is collected as an error message.

If an error occurs the last_error_message will become updated with the error message and the error_count will be increased by 1.

Some job statistics is gathered on the job objects as properties.

run_count How many times the job has ran.

last_run_time How many minutes the job ran the last time it ran (as an integer).

average_run_time How many minutes the job spends on average running (as a double).

kill_count How many times the job was killed due to time limit being exceeded.