lib/classes/task/adhoc_task.php

   1 <?php
   2 // This file is part of Moodle - http://moodle.org/
   3 //
   4 // Moodle is free software: you can redistribute it and/or modify
   5 // it under the terms of the GNU General Public License as published by
   6 // the Free Software Foundation, either version 3 of the License, or
   7 // (at your option) any later version.
   8 //
   9 // Moodle is distributed in the hope that it will be useful,
  10 // but WITHOUT ANY WARRANTY; without even the implied warranty of
  11 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12 // GNU General Public License for more details.
  13 //
  14 // You should have received a copy of the GNU General Public License
  15 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
  16
  17 /**
  18  * Adhoc task abstract class.
  19  *
  20  * All background tasks should extend this class.
  21  *
  22  * @package    core
  23  * @category   task
  24  * @copyright  2013 Damyon Wiese
  25  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  26  */
  27
  28 namespace core\task;
  29
  30 /**
  31  * Abstract class defining an adhoc task.
  32  * @copyright  2013 Damyon Wiese
  33  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  34  */
  35 abstract class adhoc_task extends task_base {
  36
  37     /** @var string $customdata - Custom data required for when this task is executed. */
  38     private $customdata = '';
  39
  40     /** @var integer|null $id - Adhoc tasks each have their own database record id. */
  41     private $id = null;
  42
  43     /** @var integer|null $userid - Adhoc tasks may choose to run as a specific user. */
  44     private $userid = null;
  45
  46     /** @var \core\lock\lock The concurrency task lock for this task. */
  47     private $concurrencylock = null;
  48
  49     /** @var int $attemptsavailable - The remaining attempts of the task. */
  50     private $attemptsavailable = 12;
  51
  52     /**
  53      * Provide default implementation of the task name for backward compatibility. Extending classes are expected to implement
  54      * this method to provide a descriptive name for the task (shown to admins)
  55      *
  56      * @return string
  57      */
  58     public function get_name() {
  59         $classparts = explode('\\', get_called_class());
  60         $classname = end($classparts);
  61
  62         // Try to make human readable, capitalized and with spaces.
  63         return ucfirst(str_replace('_', ' ', $classname));
  64     }
  65
  66     /**
  67      * Setter for $id.
  68      * @param int|null $id
  69      */
  70     public function set_id($id) {
  71         $this->id = $id;
  72     }
  73
  74     /**
  75      * Getter for $userid.
  76      * @return int|null $userid
  77      */
  78     public function get_userid() {
  79         return $this->userid;
  80     }
  81
  82     /**
  83      * Setter for $customdata.
  84      * @param mixed $customdata (anything that can be handled by json_encode)
  85      */
  86     public function set_custom_data($customdata) {
  87         $this->customdata = json_encode($customdata);
  88     }
  89
  90     /**
  91      * Alternate setter for $customdata. Expects the data as a json_encoded string.
  92      * @param string $customdata json_encoded string
  93      */
  94     public function set_custom_data_as_string($customdata) {
  95         $this->customdata = $customdata;
  96     }
  97
  98     /**
  99      * Getter for $customdata.
 100      * @return mixed (anything that can be handled by json_decode).
 101      */
 102     public function get_custom_data() {
 103         return json_decode($this->customdata);
 104     }
 105
 106     /**
 107      * Alternate getter for $customdata.
 108      * @return string this is the raw json encoded version.
 109      */
 110     public function get_custom_data_as_string() {
 111         return $this->customdata;
 112     }
 113
 114     /**
 115      * Getter for $id.
 116      * @return int|null $id
 117      */
 118     public function get_id() {
 119         return $this->id;
 120     }
 121
 122     /**
 123      * Setter for $userid.
 124      * @param int|null $userid
 125      */
 126     public function set_userid($userid) {
 127         $this->userid = $userid;
 128     }
 129
 130     /**
 131      * Returns default concurrency limit for this task.
 132      *
 133      * @return int default concurrency limit
 134      */
 135     protected function get_default_concurrency_limit(): int {
 136         global $CFG;
 137
 138         if (isset($CFG->task_concurrency_limit_default)) {
 139             return (int) $CFG->task_concurrency_limit_default;
 140         }
 141         return 0;
 142     }
 143
 144     /**
 145      * Returns effective concurrency limit for this task.
 146      *
 147      * @return int effective concurrency limit for this task
 148      */
 149     final public function get_concurrency_limit(): int {
 150         global $CFG;
 151
 152         $classname = get_class($this);
 153
 154         if (isset($CFG->task_concurrency_limit[$classname])) {
 155             return (int) $CFG->task_concurrency_limit[$classname];
 156         }
 157         return $this->get_default_concurrency_limit();
 158     }
 159
 160     /**
 161      * Sets concurrency task lock.
 162      *
 163      * @param   \core\lock\lock $lock concurrency lock to be set
 164      */
 165     final public function set_concurrency_lock(\core\lock\lock $lock): void {
 166         $this->concurrencylock = $lock;
 167     }
 168
 169     /**
 170      * Release the concurrency lock for this task type.
 171      */
 172     final public function release_concurrency_lock(): void {
 173         if ($this->concurrencylock) {
 174             $this->concurrencylock->release();
 175         }
 176     }
 177
 178     /**
 179      * Set the remaining attempts of the task.
 180      *
 181      * @param int $attemptsavailable Number of the remaining attempts of the task.
 182      */
 183     public function set_attempts_available(int $attemptsavailable): void {
 184         $this->attemptsavailable = $attemptsavailable;
 185     }
 186
 187     /**
 188      * Get the remaining attempts of the task.
 189      *
 190      * @return int Number of the remaining attempts of the task.
 191      */
 192     public function get_attempts_available(): int {
 193         return $this->attemptsavailable;
 194     }
 195
 196     /**
 197      * Used to indicate if the task should be re-run if it fails.
 198      * By default, tasks will be retried until they succeed, other tasks can override this method to change this behaviour.
 199      *
 200      * @return bool true if the task should be retried until it succeeds, false otherwise.
 201      */
 202     public function retry_until_success(): bool {
 203         return true;
 204     }
 205 }