Differences

This shows you the differences between two versions of the page.

--- job_class [2019/10/21 09:48] – [Job capacity] sahl
+++ job_class [2023/06/27 07:30] (current) – sahl
@@ Line 3: / Line 3: @@
 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 function in a class and can be scheduled like this:
+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>
@@ Line 13: / Line 19: @@
 </code>
-This will ensure that the function ''User::checkExpireDate()'' will be called once each hour.
+==== Running once (at a specific time) ====
-Another way to schedule a job, could be:
+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 Timestamp('2019-12-31 23:59:00');
+$job->next_start = new Time('2019-12-31 23:59:00');
 $job->save();
 </code>
-This will schedule the job to run once at the given date and time.
+If //next_start// is omitted, the job will run as soon as possible.
-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.
+==== 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 =====
@@ Line 34: / Line 60: @@
 ''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_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 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 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 =====
@@ Line 50: / Line 76: @@
 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>