includes/db/LBFactory.php

   1 <?php
   2 /**
   3  * Generator of database load balancing objects
   4  *
   5  * @file
   6  * @ingroup Database
   7  */
   8
   9 /**
  10  * An interface for generating database load balancers
  11  * @ingroup Database
  12  */
  13 abstract class LBFactory {
  14
  15         /**
  16          * @var LBFactory
  17          */
  18         static $instance;
  19
  20         /**
  21          * Disables all access to the load balancer, will cause all database access
  22          * to throw a DBAccessError
  23          */
  24         public static function disableBackend() {
  25                 global $wgLBFactoryConf;
  26                 self::$instance = new LBFactory_Fake( $wgLBFactoryConf );
  27         }
  28
  29         /**
  30          * Get an LBFactory instance
  31          *
  32          * @return LBFactory
  33          */
  34         static function &singleton() {
  35                 if ( is_null( self::$instance ) ) {
  36                         global $wgLBFactoryConf;
  37                         $class = $wgLBFactoryConf['class'];
  38                         self::$instance = new $class( $wgLBFactoryConf );
  39                 }
  40                 return self::$instance;
  41         }
  42
  43         /**
  44          * Shut down, close connections and destroy the cached instance.
  45          *
  46          */
  47         static function destroyInstance() {
  48                 if ( self::$instance ) {
  49                         self::$instance->shutdown();
  50                         self::$instance->forEachLBCallMethod( 'closeAll' );
  51                         self::$instance = null;
  52                 }
  53         }
  54
  55         /**
  56          * Set the instance to be the given object
  57          *
  58          * @param $instance LBFactory
  59          */
  60         static function setInstance( $instance ) {
  61                 self::destroyInstance();
  62                 self::$instance = $instance;
  63         }
  64
  65         /**
  66          * Construct a factory based on a configuration array (typically from $wgLBFactoryConf)
  67          */
  68         abstract function __construct( $conf );
  69
  70         /**
  71          * Create a new load balancer object. The resulting object will be untracked,
  72          * not chronology-protected, and the caller is responsible for cleaning it up.
  73          *
  74          * @param $wiki String: wiki ID, or false for the current wiki
  75          * @return LoadBalancer
  76          */
  77         abstract function newMainLB( $wiki = false );
  78
  79         /**
  80          * Get a cached (tracked) load balancer object.
  81          *
  82          * @param $wiki String: wiki ID, or false for the current wiki
  83          * @return LoadBalancer
  84          */
  85         abstract function getMainLB( $wiki = false );
  86
  87         /**
  88          * Create a new load balancer for external storage. The resulting object will be
  89          * untracked, not chronology-protected, and the caller is responsible for
  90          * cleaning it up.
  91          *
  92          * @param $cluster String: external storage cluster, or false for core
  93          * @param $wiki String: wiki ID, or false for the current wiki
  94          *
  95          * @return LoadBalancer
  96          */
  97         abstract function newExternalLB( $cluster, $wiki = false );
  98
  99         /**
 100          * Get a cached (tracked) load balancer for external storage
 101          *
 102          * @param $cluster String: external storage cluster, or false for core
 103          * @param $wiki String: wiki ID, or false for the current wiki
 104          *
 105          * @return LoadBalancer
 106          */
 107         abstract function &getExternalLB( $cluster, $wiki = false );
 108
 109         /**
 110          * Execute a function for each tracked load balancer
 111          * The callback is called with the load balancer as the first parameter,
 112          * and $params passed as the subsequent parameters.
 113          */
 114         abstract function forEachLB( $callback, $params = array() );
 115
 116         /**
 117          * Prepare all tracked load balancers for shutdown
 118          * STUB
 119          */
 120         function shutdown() {}
 121
 122         /**
 123          * Call a method of each tracked load balancer
 124          */
 125         function forEachLBCallMethod( $methodName, $args = array() ) {
 126                 $this->forEachLB( array( $this, 'callMethod' ), array( $methodName, $args ) );
 127         }
 128
 129         /**
 130          * Private helper for forEachLBCallMethod
 131          */
 132         function callMethod( $loadBalancer, $methodName, $args ) {
 133                 call_user_func_array( array( $loadBalancer, $methodName ), $args );
 134         }
 135
 136         /**
 137          * Commit changes on all master connections
 138          */
 139         function commitMasterChanges() {
 140                 $this->forEachLBCallMethod( 'commitMasterChanges' );
 141         }
 142 }
 143
 144 /**
 145  * A simple single-master LBFactory that gets its configuration from the b/c globals
 146  */
 147 class LBFactory_Simple extends LBFactory {
 148
 149         /**
 150          * @var LoadBalancer
 151          */
 152         var $mainLB;
 153         var $extLBs = array();
 154
 155         # Chronology protector
 156         var $chronProt;
 157
 158         function __construct( $conf ) {
 159                 $this->chronProt = new ChronologyProtector;
 160         }
 161
 162         /**
 163          * @param $wiki
 164          * @return LoadBalancer
 165          */
 166         function newMainLB( $wiki = false ) {
 167                 global $wgDBservers, $wgMasterWaitTimeout;
 168                 if ( $wgDBservers ) {
 169                         $servers = $wgDBservers;
 170                 } else {
 171                         global $wgDBserver, $wgDBuser, $wgDBpassword, $wgDBname, $wgDBtype, $wgDebugDumpSql;
 172                         $servers = array(array(
 173                                 'host' => $wgDBserver,
 174                                 'user' => $wgDBuser,
 175                                 'password' => $wgDBpassword,
 176                                 'dbname' => $wgDBname,
 177                                 'type' => $wgDBtype,
 178                                 'load' => 1,
 179                                 'flags' => ($wgDebugDumpSql ? DBO_DEBUG : 0) | DBO_DEFAULT
 180                         ));
 181                 }
 182
 183                 return new LoadBalancer( array(
 184                         'servers' => $servers,
 185                         'masterWaitTimeout' => $wgMasterWaitTimeout
 186                 ));
 187         }
 188
 189         /**
 190          * @param $wiki
 191          * @return LoadBalancer
 192          */
 193         function getMainLB( $wiki = false ) {
 194                 if ( !isset( $this->mainLB ) ) {
 195                         $this->mainLB = $this->newMainLB( $wiki );
 196                         $this->mainLB->parentInfo( array( 'id' => 'main' ) );
 197                         $this->chronProt->initLB( $this->mainLB );
 198                 }
 199                 return $this->mainLB;
 200         }
 201
 202         /**
 203          * @throws MWException
 204          * @param $cluster
 205          * @param $wiki
 206          * @return LoadBalancer
 207          */
 208         function newExternalLB( $cluster, $wiki = false ) {
 209                 global $wgExternalServers;
 210                 if ( !isset( $wgExternalServers[$cluster] ) ) {
 211                         throw new MWException( __METHOD__.": Unknown cluster \"$cluster\"" );
 212                 }
 213                 return new LoadBalancer( array(
 214                         'servers' => $wgExternalServers[$cluster]
 215                 ));
 216         }
 217
 218         /**
 219          * @param $cluster
 220          * @param $wiki
 221          * @return array
 222          */
 223         function &getExternalLB( $cluster, $wiki = false ) {
 224                 if ( !isset( $this->extLBs[$cluster] ) ) {
 225                         $this->extLBs[$cluster] = $this->newExternalLB( $cluster, $wiki );
 226                         $this->extLBs[$cluster]->parentInfo( array( 'id' => "ext-$cluster" ) );
 227                 }
 228                 return $this->extLBs[$cluster];
 229         }
 230
 231         /**
 232          * Execute a function for each tracked load balancer
 233          * The callback is called with the load balancer as the first parameter,
 234          * and $params passed as the subsequent parameters.
 235          */
 236         function forEachLB( $callback, $params = array() ) {
 237                 if ( isset( $this->mainLB ) ) {
 238                         call_user_func_array( $callback, array_merge( array( $this->mainLB ), $params ) );
 239                 }
 240                 foreach ( $this->extLBs as $lb ) {
 241                         call_user_func_array( $callback, array_merge( array( $lb ), $params ) );
 242                 }
 243         }
 244
 245         function shutdown() {
 246                 if ( $this->mainLB ) {
 247                         $this->chronProt->shutdownLB( $this->mainLB );
 248                 }
 249                 $this->chronProt->shutdown();
 250                 $this->commitMasterChanges();
 251         }
 252 }
 253
 254 /**
 255  * LBFactory class that throws an error on any attempt to use it.
 256  * This will typically be done via wfGetDB().
 257  * Call LBFactory::disableBackend() to start using this, and
 258  * LBFactory::enableBackend() to return to normal behavior
 259  */
 260 class LBFactory_Fake extends LBFactory {
 261         function __construct( $conf ) {}
 262
 263         function newMainLB( $wiki = false) {
 264                 throw new DBAccessError;
 265         }
 266         function getMainLB( $wiki = false ) {
 267                 throw new DBAccessError;
 268         }
 269         function newExternalLB( $cluster, $wiki = false ) {
 270                 throw new DBAccessError;
 271         }
 272         function &getExternalLB( $cluster, $wiki = false ) {
 273                 throw new DBAccessError;
 274         }
 275         function forEachLB( $callback, $params = array() ) {}
 276 }
 277
 278 /**
 279  * Exception class for attempted DB access
 280  */
 281 class DBAccessError extends MWException {
 282         function __construct() {
 283                 parent::__construct( "Mediawiki tried to access the database via wfGetDB(). This is not allowed." );
 284         }
 285 }
 286
 287 /**
 288  * Class for ensuring a consistent ordering of events as seen by the user, despite replication.
 289  * Kind of like Hawking's [[Chronology Protection Agency]].
 290  */
 291 class ChronologyProtector {
 292         var $startupPos;
 293         var $shutdownPos = array();
 294
 295         /**
 296          * Initialise a LoadBalancer to give it appropriate chronology protection.
 297          *
 298          * @param $lb LoadBalancer
 299          */
 300         function initLB( $lb ) {
 301                 if ( $this->startupPos === null ) {
 302                         if ( !empty( $_SESSION[__CLASS__] ) ) {
 303                                 $this->startupPos = $_SESSION[__CLASS__];
 304                         }
 305                 }
 306                 if ( !$this->startupPos ) {
 307                         return;
 308                 }
 309                 $masterName = $lb->getServerName( 0 );
 310
 311                 if ( $lb->getServerCount() > 1 && !empty( $this->startupPos[$masterName] ) ) {
 312                         $info = $lb->parentInfo();
 313                         $pos = $this->startupPos[$masterName];
 314                         wfDebug( __METHOD__.": LB " . $info['id'] . " waiting for master pos $pos\n" );
 315                         $lb->waitFor( $this->startupPos[$masterName] );
 316                 }
 317         }
 318
 319         /**
 320          * Notify the ChronologyProtector that the LoadBalancer is about to shut
 321          * down. Saves replication positions.
 322          *
 323          * @param $lb LoadBalancer
 324          */
 325         function shutdownLB( $lb ) {
 326                 // Don't start a session, don't bother with non-replicated setups
 327                 if ( strval( session_id() ) == '' || $lb->getServerCount() <= 1 ) {
 328                         return;
 329                 }
 330                 $masterName = $lb->getServerName( 0 );
 331                 if ( isset( $this->shutdownPos[$masterName] ) ) {
 332                         // Already done
 333                         return;
 334                 }
 335                 // Only save the position if writes have been done on the connection
 336                 $db = $lb->getAnyOpenConnection( 0 );
 337                 $info = $lb->parentInfo();
 338                 if ( !$db || !$db->doneWrites() ) {
 339                         wfDebug( __METHOD__.": LB {$info['id']}, no writes done\n" );
 340                         return;
 341                 }
 342                 $pos = $db->getMasterPos();
 343                 wfDebug( __METHOD__.": LB {$info['id']} has master pos $pos\n" );
 344                 $this->shutdownPos[$masterName] = $pos;
 345         }
 346
 347         /**
 348          * Notify the ChronologyProtector that the LBFactory is done calling shutdownLB() for now.
 349          * May commit chronology data to persistent storage.
 350          */
 351         function shutdown() {
 352                 if ( session_id() != '' && count( $this->shutdownPos ) ) {
 353                         wfDebug( __METHOD__.": saving master pos for " .
 354                                 count( $this->shutdownPos ) . " master(s)\n" );
 355                         $_SESSION[__CLASS__] = $this->shutdownPos;
 356                 }
 357         }
 358 }