backup/util/progress/core_backup_progress.class.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  * Base class for handling progress information during a backup and restore.
  19  *
  20  * Subclasses should generally override the current_progress function which
  21  * summarises all progress information.
  22  *
  23  * @package core_backup
  24  * @copyright 2013 The Open University
  25  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  26  */
  27 abstract class core_backup_progress {
  28     /**
  29      * @var int Constant indicating that the number of progress calls is unknown.
  30      */
  31     const INDETERMINATE = -1;
  32
  33     /**
  34      * @var int The number of seconds that can pass without progress() calls.
  35      */
  36     const TIME_LIMIT_WITHOUT_PROGRESS = 120;
  37
  38     /**
  39      * @var int Time of last progress call.
  40      */
  41     protected $lastprogresstime;
  42
  43     /**
  44      * @var int Number of progress calls (restricted to ~ 1/second).
  45      */
  46     protected $count;
  47
  48     /**
  49      * @var array Array of progress descriptions for each stack level.
  50      */
  51     protected $descriptions = array();
  52
  53     /**
  54      * @var array Array of maximum progress values for each stack level.
  55      */
  56     protected $maxes = array();
  57
  58     /**
  59      * @var array Array of current progress values.
  60      */
  61     protected $currents = array();
  62
  63     /**
  64      * @var int Array of counts within parent progress entry (ignored for first)
  65      */
  66     protected $parentcounts = array();
  67
  68     /**
  69      * Marks the start of an operation that will display progress.
  70      *
  71      * This can be called multiple times for nested progress sections. It must
  72      * be paired with calls to end_progress.
  73      *
  74      * The progress maximum may be INDETERMINATE if the current operation has
  75      * an unknown number of steps. (This is default.)
  76      *
  77      * Calling this function will always result in a new display, so this
  78      * should not be called exceedingly frequently.
  79      *
  80      * When it is complete by calling end_progress, each start_progress section
  81      * automatically adds progress to its parent, as defined by $parentcount.
  82      *
  83      * @param string $description Description to display
  84      * @param int $max Maximum value of progress for this section
  85      * @param int $parentcount How many progress points this section counts for
  86      * @throws coding_exception If max is invalid
  87      */
  88     public function start_progress($description, $max = self::INDETERMINATE,
  89             $parentcount = 1) {
  90         if ($max != self::INDETERMINATE && $max < 0) {
  91             throw new coding_exception(
  92                     'start_progress() max value cannot be negative');
  93         }
  94         if ($parentcount < 1) {
  95             throw new coding_exception(
  96                     'start_progress() parent progress count must be at least 1');
  97         }
  98         if (!empty($this->descriptions)) {
  99             $prevmax = end($this->maxes);
 100             if ($prevmax !== self::INDETERMINATE) {
 101                 $prevcurrent = end($this->currents);
 102                 if ($prevcurrent + $parentcount > $prevmax) {
 103                     throw new coding_exception(
 104                             'start_progress() parent progress would exceed max');
 105                 }
 106             }
 107         } else {
 108             if ($parentcount != 1) {
 109                 throw new coding_exception(
 110                         'start_progress() progress count must be 1 when no parent');
 111             }
 112         }
 113         $this->descriptions[] = $description;
 114         $this->maxes[] = $max;
 115         $this->currents[] = 0;
 116         $this->parentcounts[] = $parentcount;
 117         $this->update_progress();
 118         $lastprogresstime = $this->get_time();
 119     }
 120
 121     /**
 122      * Marks the end of an operation that will display progress.
 123      *
 124      * This must be paired with each start_progress call.
 125      *
 126      * If there is a parent progress section, its progress will be increased
 127      * automatically to reflect the end of the child section.
 128      *
 129      * @throws coding_exception If progress hasn't been started
 130      */
 131     public function end_progress() {
 132         if (!count($this->descriptions)) {
 133             throw new coding_exception('end_progress() without start_progress()');
 134         }
 135         array_pop($this->descriptions);
 136         array_pop($this->maxes);
 137         array_pop($this->currents);
 138         $parentcount = array_pop($this->parentcounts);
 139         if (!empty($this->descriptions)) {
 140             $lastmax = end($this->maxes);
 141             if ($lastmax != self::INDETERMINATE) {
 142                 $lastvalue = end($this->currents);
 143                 $this->currents[key($this->currents)] = $lastvalue + $parentcount;
 144             }
 145         }
 146         $this->update_progress();
 147     }
 148
 149     /**
 150      * Indicates that progress has occurred.
 151      *
 152      * The progress value should indicate the total progress so far, from 0
 153      * to the value supplied for $max (inclusive) in start_progress.
 154      *
 155      * You do not need to call this function for every value. It is OK to skip
 156      * values. It is also OK to call this function as often as desired; it
 157      * doesn't do anything if called more than once per second.
 158      *
 159      * It must be INDETERMINATE if start_progress was called with $max set to
 160      * INDETERMINATE. Otherwise it must not be indeterminate.
 161      *
 162      * @param int $progress Progress so far
 163      * @throws coding_exception If progress value is invalid
 164      */
 165     public function progress($progress = self::INDETERMINATE) {
 166         // Ignore too-frequent progress calls (more than once per second).
 167         $now = $this->get_time();
 168         if ($now === $this->lastprogresstime) {
 169             return;
 170         }
 171
 172         // Check we are inside a progress section.
 173         $max = end($this->maxes);
 174         if ($max === false) {
 175             throw new coding_exception(
 176                     'progress() without start_progress');
 177         }
 178
 179         // Check and apply new progress.
 180         if ($progress === self::INDETERMINATE) {
 181             // Indeterminate progress.
 182             if ($max !== self::INDETERMINATE) {
 183                 throw new coding_exception(
 184                         'progress() INDETERMINATE, expecting value');
 185             }
 186         } else {
 187             // Determinate progress.
 188             $current = end($this->currents);
 189             if ($max === self::INDETERMINATE) {
 190                 throw new coding_exception(
 191                         'progress() with value, expecting INDETERMINATE');
 192             } else if ($progress < 0 || $progress > $max) {
 193                 throw new coding_exception(
 194                         'progress() value out of range');
 195             } else if ($progress < $current) {
 196                 throw new coding_Exception(
 197                         'progress() value may not go backwards');
 198             }
 199             $this->currents[key($this->currents)] = $progress;
 200         }
 201
 202         // Update progress.
 203         $this->count++;
 204         $this->lastprogresstime = $now;
 205         set_time_limit(self::TIME_LIMIT_WITHOUT_PROGRESS);
 206         $this->update_progress();
 207     }
 208
 209     /**
 210      * Gets time (this is provided so that unit tests can override it).
 211      *
 212      * @return int Current system time
 213      */
 214     protected function get_time() {
 215         return time();
 216     }
 217
 218     /**
 219      * Called whenever new progress should be displayed.
 220      */
 221     protected abstract function update_progress();
 222
 223     /**
 224      * @return bool True if currently inside a progress section
 225      */
 226     public function is_in_progress_section() {
 227         return !empty($this->descriptions);
 228     }
 229
 230     /**
 231      * Checks max value of current progress section.
 232      *
 233      * @return int Current max value (may be core_backup_progress::INDETERMINATE)
 234      * @throws coding_exception If not in a progress section
 235      */
 236     public function get_current_max() {
 237         $max = end($this->maxes);
 238         if ($max === false) {
 239             throw new coding_exception('Not inside progress section');
 240         }
 241         return $max;
 242     }
 243
 244     /**
 245      * @return string Current progress section description
 246      */
 247     public function get_current_description() {
 248         $description = end($this->descriptions);
 249         if ($description === false) {
 250             throw new coding_exception('Not inside progress section');
 251         }
 252         return $description;
 253     }
 254
 255     /**
 256      * Obtains current progress in a way suitable for drawing a progress bar.
 257      *
 258      * Progress is returned as a minimum and maximum value. If there is no
 259      * indeterminate progress, these values will be identical. If there is
 260      * intermediate progress, these values can be different. (For example, if
 261      * the top level progress sections is indeterminate, then the values will
 262      * always be 0.0 and 1.0.)
 263      *
 264      * @return array Minimum and maximum possible progress proportions
 265      */
 266     public function get_progress_proportion_range() {
 267         // If there is no progress underway, we must have finished.
 268         if (empty($this->currents)) {
 269             return array(1.0, 1.0);
 270         }
 271         $count = count($this->currents);
 272         $min = 0.0;
 273         $max = 1.0;
 274         for ($i = 0; $i < $count; $i++) {
 275             // Get max value at that section - if it's indeterminate we can tell
 276             // no more.
 277             $sectionmax = $this->maxes[$i];
 278             if ($sectionmax === self::INDETERMINATE) {
 279                 return array($min, $max);
 280             }
 281
 282             // Special case if current value is max (this should only happen
 283             // just before ending a section).
 284             $sectioncurrent = $this->currents[$i];
 285             if ($sectioncurrent === $sectionmax) {
 286                 return array($max, $max);
 287             }
 288
 289             // Using the current value at that section, we know we are somewhere
 290             // between 'current' and the next 'current' value which depends on
 291             // the parentcount of the nested section (if any).
 292             $newmin = ($sectioncurrent / $sectionmax) * ($max - $min) + $min;
 293             $nextcurrent = $sectioncurrent + 1;
 294             if ($i + 1 < $count) {
 295                 $weight = $this->parentcounts[$i + 1];
 296                 $nextcurrent = $sectioncurrent + $weight;
 297             }
 298             $newmax = ($nextcurrent / $sectionmax) * ($max - $min) + $min;
 299             $min = $newmin;
 300             $max = $newmax;
 301         }
 302
 303         // If there was nothing indeterminate, we use the min value as current.
 304         return array($min, $min);
 305     }
 306
 307     /**
 308      * Obtains current indeterminate progress in a way suitable for adding to
 309      * the progress display.
 310      *
 311      * This returns the number of indeterminate calls (at any level) during the
 312      * lifetime of this progress reporter, whether or not there is a current
 313      * indeterminate step. (The number will not be ridiculously high because
 314      * progress calls are limited to one per second.)
 315      *
 316      * @return int Number of indeterminate progress calls
 317      */
 318     public function get_progress_count() {
 319         return $this->count;
 320     }
 321 }