[Summary view] [Print] [Text view]

   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   * Scheduled and adhoc task management.
  19   *
  20   * @package    core
  21   * @category   task
  22   * @copyright  2013 Damyon Wiese
  23   * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  24   */
  25  namespace core\task;
  26  
  27  define('CORE_TASK_TASKS_FILENAME', 'db/tasks.php');
  28  /**
  29   * Collection of task related methods.
  30   *
  31   * Some locking rules for this class:
  32   * All changes to scheduled tasks must be protected with both - the global cron lock and the lock
  33   * for the specific scheduled task (in that order). Locks must be released in the reverse order.
  34   * @copyright  2013 Damyon Wiese
  35   * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  36   */
  37  class manager {
  38  
  39      /**
  40       * Given a component name, will load the list of tasks in the db/tasks.php file for that component.
  41       *
  42       * @param string $componentname - The name of the component to fetch the tasks for.
  43       * @return \core\task\scheduled_task[] - List of scheduled tasks for this component.
  44       */
  45      public static function load_default_scheduled_tasks_for_component($componentname) {
  46          $dir = \core_component::get_component_directory($componentname);
  47  
  48          if (!$dir) {
  49              return array();
  50          }
  51  
  52          $file = $dir . '/' . CORE_TASK_TASKS_FILENAME;
  53          if (!file_exists($file)) {
  54              return array();
  55          }
  56  
  57          $tasks = null;
  58          require_once($file);
  59  
  60          if (!isset($tasks)) {
  61              return array();
  62          }
  63  
  64          $scheduledtasks = array();
  65  
  66          foreach ($tasks as $task) {
  67              $record = (object) $task;
  68              $scheduledtask = self::scheduled_task_from_record($record);
  69              // Safety check in case the task in the DB does not match a real class (maybe something was uninstalled).
  70              if ($scheduledtask) {
  71                  $scheduledtask->set_component($componentname);
  72                  $scheduledtasks[] = $scheduledtask;
  73              }
  74          }
  75  
  76          return $scheduledtasks;
  77      }
  78  
  79      /**
  80       * Update the database to contain a list of scheduled task for a component.
  81       * The list of scheduled tasks is taken from @load_scheduled_tasks_for_component.
  82       * Will throw exceptions for any errors.
  83       *
  84       * @param string $componentname - The frankenstyle component name.
  85       */
  86      public static function reset_scheduled_tasks_for_component($componentname) {
  87          global $DB;
  88          $cronlockfactory = \core\lock\lock_config::get_lock_factory('cron');
  89  
  90          if (!$cronlock = $cronlockfactory->get_lock('core_cron', 10, 60)) {
  91              throw new \moodle_exception('locktimeout');
  92          }
  93          $tasks = self::load_default_scheduled_tasks_for_component($componentname);
  94  
  95          $tasklocks = array();
  96          foreach ($tasks as $taskid => $task) {
  97              $classname = get_class($task);
  98              if (strpos($classname, '\\') !== 0) {
  99                  $classname = '\\' . $classname;
 100              }
 101  
 102              // If there is an existing task with a custom schedule, do not override it.
 103              $currenttask = self::get_scheduled_task($classname);
 104              if ($currenttask && $currenttask->is_customised()) {
 105                  $tasks[$taskid] = $currenttask;
 106              }
 107  
 108              if (!$lock = $cronlockfactory->get_lock($classname, 10, 60)) {
 109                  // Could not get all the locks required - release all locks and fail.
 110                  foreach ($tasklocks as $tasklock) {
 111                      $tasklock->release();
 112                  }
 113                  $cronlock->release();
 114                  throw new \moodle_exception('locktimeout');
 115              }
 116              $tasklocks[] = $lock;
 117          }
 118  
 119          // Got a lock on cron and all the tasks for this component, time to reset the config.
 120          $DB->delete_records('task_scheduled', array('component' => $componentname));
 121          foreach ($tasks as $task) {
 122              $record = self::record_from_scheduled_task($task);
 123              $DB->insert_record('task_scheduled', $record);
 124          }
 125  
 126          // Release the locks.
 127          foreach ($tasklocks as $tasklock) {
 128              $tasklock->release();
 129          }
 130  
 131          $cronlock->release();
 132      }
 133  
 134      /**
 135       * Queue an adhoc task to run in the background.
 136       *
 137       * @param \core\task\adhoc_task $task - The new adhoc task information to store.
 138       * @return boolean - True if the config was saved.
 139       */
 140      public static function queue_adhoc_task(adhoc_task $task) {
 141          global $DB;
 142  
 143          $record = self::record_from_adhoc_task($task);
 144          // Schedule it immediately.
 145          $record->nextruntime = time() - 1;
 146          $result = $DB->insert_record('task_adhoc', $record);
 147  
 148          return $result;
 149      }
 150  
 151      /**
 152       * Change the default configuration for a scheduled task.
 153       * The list of scheduled tasks is taken from {@link load_scheduled_tasks_for_component}.
 154       *
 155       * @param \core\task\scheduled_task $task - The new scheduled task information to store.
 156       * @return boolean - True if the config was saved.
 157       */
 158      public static function configure_scheduled_task(scheduled_task $task) {
 159          global $DB;
 160          $cronlockfactory = \core\lock\lock_config::get_lock_factory('cron');
 161  
 162          if (!$cronlock = $cronlockfactory->get_lock('core_cron', 10, 60)) {
 163              throw new \moodle_exception('locktimeout');
 164          }
 165  
 166          $classname = get_class($task);
 167          if (strpos($classname, '\\') !== 0) {
 168              $classname = '\\' . $classname;
 169          }
 170          if (!$lock = $cronlockfactory->get_lock($classname, 10, 60)) {
 171              $cronlock->release();
 172              throw new \moodle_exception('locktimeout');
 173          }
 174  
 175          $original = $DB->get_record('task_scheduled', array('classname'=>$classname), 'id', MUST_EXIST);
 176  
 177          $record = self::record_from_scheduled_task($task);
 178          $record->id = $original->id;
 179          $record->nextruntime = $task->get_next_scheduled_time();
 180          $result = $DB->update_record('task_scheduled', $record);
 181  
 182          $lock->release();
 183          $cronlock->release();
 184          return $result;
 185      }
 186  
 187      /**
 188       * Utility method to create a DB record from a scheduled task.
 189       *
 190       * @param \core\task\scheduled_task $task
 191       * @return \stdClass
 192       */
 193      public static function record_from_scheduled_task($task) {
 194          $record = new \stdClass();
 195          $record->classname = get_class($task);
 196          if (strpos($record->classname, '\\') !== 0) {
 197              $record->classname = '\\' . $record->classname;
 198          }
 199          $record->component = $task->get_component();
 200          $record->blocking = $task->is_blocking();
 201          $record->customised = $task->is_customised();
 202          $record->lastruntime = $task->get_last_run_time();
 203          $record->nextruntime = $task->get_next_run_time();
 204          $record->faildelay = $task->get_fail_delay();
 205          $record->hour = $task->get_hour();
 206          $record->minute = $task->get_minute();
 207          $record->day = $task->get_day();
 208          $record->dayofweek = $task->get_day_of_week();
 209          $record->month = $task->get_month();
 210          $record->disabled = $task->get_disabled();
 211  
 212          return $record;
 213      }
 214  
 215      /**
 216       * Utility method to create a DB record from an adhoc task.
 217       *
 218       * @param \core\task\adhoc_task $task
 219       * @return \stdClass
 220       */
 221      public static function record_from_adhoc_task($task) {
 222          $record = new \stdClass();
 223          $record->classname = get_class($task);
 224          if (strpos($record->classname, '\\') !== 0) {
 225              $record->classname = '\\' . $record->classname;
 226          }
 227          $record->id = $task->get_id();
 228          $record->component = $task->get_component();
 229          $record->blocking = $task->is_blocking();
 230          $record->nextruntime = $task->get_next_run_time();
 231          $record->faildelay = $task->get_fail_delay();
 232          $record->customdata = $task->get_custom_data_as_string();
 233  
 234          return $record;
 235      }
 236  
 237      /**
 238       * Utility method to create an adhoc task from a DB record.
 239       *
 240       * @param \stdClass $record
 241       * @return \core\task\adhoc_task
 242       */
 243      public static function adhoc_task_from_record($record) {
 244          $classname = $record->classname;
 245          if (strpos($classname, '\\') !== 0) {
 246              $classname = '\\' . $classname;
 247          }
 248          if (!class_exists($classname)) {
 249              debugging("Failed to load task: " . $classname, DEBUG_DEVELOPER);
 250              return false;
 251          }
 252          $task = new $classname;
 253          if (isset($record->nextruntime)) {
 254              $task->set_next_run_time($record->nextruntime);
 255          }
 256          if (isset($record->id)) {
 257              $task->set_id($record->id);
 258          }
 259          if (isset($record->component)) {
 260              $task->set_component($record->component);
 261          }
 262          $task->set_blocking(!empty($record->blocking));
 263          if (isset($record->faildelay)) {
 264              $task->set_fail_delay($record->faildelay);
 265          }
 266          if (isset($record->customdata)) {
 267              $task->set_custom_data_as_string($record->customdata);
 268          }
 269  
 270          return $task;
 271      }
 272  
 273      /**
 274       * Utility method to create a task from a DB record.
 275       *
 276       * @param \stdClass $record
 277       * @return \core\task\scheduled_task
 278       */
 279      public static function scheduled_task_from_record($record) {
 280          $classname = $record->classname;
 281          if (strpos($classname, '\\') !== 0) {
 282              $classname = '\\' . $classname;
 283          }
 284          if (!class_exists($classname)) {
 285              debugging("Failed to load task: " . $classname, DEBUG_DEVELOPER);
 286              return false;
 287          }
 288          /** @var \core\task\scheduled_task $task */
 289          $task = new $classname;
 290          if (isset($record->lastruntime)) {
 291              $task->set_last_run_time($record->lastruntime);
 292          }
 293          if (isset($record->nextruntime)) {
 294              $task->set_next_run_time($record->nextruntime);
 295          }
 296          if (isset($record->customised)) {
 297              $task->set_customised($record->customised);
 298          }
 299          if (isset($record->component)) {
 300              $task->set_component($record->component);
 301          }
 302          $task->set_blocking(!empty($record->blocking));
 303          if (isset($record->minute)) {
 304              $task->set_minute($record->minute);
 305          }
 306          if (isset($record->hour)) {
 307              $task->set_hour($record->hour);
 308          }
 309          if (isset($record->day)) {
 310              $task->set_day($record->day);
 311          }
 312          if (isset($record->month)) {
 313              $task->set_month($record->month);
 314          }
 315          if (isset($record->dayofweek)) {
 316              $task->set_day_of_week($record->dayofweek);
 317          }
 318          if (isset($record->faildelay)) {
 319              $task->set_fail_delay($record->faildelay);
 320          }
 321          if (isset($record->disabled)) {
 322              $task->set_disabled($record->disabled);
 323          }
 324  
 325          return $task;
 326      }
 327  
 328      /**
 329       * Given a component name, will load the list of tasks from the scheduled_tasks table for that component.
 330       * Do not execute tasks loaded from this function - they have not been locked.
 331       * @param string $componentname - The name of the component to load the tasks for.
 332       * @return \core\task\scheduled_task[]
 333       */
 334      public static function load_scheduled_tasks_for_component($componentname) {
 335          global $DB;
 336  
 337          $tasks = array();
 338          // We are just reading - so no locks required.
 339          $records = $DB->get_records('task_scheduled', array('component' => $componentname), 'classname', '*', IGNORE_MISSING);
 340          foreach ($records as $record) {
 341              $task = self::scheduled_task_from_record($record);
 342              // Safety check in case the task in the DB does not match a real class (maybe something was uninstalled).
 343              if ($task) {
 344                  $tasks[] = $task;
 345              }
 346          }
 347  
 348          return $tasks;
 349      }
 350  
 351      /**
 352       * This function load the scheduled task details for a given classname.
 353       *
 354       * @param string $classname
 355       * @return \core\task\scheduled_task or false
 356       */
 357      public static function get_scheduled_task($classname) {
 358          global $DB;
 359  
 360          if (strpos($classname, '\\') !== 0) {
 361              $classname = '\\' . $classname;
 362          }
 363          // We are just reading - so no locks required.
 364          $record = $DB->get_record('task_scheduled', array('classname'=>$classname), '*', IGNORE_MISSING);
 365          if (!$record) {
 366              return false;
 367          }
 368          return self::scheduled_task_from_record($record);
 369      }
 370  
 371      /**
 372       * This function load the default scheduled task details for a given classname.
 373       *
 374       * @param string $classname
 375       * @return \core\task\scheduled_task or false
 376       */
 377      public static function get_default_scheduled_task($classname) {
 378          $task = self::get_scheduled_task($classname);
 379          $componenttasks = array();
 380  
 381          // Safety check in case no task was found for the given classname.
 382          if ($task) {
 383              $componenttasks = self::load_default_scheduled_tasks_for_component($task->get_component());
 384          }
 385  
 386          foreach ($componenttasks as $componenttask) {
 387              if (get_class($componenttask) == get_class($task)) {
 388                  return $componenttask;
 389              }
 390          }
 391  
 392          return false;
 393      }
 394  
 395      /**
 396       * This function will return a list of all the scheduled tasks that exist in the database.
 397       *
 398       * @return \core\task\scheduled_task[]
 399       */
 400      public static function get_all_scheduled_tasks() {
 401          global $DB;
 402  
 403          $records = $DB->get_records('task_scheduled', null, 'component, classname', '*', IGNORE_MISSING);
 404          $tasks = array();
 405  
 406          foreach ($records as $record) {
 407              $task = self::scheduled_task_from_record($record);
 408              // Safety check in case the task in the DB does not match a real class (maybe something was uninstalled).
 409              if ($task) {
 410                  $tasks[] = $task;
 411              }
 412          }
 413  
 414          return $tasks;
 415      }
 416  
 417      /**
 418       * This function will dispatch the next adhoc task in the queue. The task will be handed out
 419       * with an open lock - possibly on the entire cron process. Make sure you call either
 420       * {@link adhoc_task_failed} or {@link adhoc_task_complete} to release the lock and reschedule the task.
 421       *
 422       * @param int $timestart
 423       * @return \core\task\adhoc_task or null if not found
 424       */
 425      public static function get_next_adhoc_task($timestart) {
 426          global $DB;
 427          $cronlockfactory = \core\lock\lock_config::get_lock_factory('cron');
 428  
 429          if (!$cronlock = $cronlockfactory->get_lock('core_cron', 10)) {
 430              throw new \moodle_exception('locktimeout');
 431          }
 432  
 433          $where = '(nextruntime IS NULL OR nextruntime < :timestart1)';
 434          $params = array('timestart1' => $timestart);
 435          $records = $DB->get_records_select('task_adhoc', $where, $params);
 436  
 437          foreach ($records as $record) {
 438  
 439              if ($lock = $cronlockfactory->get_lock('adhoc_' . $record->id, 10)) {
 440                  $classname = '\\' . $record->classname;
 441                  $task = self::adhoc_task_from_record($record);
 442                  // Safety check in case the task in the DB does not match a real class (maybe something was uninstalled).
 443                  if (!$task) {
 444                      $lock->release();
 445                      continue;
 446                  }
 447  
 448                  $task->set_lock($lock);
 449                  if (!$task->is_blocking()) {
 450                      $cronlock->release();
 451                  } else {
 452                      $task->set_cron_lock($cronlock);
 453                  }
 454                  return $task;
 455              }
 456          }
 457  
 458          // No tasks.
 459          $cronlock->release();
 460          return null;
 461      }
 462  
 463      /**
 464       * This function will dispatch the next scheduled task in the queue. The task will be handed out
 465       * with an open lock - possibly on the entire cron process. Make sure you call either
 466       * {@link scheduled_task_failed} or {@link scheduled_task_complete} to release the lock and reschedule the task.
 467       *
 468       * @param int $timestart - The start of the cron process - do not repeat any tasks that have been run more recently than this.
 469       * @return \core\task\scheduled_task or null
 470       */
 471      public static function get_next_scheduled_task($timestart) {
 472          global $DB;
 473          $cronlockfactory = \core\lock\lock_config::get_lock_factory('cron');
 474  
 475          if (!$cronlock = $cronlockfactory->get_lock('core_cron', 10)) {
 476              throw new \moodle_exception('locktimeout');
 477          }
 478  
 479          $where = "(lastruntime IS NULL OR lastruntime < :timestart1)
 480                    AND (nextruntime IS NULL OR nextruntime < :timestart2)
 481                    AND disabled = 0";
 482          $params = array('timestart1' => $timestart, 'timestart2' => $timestart);
 483          $records = $DB->get_records_select('task_scheduled', $where, $params);
 484  
 485          $pluginmanager = \core_plugin_manager::instance();
 486  
 487          foreach ($records as $record) {
 488  
 489              if ($lock = $cronlockfactory->get_lock(($record->classname), 10)) {
 490                  $classname = '\\' . $record->classname;
 491                  $task = self::scheduled_task_from_record($record);
 492                  // Safety check in case the task in the DB does not match a real class (maybe something was uninstalled).
 493                  if (!$task) {
 494                      $lock->release();
 495                      continue;
 496                  }
 497  
 498                  $task->set_lock($lock);
 499  
 500                  // See if the component is disabled.
 501                  $plugininfo = $pluginmanager->get_plugin_info($task->get_component());
 502  
 503                  if ($plugininfo) {
 504                      if (($plugininfo->is_enabled() === false) && !$task->get_run_if_component_disabled()) {
 505                          mtrace($task->get_name().' skipped - the component '.$task->get_component().' is disabled');
 506                          $lock->release();
 507                          continue;
 508                      }
 509                  }
 510  
 511                  if (!$task->is_blocking()) {
 512                      $cronlock->release();
 513                  } else {
 514                      $task->set_cron_lock($cronlock);
 515                  }
 516                  return $task;
 517              }
 518          }
 519  
 520          // No tasks.
 521          $cronlock->release();
 522          return null;
 523      }
 524  
 525      /**
 526       * This function indicates that an adhoc task was not completed successfully and should be retried.
 527       *
 528       * @param \core\task\adhoc_task $task
 529       */
 530      public static function adhoc_task_failed(adhoc_task $task) {
 531          global $DB;
 532          $delay = $task->get_fail_delay();
 533  
 534          // Reschedule task with exponential fall off for failing tasks.
 535          if (empty($delay)) {
 536              $delay = 60;
 537          } else {
 538              $delay *= 2;
 539          }
 540  
 541          // Max of 24 hour delay.
 542          if ($delay > 86400) {
 543              $delay = 86400;
 544          }
 545  
 546          $classname = get_class($task);
 547          if (strpos($classname, '\\') !== 0) {
 548              $classname = '\\' . $classname;
 549          }
 550  
 551          $task->set_next_run_time(time() + $delay);
 552          $task->set_fail_delay($delay);
 553          $record = self::record_from_adhoc_task($task);
 554          $DB->update_record('task_adhoc', $record);
 555  
 556          if ($task->is_blocking()) {
 557              $task->get_cron_lock()->release();
 558          }
 559          $task->get_lock()->release();
 560      }
 561  
 562      /**
 563       * This function indicates that an adhoc task was completed successfully.
 564       *
 565       * @param \core\task\adhoc_task $task
 566       */
 567      public static function adhoc_task_complete(adhoc_task $task) {
 568          global $DB;
 569  
 570          // Delete the adhoc task record - it is finished.
 571          $DB->delete_records('task_adhoc', array('id' => $task->get_id()));
 572  
 573          // Reschedule and then release the locks.
 574          if ($task->is_blocking()) {
 575              $task->get_cron_lock()->release();
 576          }
 577          $task->get_lock()->release();
 578      }
 579  
 580      /**
 581       * This function indicates that a scheduled task was not completed successfully and should be retried.
 582       *
 583       * @param \core\task\scheduled_task $task
 584       */
 585      public static function scheduled_task_failed(scheduled_task $task) {
 586          global $DB;
 587  
 588          $delay = $task->get_fail_delay();
 589  
 590          // Reschedule task with exponential fall off for failing tasks.
 591          if (empty($delay)) {
 592              $delay = 60;
 593          } else {
 594              $delay *= 2;
 595          }
 596  
 597          // Max of 24 hour delay.
 598          if ($delay > 86400) {
 599              $delay = 86400;
 600          }
 601  
 602          $classname = get_class($task);
 603          if (strpos($classname, '\\') !== 0) {
 604              $classname = '\\' . $classname;
 605          }
 606  
 607          $record = $DB->get_record('task_scheduled', array('classname' => $classname));
 608          $record->nextruntime = time() + $delay;
 609          $record->faildelay = $delay;
 610          $DB->update_record('task_scheduled', $record);
 611  
 612          if ($task->is_blocking()) {
 613              $task->get_cron_lock()->release();
 614          }
 615          $task->get_lock()->release();
 616      }
 617  
 618      /**
 619       * This function indicates that a scheduled task was completed successfully and should be rescheduled.
 620       *
 621       * @param \core\task\scheduled_task $task
 622       */
 623      public static function scheduled_task_complete(scheduled_task $task) {
 624          global $DB;
 625  
 626          $classname = get_class($task);
 627          if (strpos($classname, '\\') !== 0) {
 628              $classname = '\\' . $classname;
 629          }
 630          $record = $DB->get_record('task_scheduled', array('classname' => $classname));
 631          if ($record) {
 632              $record->lastruntime = time();
 633              $record->faildelay = 0;
 634              $record->nextruntime = $task->get_next_scheduled_time();
 635  
 636              $DB->update_record('task_scheduled', $record);
 637          }
 638  
 639          // Reschedule and then release the locks.
 640          if ($task->is_blocking()) {
 641              $task->get_cron_lock()->release();
 642          }
 643          $task->get_lock()->release();
 644      }
 645  
 646      /**
 647       * This function is used to indicate that any long running cron processes should exit at the
 648       * next opportunity and restart. This is because something (e.g. DB changes) has changed and
 649       * the static caches may be stale.
 650       */
 651      public static function clear_static_caches() {
 652          global $DB;
 653          // Do not use get/set config here because the caches cannot be relied on.
 654          $record = $DB->get_record('config', array('name'=>'scheduledtaskreset'));
 655          if ($record) {
 656              $record->value = time();
 657              $DB->update_record('config', $record);
 658          } else {
 659              $record = new \stdClass();
 660              $record->name = 'scheduledtaskreset';
 661              $record->value = time();
 662              $DB->insert_record('config', $record);
 663          }
 664      }
 665  
 666      /**
 667       * Return true if the static caches have been cleared since $starttime.
 668       * @param int $starttime The time this process started.
 669       * @return boolean True if static caches need resetting.
 670       */
 671      public static function static_caches_cleared_since($starttime) {
 672          global $DB;
 673          $record = $DB->get_record('config', array('name'=>'scheduledtaskreset'));
 674          return $record && (intval($record->value) > $starttime);
 675      }
 676  }