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.

Jobs are usually running in the context of an instance, but it is also possible to have serverjobs, which isn't related to a specific instance. See later.

A job is basically a reference to a function in a class that will be called at given times. This can be initiated in a few different ways:

A job can run in a specific interval. For example the following code will ensure that the function User::checkExpireDate() will be called once each hour.

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

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

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

If next_start is omitted, the job will run as soon as possible.

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

$job = Job::getJob('Team', 'AdvertiseWork', Job::FREQUENCY_SETTIME);
$job->next_start = new Time('2019-12-31 20:00:00');
$job->save();

This will start the given job if it isn't already running. If the job exits, it will be started again ASAP.

$job = Job::getJob('Chat', 'NetworkDaemon', Job::FREQUENCY_ALWAYS);
$job->save();

The job will be executed by calling the provided function in the provided class, with the job itself as a parameter. The correct instance is already activated, but please be aware that the job is provided in read mode, so we don't block the job if the execution of the function takes a long time.

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 the job will execute as soon as possible. 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 job function, 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.

As mentioned earlier jobs run in relation to instances. It is also possible to have a server job, which is a job that doesn't run in relation to any instance, but in relation to the server itself. To create a server job, just use getServerJob instead of getJob:

$server_job = Job::getServerJob('Server', 'clearTempFiles', 24*60);
$server_job->save();