3 * Generator of database load balancing objects.
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.
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.
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
25 * An interface for generating database load balancers
28 abstract class LBFactory
{
36 * Disables all access to the load balancer, will cause all database access
37 * to throw a DBAccessError
39 public static function disableBackend() {
40 global $wgLBFactoryConf;
41 self
::$instance = new LBFactory_Fake( $wgLBFactoryConf );
45 * Get an LBFactory instance
49 static function &singleton() {
50 if ( is_null( self
::$instance ) ) {
51 global $wgLBFactoryConf;
52 $class = $wgLBFactoryConf['class'];
53 self
::$instance = new $class( $wgLBFactoryConf );
55 return self
::$instance;
59 * Shut down, close connections and destroy the cached instance.
61 static function destroyInstance() {
62 if ( self
::$instance ) {
63 self
::$instance->shutdown();
64 self
::$instance->forEachLBCallMethod( 'closeAll' );
65 self
::$instance = null;
70 * Set the instance to be the given object
72 * @param $instance LBFactory
74 static function setInstance( $instance ) {
75 self
::destroyInstance();
76 self
::$instance = $instance;
80 * Construct a factory based on a configuration array (typically from $wgLBFactoryConf)
83 abstract function __construct( $conf );
86 * Create a new load balancer object. The resulting object will be untracked,
87 * not chronology-protected, and the caller is responsible for cleaning it up.
89 * @param $wiki String: wiki ID, or false for the current wiki
90 * @return LoadBalancer
92 abstract function newMainLB( $wiki = false );
95 * Get a cached (tracked) load balancer object.
97 * @param $wiki String: wiki ID, or false for the current wiki
98 * @return LoadBalancer
100 abstract function getMainLB( $wiki = false );
103 * Create a new load balancer for external storage. The resulting object will be
104 * untracked, not chronology-protected, and the caller is responsible for
107 * @param $cluster String: external storage cluster, or false for core
108 * @param $wiki String: wiki ID, or false for the current wiki
110 * @return LoadBalancer
112 abstract function newExternalLB( $cluster, $wiki = false );
115 * Get a cached (tracked) load balancer for external storage
117 * @param $cluster String: external storage cluster, or false for core
118 * @param $wiki String: wiki ID, or false for the current wiki
120 * @return LoadBalancer
122 abstract function &getExternalLB( $cluster, $wiki = false );
125 * Execute a function for each tracked load balancer
126 * The callback is called with the load balancer as the first parameter,
127 * and $params passed as the subsequent parameters.
128 * @param $callback string|array
129 * @param array $params
131 abstract function forEachLB( $callback, $params = array() );
134 * Prepare all tracked load balancers for shutdown
137 function shutdown() {}
140 * Call a method of each tracked load balancer
141 * @param $methodName string
144 function forEachLBCallMethod( $methodName, $args = array() ) {
145 $this->forEachLB( array( $this, 'callMethod' ), array( $methodName, $args ) );
149 * Private helper for forEachLBCallMethod
150 * @param $loadBalancer
151 * @param $methodName string
154 function callMethod( $loadBalancer, $methodName, $args ) {
155 call_user_func_array( array( $loadBalancer, $methodName ), $args );
159 * Commit changes on all master connections
161 function commitMasterChanges() {
162 $this->forEachLBCallMethod( 'commitMasterChanges' );
167 * A simple single-master LBFactory that gets its configuration from the b/c globals
169 class LBFactory_Simple
extends LBFactory
{
175 var $extLBs = array();
177 # Chronology protector
180 function __construct( $conf ) {
181 $this->chronProt
= new ChronologyProtector
;
186 * @return LoadBalancer
188 function newMainLB( $wiki = false ) {
189 global $wgDBservers, $wgMasterWaitTimeout;
190 if ( $wgDBservers ) {
191 $servers = $wgDBservers;
193 global $wgDBserver, $wgDBuser, $wgDBpassword, $wgDBname, $wgDBtype, $wgDebugDumpSql;
194 global $wgDBssl, $wgDBcompress;
196 $flags = ( $wgDebugDumpSql ? DBO_DEBUG
: 0 ) | DBO_DEFAULT
;
200 if ( $wgDBcompress ) {
201 $flags |
= DBO_COMPRESS
;
204 $servers = array(array(
205 'host' => $wgDBserver,
207 'password' => $wgDBpassword,
208 'dbname' => $wgDBname,
215 return new LoadBalancer( array(
216 'servers' => $servers,
217 'masterWaitTimeout' => $wgMasterWaitTimeout
223 * @return LoadBalancer
225 function getMainLB( $wiki = false ) {
226 if ( !isset( $this->mainLB
) ) {
227 $this->mainLB
= $this->newMainLB( $wiki );
228 $this->mainLB
->parentInfo( array( 'id' => 'main' ) );
229 $this->chronProt
->initLB( $this->mainLB
);
231 return $this->mainLB
;
235 * @throws MWException
238 * @return LoadBalancer
240 function newExternalLB( $cluster, $wiki = false ) {
241 global $wgExternalServers;
242 if ( !isset( $wgExternalServers[$cluster] ) ) {
243 throw new MWException( __METHOD__
.": Unknown cluster \"$cluster\"" );
245 return new LoadBalancer( array(
246 'servers' => $wgExternalServers[$cluster]
255 function &getExternalLB( $cluster, $wiki = false ) {
256 if ( !isset( $this->extLBs
[$cluster] ) ) {
257 $this->extLBs
[$cluster] = $this->newExternalLB( $cluster, $wiki );
258 $this->extLBs
[$cluster]->parentInfo( array( 'id' => "ext-$cluster" ) );
260 return $this->extLBs
[$cluster];
264 * Execute a function for each tracked load balancer
265 * The callback is called with the load balancer as the first parameter,
266 * and $params passed as the subsequent parameters.
268 * @param $params array
270 function forEachLB( $callback, $params = array() ) {
271 if ( isset( $this->mainLB
) ) {
272 call_user_func_array( $callback, array_merge( array( $this->mainLB
), $params ) );
274 foreach ( $this->extLBs
as $lb ) {
275 call_user_func_array( $callback, array_merge( array( $lb ), $params ) );
279 function shutdown() {
280 if ( $this->mainLB
) {
281 $this->chronProt
->shutdownLB( $this->mainLB
);
283 $this->chronProt
->shutdown();
284 $this->commitMasterChanges();
289 * LBFactory class that throws an error on any attempt to use it.
290 * This will typically be done via wfGetDB().
291 * Call LBFactory::disableBackend() to start using this, and
292 * LBFactory::enableBackend() to return to normal behavior
294 class LBFactory_Fake
extends LBFactory
{
295 function __construct( $conf ) {}
297 function newMainLB( $wiki = false) {
298 throw new DBAccessError
;
300 function getMainLB( $wiki = false ) {
301 throw new DBAccessError
;
303 function newExternalLB( $cluster, $wiki = false ) {
304 throw new DBAccessError
;
306 function &getExternalLB( $cluster, $wiki = false ) {
307 throw new DBAccessError
;
309 function forEachLB( $callback, $params = array() ) {}
313 * Exception class for attempted DB access
315 class DBAccessError
extends MWException
{
316 function __construct() {
317 parent
::__construct( "Mediawiki tried to access the database via wfGetDB(). This is not allowed." );
322 * Class for ensuring a consistent ordering of events as seen by the user, despite replication.
323 * Kind of like Hawking's [[Chronology Protection Agency]].
325 class ChronologyProtector
{
327 var $shutdownPos = array();
330 * Initialise a LoadBalancer to give it appropriate chronology protection.
332 * @param $lb LoadBalancer
334 function initLB( $lb ) {
335 if ( $this->startupPos
=== null ) {
336 if ( !empty( $_SESSION[__CLASS__
] ) ) {
337 $this->startupPos
= $_SESSION[__CLASS__
];
340 if ( !$this->startupPos
) {
343 $masterName = $lb->getServerName( 0 );
345 if ( $lb->getServerCount() > 1 && !empty( $this->startupPos
[$masterName] ) ) {
346 $info = $lb->parentInfo();
347 $pos = $this->startupPos
[$masterName];
348 wfDebug( __METHOD__
.": LB " . $info['id'] . " waiting for master pos $pos\n" );
349 $lb->waitFor( $this->startupPos
[$masterName] );
354 * Notify the ChronologyProtector that the LoadBalancer is about to shut
355 * down. Saves replication positions.
357 * @param $lb LoadBalancer
359 function shutdownLB( $lb ) {
360 // Don't start a session, don't bother with non-replicated setups
361 if ( strval( session_id() ) == '' ||
$lb->getServerCount() <= 1 ) {
364 $masterName = $lb->getServerName( 0 );
365 if ( isset( $this->shutdownPos
[$masterName] ) ) {
369 // Only save the position if writes have been done on the connection
370 $db = $lb->getAnyOpenConnection( 0 );
371 $info = $lb->parentInfo();
372 if ( !$db ||
!$db->doneWrites() ) {
373 wfDebug( __METHOD__
.": LB {$info['id']}, no writes done\n" );
376 $pos = $db->getMasterPos();
377 wfDebug( __METHOD__
.": LB {$info['id']} has master pos $pos\n" );
378 $this->shutdownPos
[$masterName] = $pos;
382 * Notify the ChronologyProtector that the LBFactory is done calling shutdownLB() for now.
383 * May commit chronology data to persistent storage.
385 function shutdown() {
386 if ( session_id() != '' && count( $this->shutdownPos
) ) {
387 wfDebug( __METHOD__
.": saving master pos for " .
388 count( $this->shutdownPos
) . " master(s)\n" );
389 $_SESSION[__CLASS__
] = $this->shutdownPos
;