====== Job class ======

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.

===== Scheduling a job =====

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:

==== Running at a specific interval ====

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.

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

==== Running once (at a specific time) ====

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

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

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

==== Running daily (at a specific time) ====

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

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

==== Running always (daemon job) ====

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

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

===== Running a job =====
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.

===== Timing =====
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.

===== Modifying the job on the fly =====
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.

===== Limiting run time =====
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.

===== Job capacity =====
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.

===== Errors in job =====

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.

===== Job statistics =====
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.

===== Server jobs =====

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'':

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