application/hub/main/miner/class_BaseHubMiner.php

   1 <?php
   2 /**
   3  * A general hub miner class
   4  *
   5  * @author              Roland Haeder <webmaster@shipsimu.org>
   6  * @version             0.0.0
   7  * @copyright   Copyright (c) 2011 - 2012 Miner Developer Team
   8  * @license             GNU GPL 3.0 or any newer version
   9  * @link                http://www.shipsimu.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 abstract class BaseHubMiner extends BaseHubSystem implements Updateable {
  25         /**
  26          * Version information
  27          */
  28         private $version = 'x.x';
  29
  30         /**
  31          * By default no miner is active
  32          */
  33         private $isActive = FALSE;
  34
  35         /**
  36          * All buffer queue instances (a FIFO)
  37          */
  38         private $bufferInstance = NULL;
  39
  40         /**
  41          * Stacker name for incoming queue
  42          */
  43         const STACKER_NAME_IN_QUEUE = 'in_queue';
  44
  45         /**
  46          * Stacker name for outcoming queue
  47          */
  48         const STACKER_NAME_OUT_QUEUE = 'out_queue';
  49
  50         /**
  51          * Protected constructor
  52          *
  53          * @param       $className      Name of the class
  54          * @return      void
  55          */
  56         protected function __construct ($className) {
  57                 // Call parent constructor
  58                 parent::__construct($className);
  59
  60                 // Init this miner
  61                 $this->initMiner();
  62         }
  63
  64         /**
  65          * Initialize the miner generically
  66          *
  67          * @return      void
  68          */
  69         private function initMiner () {
  70                 // Init the state
  71                 MinerStateFactory::createMinerStateInstanceByName('init');
  72         }
  73
  74         /**
  75          * Getter for version
  76          *
  77          * @return      $version        Version number of this miner
  78          */
  79         protected final function getVersion () {
  80                 return $this->version;
  81         }
  82
  83         /**
  84          * Setter for version
  85          *
  86          * @param       $version        Version number of this miner
  87          * @return      void
  88          */
  89         protected final function setVersion ($version) {
  90                 $this->version = (string) $version;
  91         }
  92
  93         /**
  94          * Checks whether the in-buffer queue is filled by comparing it's current
  95          * amount of entries against a threshold.
  96          *
  97          * @return      $isFilled       Whether the in-buffer is filled
  98          */
  99         protected function isInBufferQueueFilled () {
 100                 // Determine it
 101                 $isFilled = ($this->bufferInstance->getStackCount(self::STACKER_NAME_IN_QUEUE) > $this->getConfigInstance()->getConfigEntry('miner_in_buffer_min_threshold'));
 102
 103                 // And return the result
 104                 return $isFilled;
 105         }
 106
 107         /**
 108          * This method fills the in-buffer with (a) test unit(s) which are mainly
 109          * used for development of the crunching part. They must be enabled in
 110          * configuration, or else your miner runs out of WUs and waits for more
 111          * to show up.
 112          *
 113          * In this method we already know that the in-buffer is going depleted so
 114          * no need to double-check it here.
 115          *
 116          * @return      void
 117          */
 118         abstract protected function fillInBufferQueueWithTestUnits ();
 119
 120         /**
 121          * This method fills the in-buffer with (real) WUs which will be crunched
 122          * and the result be sent back to the key producer instance.
 123          *
 124          * @return      void
 125          */
 126         abstract protected function fillInBufferQueueWithWorkUnits ();
 127
 128         /**
 129          * Enables/disables the miner (just sets a flag)
 130          *
 131          * @param       $version        Version number of this miner
 132          * @return      void
 133          */
 134         public final function enableIsActive ($isActive = TRUE) {
 135                 $this->isActive = (bool) $isActive;
 136         }
 137
 138         /**
 139          * Determines whether the miner is active
 140          *
 141          * @return      $isActive       Whether the miner is active
 142          */
 143         public final function isActive () {
 144                 return $this->isActive;
 145         }
 146
 147         /**
 148          * Initializes all buffer queues (mostly in/out). This method is demanded
 149          * by the MinerHelper interface.
 150          *
 151          * @return      void
 152          */
 153         public function initBufferQueues () {
 154                 /*
 155                  * Initialize both buffer queues, we can use the FIFO class here
 156                  * directly and encapsulate its method calls with protected methods.
 157                  */
 158                 $this->bufferInstance = ObjectFactory::createObjectByConfiguredName('miner_buffer_stacker_class');
 159
 160                 // Initialize common stackers, like in/out
 161                 $this->bufferInstance->initStacks(array(
 162                         self::STACKER_NAME_IN_QUEUE,
 163                         self::STACKER_NAME_OUT_QUEUE
 164                 ));
 165
 166                 // Output debug message
 167                 self::createDebugInstance(__CLASS__)->debugOutput('MINER: All buffers are now initialized.');
 168         }
 169
 170         /**
 171          * This method determines if the in-buffer is going to depleted and if so,
 172          * it fetches more WUs from the network. If no WU can be fetched from the
 173          * network and if enabled, a random test WU is being generated.
 174          *
 175          * This method is demanded from the MinerHelper interface.
 176          *
 177          * @return      void
 178          */
 179         public function doFetchWorkUnits () {
 180                 // Simply check if we have enough WUs left in the in-buffer queue (a FIFO)
 181                 if (!$this->isInBufferQueueFilled()) {
 182                         // The in-buffer queue needs filling, so head out and get some work
 183                         $this->fillInBufferQueueWithWorkUnits();
 184
 185                         // Is the buffer still not filled and are test-packages allowed?
 186                         if ((!$this->isInBufferQueueFilled()) && ($this->getConfigInstance()->getConfigEntry('miner_test_units_enabled') == 'Y')) {
 187                                 // Then fill the in-buffer with (one) test-unit(s)
 188                                 $this->fillInBufferQueueWithTestUnits();
 189                         } // END - if
 190                 } // END - if
 191         }
 192
 193         /**
 194          * Updates a given field with new value
 195          *
 196          * @param       $fieldName              Field to update
 197          * @param       $fieldValue             New value to store
 198          * @return      void
 199          * @throws      DatabaseUpdateSupportException  If this class does not support database updates
 200          * @todo        Try to make this method more generic so we can move it in BaseFrameworkSystem
 201          */
 202         public function updateDatabaseField ($fieldName, $fieldValue) {
 203                 // Unfinished
 204                 $this->partialStub('Unfinished!');
 205                 return;
 206         }
 207
 208         /**
 209          * Changes the state to 'booting' and shall be called after the block
 210          * producer has been initialized.
 211          *
 212          * @return      void
 213          */
 214         public function blockProducerHasInitialized () {
 215                 // Make sure the state is correct ('init')
 216                 $this->getStateInstance()->validateMinerStateIsInit();
 217
 218                 // Change it to 'booting'
 219                 MinerStateFactory::createMinerStateInstanceByName('booting', $this);
 220         }
 221 }
 222
 223 // [EOF]
 224 ?>