8 * An interface for generating database load balancers
11 abstract class LBFactory
{
15 * Disables all access to the load balancer, will cause all database access
16 * to throw a DBAccessError
18 public static function disableBackend() {
19 global $wgLBFactoryConf;
20 self
::$instance = new LBFactory_Fake( $wgLBFactoryConf );
24 * Resets the singleton for use if it's been disabled. Does nothing otherwise
26 public static function enableBackend() {
27 if( self
::$instance instanceof LBFactory_Fake
)
28 self
::$instance = null;
32 * Get an LBFactory instance
34 static function &singleton() {
35 if ( is_null( self
::$instance ) ) {
36 global $wgLBFactoryConf;
37 $class = $wgLBFactoryConf['class'];
38 self
::$instance = new $class( $wgLBFactoryConf );
40 return self
::$instance;
44 * Shut down, close connections and destroy the cached instance.
47 static function destroyInstance() {
48 if ( self
::$instance ) {
49 self
::$instance->shutdown();
50 self
::$instance->forEachLBCallMethod( 'closeAll' );
51 self
::$instance = null;
56 * Construct a factory based on a configuration array (typically from $wgLBFactoryConf)
58 abstract function __construct( $conf );
61 * Create a new load balancer object. The resulting object will be untracked,
62 * not chronology-protected, and the caller is responsible for cleaning it up.
64 * @param $wiki String: wiki ID, or false for the current wiki
65 * @return LoadBalancer
67 abstract function newMainLB( $wiki = false );
70 * Get a cached (tracked) load balancer object.
72 * @param $wiki String: wiki ID, or false for the current wiki
73 * @return LoadBalancer
75 abstract function getMainLB( $wiki = false );
78 * Create a new load balancer for external storage. The resulting object will be
79 * untracked, not chronology-protected, and the caller is responsible for
82 * @param $cluster String: external storage cluster, or false for core
83 * @param $wiki String: wiki ID, or false for the current wiki
85 abstract function newExternalLB( $cluster, $wiki = false );
88 * Get a cached (tracked) load balancer for external storage
90 * @param $cluster String: external storage cluster, or false for core
91 * @param $wiki String: wiki ID, or false for the current wiki
93 abstract function &getExternalLB( $cluster, $wiki = false );
96 * Execute a function for each tracked load balancer
97 * The callback is called with the load balancer as the first parameter,
98 * and $params passed as the subsequent parameters.
100 abstract function forEachLB( $callback, $params = array() );
103 * Prepare all tracked load balancers for shutdown
106 function shutdown() {}
109 * Call a method of each tracked load balancer
111 function forEachLBCallMethod( $methodName, $args = array() ) {
112 $this->forEachLB( array( $this, 'callMethod' ), array( $methodName, $args ) );
116 * Private helper for forEachLBCallMethod
118 function callMethod( $loadBalancer, $methodName, $args ) {
119 call_user_func_array( array( $loadBalancer, $methodName ), $args );
123 * Commit changes on all master connections
125 function commitMasterChanges() {
126 $this->forEachLBCallMethod( 'commitMasterChanges' );
131 * A simple single-master LBFactory that gets its configuration from the b/c globals
133 class LBFactory_Simple
extends LBFactory
{
135 var $extLBs = array();
137 # Chronology protector
140 function __construct( $conf ) {
141 $this->chronProt
= new ChronologyProtector
;
144 function newMainLB( $wiki = false ) {
145 global $wgDBservers, $wgMasterWaitTimeout;
146 if ( $wgDBservers ) {
147 $servers = $wgDBservers;
149 global $wgDBserver, $wgDBuser, $wgDBpassword, $wgDBname, $wgDBtype, $wgDebugDumpSql;
150 $servers = array(array(
151 'host' => $wgDBserver,
153 'password' => $wgDBpassword,
154 'dbname' => $wgDBname,
157 'flags' => ($wgDebugDumpSql ? DBO_DEBUG
: 0) | DBO_DEFAULT
161 return new LoadBalancer( array(
162 'servers' => $servers,
163 'masterWaitTimeout' => $wgMasterWaitTimeout
167 function getMainLB( $wiki = false ) {
168 if ( !isset( $this->mainLB
) ) {
169 $this->mainLB
= $this->newMainLB( $wiki );
170 $this->mainLB
->parentInfo( array( 'id' => 'main' ) );
171 $this->chronProt
->initLB( $this->mainLB
);
173 return $this->mainLB
;
176 function newExternalLB( $cluster, $wiki = false ) {
177 global $wgExternalServers;
178 if ( !isset( $wgExternalServers[$cluster] ) ) {
179 throw new MWException( __METHOD__
.": Unknown cluster \"$cluster\"" );
181 return new LoadBalancer( array(
182 'servers' => $wgExternalServers[$cluster]
186 function &getExternalLB( $cluster, $wiki = false ) {
187 if ( !isset( $this->extLBs
[$cluster] ) ) {
188 $this->extLBs
[$cluster] = $this->newExternalLB( $cluster, $wiki );
189 $this->extLBs
[$cluster]->parentInfo( array( 'id' => "ext-$cluster" ) );
191 return $this->extLBs
[$cluster];
195 * Execute a function for each tracked load balancer
196 * The callback is called with the load balancer as the first parameter,
197 * and $params passed as the subsequent parameters.
199 function forEachLB( $callback, $params = array() ) {
200 if ( isset( $this->mainLB
) ) {
201 call_user_func_array( $callback, array_merge( array( $this->mainLB
), $params ) );
203 foreach ( $this->extLBs
as $lb ) {
204 call_user_func_array( $callback, array_merge( array( $lb ), $params ) );
208 function shutdown() {
209 if ( $this->mainLB
) {
210 $this->chronProt
->shutdownLB( $this->mainLB
);
212 $this->chronProt
->shutdown();
213 $this->commitMasterChanges();
218 * LBFactory class that throws an error on any attempt to use it.
219 * This will typically be done via wfGetDB().
220 * Call LBFactory::disableBackend() to start using this, and
221 * LBFactory::enableBackend() to return to normal behavior
223 class LBFactory_Fake
extends LBFactory
{
224 function __construct( $conf ) {}
226 function newMainLB( $wiki = false) {
227 throw new DBAccessError
;
229 function getMainLB( $wiki = false ) {
230 throw new DBAccessError
;
232 function newExternalLB( $cluster, $wiki = false ) {
233 throw new DBAccessError
;
235 function &getExternalLB( $cluster, $wiki = false ) {
236 throw new DBAccessError
;
238 function forEachLB( $callback, $params = array() ) {}
242 * Exception class for attempted DB access
244 class DBAccessError
extends MWException
{
245 function __construct() {
246 parent
::__construct( "Mediawiki tried to access the database via wfGetDB(). This is not allowed." );
251 * Class for ensuring a consistent ordering of events as seen by the user, despite replication.
252 * Kind of like Hawking's [[Chronology Protection Agency]].
254 class ChronologyProtector
{
256 var $shutdownPos = array();
259 * Initialise a LoadBalancer to give it appropriate chronology protection.
261 * @param $lb LoadBalancer
263 function initLB( $lb ) {
264 if ( $this->startupPos
=== null ) {
265 if ( !empty( $_SESSION[__CLASS__
] ) ) {
266 $this->startupPos
= $_SESSION[__CLASS__
];
269 if ( !$this->startupPos
) {
272 $masterName = $lb->getServerName( 0 );
274 if ( $lb->getServerCount() > 1 && !empty( $this->startupPos
[$masterName] ) ) {
275 $info = $lb->parentInfo();
276 $pos = $this->startupPos
[$masterName];
277 wfDebug( __METHOD__
.": LB " . $info['id'] . " waiting for master pos $pos\n" );
278 $lb->waitFor( $this->startupPos
[$masterName] );
283 * Notify the ChronologyProtector that the LoadBalancer is about to shut
284 * down. Saves replication positions.
286 * @param $lb LoadBalancer
288 function shutdownLB( $lb ) {
289 // Don't start a session, don't bother with non-replicated setups
290 if ( strval( session_id() ) == '' ||
$lb->getServerCount() <= 1 ) {
293 $masterName = $lb->getServerName( 0 );
294 if ( isset( $this->shutdownPos
[$masterName] ) ) {
298 // Only save the position if writes have been done on the connection
299 $db = $lb->getAnyOpenConnection( 0 );
300 $info = $lb->parentInfo();
301 if ( !$db ||
!$db->doneWrites() ) {
302 wfDebug( __METHOD__
.": LB {$info['id']}, no writes done\n" );
305 $pos = $db->getMasterPos();
306 wfDebug( __METHOD__
.": LB {$info['id']} has master pos $pos\n" );
307 $this->shutdownPos
[$masterName] = $pos;
311 * Notify the ChronologyProtector that the LBFactory is done calling shutdownLB() for now.
312 * May commit chronology data to persistent storage.
314 function shutdown() {
315 if ( session_id() != '' && count( $this->shutdownPos
) ) {
316 wfDebug( __METHOD__
.": saving master pos for " .
317 count( $this->shutdownPos
) . " master(s)\n" );
318 $_SESSION[__CLASS__
] = $this->shutdownPos
;