application/hub/main/handler/tasks/class_TaskHandler.php

   1 <?php
   2 /**
   3  * A Task handler
   4  *
   5  * @author              Roland Haeder <webmaster@ship-simu.org>
   6  * @version             0.0.0
   7  * @copyright   Copyright (c) 2007, 2008 Roland Haeder, 2009, 2010 Hub Developer Team
   8  * @license             GNU GPL 3.0 or any newer version
   9  * @link                http://www.ship-simu.org
  10  *
  11  * This program is free software: you can redistribute it and/or modify
  12  * it under the terms of the GNU General Public License as published by
  13  * the Free Software Foundation, either version 3 of the License, or
  14  * (at your option) any later version.
  15  *
  16  * This program is distributed in the hope that it will be useful,
  17  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  18  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  19  * GNU General Public License for more details.
  20  *
  21  * You should have received a copy of the GNU General Public License
  22  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  23  */
  24 class TaskHandler extends BaseHandler implements Registerable, HandleableTask {
  25         // Exception constants
  26         const EXCEPTION_TASK_IS_INVALID = 0xb00;
  27
  28         /**
  29          * A task list instance
  30          */
  31         private $listInstance = null;
  32
  33         /**
  34          * Instance for iterator
  35          */
  36         private $iteratorInstance = null;
  37
  38         /**
  39          * Visitor instance for all tasks while they are active
  40          */
  41         private $visitorInstance = null;
  42
  43         /**
  44          * Protected constructor
  45          *
  46          * @return      void
  47          */
  48         protected function __construct () {
  49                 // Call parent constructor
  50                 parent::__construct(__CLASS__);
  51
  52                 // Init the task list
  53                 $this->listInstance = ObjectFactory::createObjectByConfiguredName('task_list_class');
  54
  55                 // Get default instance
  56                 $this->iteratorInstance = $this->listInstance->getIterator();
  57
  58                 // Init visitor instance for faster loop
  59                 $this->visitorInstance = ObjectFactory::createObjectByConfiguredName('active_task_visitor_class');
  60         }
  61
  62         /**
  63          * Creates an instance of this class
  64          *
  65          * @return      $handlerInstance        An instance of a HandleableTask class
  66          */
  67         public final static function createTaskHandler () {
  68                 // Get new instance
  69                 $handlerInstance = new TaskHandler();
  70
  71                 // Output debug message
  72                 $handlerInstance->debugOutput('TASK-HANDLER: Task handler initialized.');
  73
  74                 // Return the prepared instance
  75                 return $handlerInstance;
  76         }
  77
  78         /**
  79          * Tries to execute the given task. If as task should not be started (yet)
  80          * or the interval time (see task_interval_delay) is not yet reached the
  81          * task is quietly skipped.
  82          *
  83          * @return      void
  84          * @throws      InvalidTaskException    If the current task is invalid
  85          */
  86         private function executeCurrentTask () {
  87                 // Update no task by default
  88                 $updateTask = false;
  89
  90                 // Is the current task valid?
  91                 if (!$this->iteratorInstance->valid()) {
  92                         // Not valid!
  93                         throw new InvalidTaskException($this, self::EXCEPTION_TASK_IS_INVALID);
  94                 } // END - if
  95
  96                 // Get current task
  97                 $currentTask = $this->iteratorInstance->current();
  98
  99                 // Is the task not yet started?
 100                 if ($currentTask['task_started'] === false) {
 101                         // Determine difference between current time and registration
 102                         $diff = ($this->getMilliTime() - $currentTask['task_registered']) * 1000;
 103
 104                         // Should we start now?
 105                         if ($diff < $currentTask['task_startup_delay']) {
 106                                 // Skip this silently
 107                                 return false;
 108                         } // END - if
 109
 110                         // Launch the task and mark it as updated
 111                         $currentTask['task_started'] = true;
 112                         $updateTask = true;
 113
 114                         // Debug message
 115                         $this->debugOutput('TASK-HANDLER: Task ' . $currentTask['id'] . ' started with startup_delay=' . $currentTask['task_startup_delay'] . 'ms');
 116                 } // END - if
 117
 118                 // Get time difference from interval delay
 119                 $diff = ($this->getMilliTime() - $currentTask['task_last_activity']) * 1000;
 120
 121                 // Is the interval delay reached?
 122                 if ((($diff < $currentTask['task_interval_delay']) && ($currentTask['task_max_runs'] == 0)) || (($currentTask['task_total_runs'] == $currentTask['task_max_runs']) && ($currentTask['task_max_runs'] > 0))) {
 123                         // Should we update the task from startup?
 124                         if ($updateTask === true) {
 125                                 // Update the task before leaving
 126                                 $this->updateTask($currentTask);
 127                         } // END - if
 128
 129                         // Skip this silently
 130                         return false;
 131                 } // END - if
 132
 133                 // Set last activity
 134                 $currentTask['task_last_activity'] = $this->getMilliTime();
 135
 136                 // Count this run
 137                 $currentTask['task_total_runs']++;
 138
 139                 // Update the task
 140                 $this->updateTask($currentTask);
 141
 142                 // And visit/run it
 143                 // @TODO Messurement can be added around this call
 144                 $currentTask['task_instance']->accept($this->visitorInstance);
 145         }
 146
 147         /**
 148          * Updates given task by updating the underlaying list
 149          *
 150          * @param       $taskEntry      An array with a task
 151          * @return      void
 152          */
 153         private function updateTask (array $taskEntry) {
 154                 // Get the key from current iteration
 155                 $key = $this->iteratorInstance->key();
 156
 157                 // Get the hash from key
 158                 $hash = $this->listInstance->getHash($key);
 159
 160                 // Update the entry
 161                 $this->listInstance->updateCurrentEntryByHash($hash, $taskEntry);
 162         }
 163
 164         /**
 165          * Unregisters the given task
 166          *
 167          * @param       $taskName       Name of the task
 168          * @return      void
 169          */
 170          private function unregisterTask ($taskName) {
 171                 // Remove the entry
 172                 $this->listInstance->removeEntry('tasks', $taskName);
 173          }
 174
 175         /**
 176          * Registers a task with a task handler.
 177          *
 178          * @param       $taskName               A task name to register the task on
 179          * @param       $taskInstance   The instance we should register as a task
 180          * @return      void
 181          */
 182         public function registerTask ($taskName, Visitable $taskInstance) {
 183                 // Create the entry
 184                 $taskEntry = array(
 185                         // Identifier for the generateHash() method
 186                         'id'                  => $taskName,
 187                         // Wether the task is started
 188                         'task_started'        => false,
 189                         // Wether the task is paused (not yet implemented)
 190                         'task_paused'         => false,
 191                         // Wether the task can be paused (not yet implemented)
 192                         'task_pauseable'      => true,
 193                         // Timestamp of registration
 194                         'task_registered'     => $this->getMilliTime(),
 195                         // Last activity timestamp
 196                         'task_last_activity'  => 0,
 197                         // Total runs of this task
 198                         'task_total_runs'     => 0,
 199                         // Task instance itself
 200                         'task_instance'       => $taskInstance,
 201                         // Startup delay in milliseconds
 202                         'task_startup_delay'  => $this->getConfigInstance()->getConfigEntry('task_' . $taskName . '_startup_delay'),
 203                         // Interval time (delay) in milliseconds before this task is executed again
 204                         'task_interval_delay' => $this->getConfigInstance()->getConfigEntry('task_' . $taskName . '_interval_delay'),
 205                         // How often should this task run?
 206                         'task_max_runs'       => $this->getConfigInstance()->getConfigEntry('task_' . $taskName . '_max_runs'),
 207                 );
 208
 209                 // Add the entry
 210                 $this->listInstance->addEntry('tasks', $taskEntry);
 211
 212                 // Debug message
 213                 $this->debugOutput('TASK-HANDLER: Task ' . $taskName .
 214                         ' (taskInstance=' . $taskInstance->__toString() . ')' .
 215                         ', startupDelay=' . $taskEntry['task_startup_delay'] . 'ms' .
 216                         ', intervalDelay=' . $taskEntry['task_interval_delay'] . 'ms' .
 217                         ', maxRuns=' . $taskEntry['task_max_runs'] . ' times registered.'
 218                 );
 219         }
 220
 221         /**
 222          * Checks wether tasks are left including idle task
 223          *
 224          * @return      $tasksLeft      Wether there are tasks left to handle
 225          */
 226         public function hasTasksLeft () {
 227                 // Do we have tasks there?
 228                 $tasksLeft = (($this->listInstance instanceof Listable) && ($this->listInstance->count() > 0));
 229
 230                 // Return result
 231                 return $tasksLeft;
 232         }
 233
 234         /**
 235          * Handles all tasks by checking if they should startup or if it is their
 236          * turn to run. You should use this method in a while() loop in conjuntion
 237          * with hasTasksLeft() so you can e.g. shutdown by adding a ShutdownTask
 238          * which will attempt to remove all tasks from the task handler.
 239          *
 240          * @return      void
 241          */
 242         public function handleTasks () {
 243                 // Should we rewind?
 244                 if (!$this->iteratorInstance->valid()) {
 245                         // Rewind to the beginning for next loop
 246                         $this->iteratorInstance->rewind();
 247                 } // END - if
 248
 249                 // Try to execute the task
 250                 $this->executeCurrentTask();
 251
 252                 // Go to next entry
 253                 $this->iteratorInstance->next();
 254         }
 255
 256         /**
 257          * Shuts down all tasks and the task handler itself. This method should be
 258          * called from a corresponding filter class.
 259          *
 260          * @return      void
 261          */
 262         public function doShutdown () {
 263                 // Should we rewind?
 264                 if (!$this->iteratorInstance->valid()) {
 265                         // Rewind to the beginning for next loop
 266                         $this->iteratorInstance->rewind();
 267                 } // END - if
 268
 269                 // Debug message
 270                 $this->debugOutput('TASK-HANDLER: Shutting down all ' . $this->listInstance->count() . ' tasks...');
 271
 272                 // Remember all tasks that has been shutdown for removal
 273                 $tasks = array();
 274
 275                 // Shutdown all tasks in once go
 276                 while ($this->iteratorInstance->valid()) {
 277                         // Get current entry
 278                         $current = $this->iteratorInstance->current();
 279
 280                         // Output debug message
 281                         $this->debugOutput('TASK-HANDLER: Shutting down task ' . $current['id'] . ' (taskInstance=' . $current['task_instance']->__toString() . ') ...');
 282
 283                         // Shutdown the task
 284                         $current['task_instance']->doShutdown();
 285
 286                         // Remember this task
 287                         $tasks[] = $current;
 288
 289                         // Advance to next one
 290                         $this->iteratorInstance->next();
 291                 } // END - while
 292
 293
 294                 // Debug message
 295                 $this->debugOutput('TASK-HANDLER: Shutdown of all tasks completed.');
 296
 297                 // Remove all tasks
 298                 foreach ($tasks as $entry) {
 299                         $this->unregisterTask($entry);
 300                 } // END - foreach
 301         }
 302 }
 303
 304 // [EOF]
 305 ?>