includes/db/loadbalancer/LBFactory.php

   1 <?php
   2 /**
   3  * Generator of database load balancing objects.
   4  *
   5  * This program is free software; you can redistribute it and/or modify
   6  * it under the terms of the GNU General Public License as published by
   7  * the Free Software Foundation; either version 2 of the License, or
   8  * (at your option) any later version.
   9  *
  10  * This program is distributed in the hope that it will be useful,
  11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  13  * GNU General Public License for more details.
  14  *
  15  * You should have received a copy of the GNU General Public License along
  16  * with this program; if not, write to the Free Software Foundation, Inc.,
  17  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  18  * http://www.gnu.org/copyleft/gpl.html
  19  *
  20  * @file
  21  * @ingroup Database
  22  */
  23
  24 /**
  25  * An interface for generating database load balancers
  26  * @ingroup Database
  27  */
  28 abstract class LBFactory {
  29         /** @var LBFactory */
  30         private static $instance;
  31
  32         /** @var string|bool Reason all LBs are read-only or false if not */
  33         protected $readOnlyReason = false;
  34
  35         /**
  36          * Construct a factory based on a configuration array (typically from $wgLBFactoryConf)
  37          * @param array $conf
  38          */
  39         public function __construct( array $conf ) {
  40                 if ( isset( $conf['readOnlyReason'] ) && is_string( $conf['readOnlyReason'] ) ) {
  41                         $this->readOnlyReason = $conf['readOnlyReason'];
  42                 }
  43         }
  44
  45         /**
  46          * Disables all access to the load balancer, will cause all database access
  47          * to throw a DBAccessError
  48          */
  49         public static function disableBackend() {
  50                 global $wgLBFactoryConf;
  51                 self::$instance = new LBFactoryFake( $wgLBFactoryConf );
  52         }
  53
  54         /**
  55          * Get an LBFactory instance
  56          *
  57          * @return LBFactory
  58          */
  59         public static function singleton() {
  60                 global $wgLBFactoryConf;
  61
  62                 if ( is_null( self::$instance ) ) {
  63                         $class = self::getLBFactoryClass( $wgLBFactoryConf );
  64                         $config = $wgLBFactoryConf;
  65                         if ( !isset( $config['readOnlyReason'] ) ) {
  66                                 $config['readOnlyReason'] = wfConfiguredReadOnlyReason();
  67                         }
  68                         self::$instance = new $class( $config );
  69                 }
  70
  71                 return self::$instance;
  72         }
  73
  74         /**
  75          * Returns the LBFactory class to use and the load balancer configuration.
  76          *
  77          * @param array $config (e.g. $wgLBFactoryConf)
  78          * @return string Class name
  79          */
  80         public static function getLBFactoryClass( array $config ) {
  81                 // For configuration backward compatibility after removing
  82                 // underscores from class names in MediaWiki 1.23.
  83                 $bcClasses = array(
  84                         'LBFactory_Simple' => 'LBFactorySimple',
  85                         'LBFactory_Single' => 'LBFactorySingle',
  86                         'LBFactory_Multi' => 'LBFactoryMulti',
  87                         'LBFactory_Fake' => 'LBFactoryFake',
  88                 );
  89
  90                 $class = $config['class'];
  91
  92                 if ( isset( $bcClasses[$class] ) ) {
  93                         $class = $bcClasses[$class];
  94                         wfDeprecated(
  95                                 '$wgLBFactoryConf must be updated. See RELEASE-NOTES for details',
  96                                 '1.23'
  97                         );
  98                 }
  99
 100                 return $class;
 101         }
 102
 103         /**
 104          * Shut down, close connections and destroy the cached instance.
 105          */
 106         public static function destroyInstance() {
 107                 if ( self::$instance ) {
 108                         self::$instance->shutdown();
 109                         self::$instance->forEachLBCallMethod( 'closeAll' );
 110                         self::$instance = null;
 111                 }
 112         }
 113
 114         /**
 115          * Set the instance to be the given object
 116          *
 117          * @param LBFactory $instance
 118          */
 119         public static function setInstance( $instance ) {
 120                 self::destroyInstance();
 121                 self::$instance = $instance;
 122         }
 123
 124         /**
 125          * Create a new load balancer object. The resulting object will be untracked,
 126          * not chronology-protected, and the caller is responsible for cleaning it up.
 127          *
 128          * @param bool|string $wiki Wiki ID, or false for the current wiki
 129          * @return LoadBalancer
 130          */
 131         abstract public function newMainLB( $wiki = false );
 132
 133         /**
 134          * Get a cached (tracked) load balancer object.
 135          *
 136          * @param bool|string $wiki Wiki ID, or false for the current wiki
 137          * @return LoadBalancer
 138          */
 139         abstract public function getMainLB( $wiki = false );
 140
 141         /**
 142          * Create a new load balancer for external storage. The resulting object will be
 143          * untracked, not chronology-protected, and the caller is responsible for
 144          * cleaning it up.
 145          *
 146          * @param string $cluster External storage cluster, or false for core
 147          * @param bool|string $wiki Wiki ID, or false for the current wiki
 148          * @return LoadBalancer
 149          */
 150         abstract protected function newExternalLB( $cluster, $wiki = false );
 151
 152         /**
 153          * Get a cached (tracked) load balancer for external storage
 154          *
 155          * @param string $cluster External storage cluster, or false for core
 156          * @param bool|string $wiki Wiki ID, or false for the current wiki
 157          * @return LoadBalancer
 158          */
 159         abstract public function &getExternalLB( $cluster, $wiki = false );
 160
 161         /**
 162          * Execute a function for each tracked load balancer
 163          * The callback is called with the load balancer as the first parameter,
 164          * and $params passed as the subsequent parameters.
 165          *
 166          * @param callable $callback
 167          * @param array $params
 168          */
 169         abstract public function forEachLB( $callback, array $params = array() );
 170
 171         /**
 172          * Prepare all tracked load balancers for shutdown
 173          * STUB
 174          */
 175         public function shutdown() {
 176         }
 177
 178         /**
 179          * Call a method of each tracked load balancer
 180          *
 181          * @param string $methodName
 182          * @param array $args
 183          */
 184         private function forEachLBCallMethod( $methodName, array $args = array() ) {
 185                 $this->forEachLB( function ( LoadBalancer $loadBalancer, $methodName, array $args ) {
 186                         call_user_func_array( array( $loadBalancer, $methodName ), $args );
 187                 }, array( $methodName, $args ) );
 188         }
 189
 190         /**
 191          * Commit on all connections. Done for two reasons:
 192          * 1. To commit changes to the masters.
 193          * 2. To release the snapshot on all connections, master and slave.
 194          */
 195         public function commitAll() {
 196                 $this->forEachLBCallMethod( 'commitAll' );
 197         }
 198
 199         /**
 200          * Commit changes on all master connections
 201          */
 202         public function commitMasterChanges() {
 203                 $this->forEachLBCallMethod( 'commitMasterChanges' );
 204         }
 205
 206         /**
 207          * Rollback changes on all master connections
 208          * @since 1.23
 209          */
 210         public function rollbackMasterChanges() {
 211                 $this->forEachLBCallMethod( 'rollbackMasterChanges' );
 212         }
 213
 214         /**
 215          * Determine if any master connection has pending changes
 216          * @return bool
 217          * @since 1.23
 218          */
 219         public function hasMasterChanges() {
 220                 $ret = false;
 221                 $this->forEachLB( function ( LoadBalancer $lb ) use ( &$ret ) {
 222                         $ret = $ret || $lb->hasMasterChanges();
 223                 } );
 224
 225                 return $ret;
 226         }
 227
 228         /**
 229          * Detemine if any lagged slave connection was used
 230          * @since 1.27
 231          * @return bool
 232          */
 233         public function laggedSlaveUsed() {
 234                 $ret = false;
 235                 $this->forEachLB( function ( LoadBalancer $lb ) use ( &$ret ) {
 236                         $ret = $ret || $lb->laggedSlaveUsed();
 237                 } );
 238
 239                 return $ret;
 240         }
 241
 242         /**
 243          * Determine if any master connection has pending/written changes from this request
 244          * @return bool
 245          * @since 1.27
 246          */
 247         public function hasOrMadeRecentMasterChanges() {
 248                 $ret = false;
 249                 $this->forEachLB( function ( LoadBalancer $lb ) use ( &$ret ) {
 250                         $ret = $ret || $lb->hasOrMadeRecentMasterChanges();
 251                 } );
 252                 return $ret;
 253         }
 254 }
 255
 256 /**
 257  * Exception class for attempted DB access
 258  */
 259 class DBAccessError extends MWException {
 260         public function __construct() {
 261                 parent::__construct( "Mediawiki tried to access the database via wfGetDB(). " .
 262                         "This is not allowed." );
 263         }
 264 }