3 * Generator of database load balancing objects
10 * An interface for generating database load balancers
13 abstract class LBFactory
{
17 * Disables all access to the load balancer, will cause all database access
18 * to throw a DBAccessError
20 public static function disableBackend() {
21 global $wgLBFactoryConf;
22 self
::$instance = new LBFactory_Fake( $wgLBFactoryConf );
26 * Resets the singleton for use if it's been disabled. Does nothing otherwise
28 public static function enableBackend() {
29 if( self
::$instance instanceof LBFactory_Fake
)
30 self
::$instance = null;
34 * Get an LBFactory instance
36 static function &singleton() {
37 if ( is_null( self
::$instance ) ) {
38 global $wgLBFactoryConf;
39 $class = $wgLBFactoryConf['class'];
40 self
::$instance = new $class( $wgLBFactoryConf );
42 return self
::$instance;
46 * Shut down, close connections and destroy the cached instance.
49 static function destroyInstance() {
50 if ( self
::$instance ) {
51 self
::$instance->shutdown();
52 self
::$instance->forEachLBCallMethod( 'closeAll' );
53 self
::$instance = null;
58 * Set the instance to be the given object
60 static function setInstance( $instance ) {
61 self
::destroyInstance();
62 self
::$instance = $instance;
66 * Construct a factory based on a configuration array (typically from $wgLBFactoryConf)
68 abstract function __construct( $conf );
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.
74 * @param $wiki String: wiki ID, or false for the current wiki
75 * @return LoadBalancer
77 abstract function newMainLB( $wiki = false );
80 * Get a cached (tracked) load balancer object.
82 * @param $wiki String: wiki ID, or false for the current wiki
83 * @return LoadBalancer
85 abstract function getMainLB( $wiki = false );
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
92 * @param $cluster String: external storage cluster, or false for core
93 * @param $wiki String: wiki ID, or false for the current wiki
95 abstract function newExternalLB( $cluster, $wiki = false );
98 * Get a cached (tracked) load balancer for external storage
100 * @param $cluster String: external storage cluster, or false for core
101 * @param $wiki String: wiki ID, or false for the current wiki
103 abstract function &getExternalLB( $cluster, $wiki = false );
106 * Execute a function for each tracked load balancer
107 * The callback is called with the load balancer as the first parameter,
108 * and $params passed as the subsequent parameters.
110 abstract function forEachLB( $callback, $params = array() );
113 * Prepare all tracked load balancers for shutdown
116 function shutdown() {}
119 * Call a method of each tracked load balancer
121 function forEachLBCallMethod( $methodName, $args = array() ) {
122 $this->forEachLB( array( $this, 'callMethod' ), array( $methodName, $args ) );
126 * Private helper for forEachLBCallMethod
128 function callMethod( $loadBalancer, $methodName, $args ) {
129 call_user_func_array( array( $loadBalancer, $methodName ), $args );
133 * Commit changes on all master connections
135 function commitMasterChanges() {
136 $this->forEachLBCallMethod( 'commitMasterChanges' );
141 * A simple single-master LBFactory that gets its configuration from the b/c globals
143 class LBFactory_Simple
extends LBFactory
{
145 var $extLBs = array();
147 # Chronology protector
150 function __construct( $conf ) {
151 $this->chronProt
= new ChronologyProtector
;
154 function newMainLB( $wiki = false ) {
155 global $wgDBservers, $wgMasterWaitTimeout;
156 if ( $wgDBservers ) {
157 $servers = $wgDBservers;
159 global $wgDBserver, $wgDBuser, $wgDBpassword, $wgDBname, $wgDBtype, $wgDebugDumpSql;
160 $servers = array(array(
161 'host' => $wgDBserver,
163 'password' => $wgDBpassword,
164 'dbname' => $wgDBname,
167 'flags' => ($wgDebugDumpSql ? DBO_DEBUG
: 0) | DBO_DEFAULT
171 return new LoadBalancer( array(
172 'servers' => $servers,
173 'masterWaitTimeout' => $wgMasterWaitTimeout
177 function getMainLB( $wiki = false ) {
178 if ( !isset( $this->mainLB
) ) {
179 $this->mainLB
= $this->newMainLB( $wiki );
180 $this->mainLB
->parentInfo( array( 'id' => 'main' ) );
181 $this->chronProt
->initLB( $this->mainLB
);
183 return $this->mainLB
;
186 function newExternalLB( $cluster, $wiki = false ) {
187 global $wgExternalServers;
188 if ( !isset( $wgExternalServers[$cluster] ) ) {
189 throw new MWException( __METHOD__
.": Unknown cluster \"$cluster\"" );
191 return new LoadBalancer( array(
192 'servers' => $wgExternalServers[$cluster]
196 function &getExternalLB( $cluster, $wiki = false ) {
197 if ( !isset( $this->extLBs
[$cluster] ) ) {
198 $this->extLBs
[$cluster] = $this->newExternalLB( $cluster, $wiki );
199 $this->extLBs
[$cluster]->parentInfo( array( 'id' => "ext-$cluster" ) );
201 return $this->extLBs
[$cluster];
205 * Execute a function for each tracked load balancer
206 * The callback is called with the load balancer as the first parameter,
207 * and $params passed as the subsequent parameters.
209 function forEachLB( $callback, $params = array() ) {
210 if ( isset( $this->mainLB
) ) {
211 call_user_func_array( $callback, array_merge( array( $this->mainLB
), $params ) );
213 foreach ( $this->extLBs
as $lb ) {
214 call_user_func_array( $callback, array_merge( array( $lb ), $params ) );
218 function shutdown() {
219 if ( $this->mainLB
) {
220 $this->chronProt
->shutdownLB( $this->mainLB
);
222 $this->chronProt
->shutdown();
223 $this->commitMasterChanges();
228 * LBFactory class that throws an error on any attempt to use it.
229 * This will typically be done via wfGetDB().
230 * Call LBFactory::disableBackend() to start using this, and
231 * LBFactory::enableBackend() to return to normal behavior
233 class LBFactory_Fake
extends LBFactory
{
234 function __construct( $conf ) {}
236 function newMainLB( $wiki = false) {
237 throw new DBAccessError
;
239 function getMainLB( $wiki = false ) {
240 throw new DBAccessError
;
242 function newExternalLB( $cluster, $wiki = false ) {
243 throw new DBAccessError
;
245 function &getExternalLB( $cluster, $wiki = false ) {
246 throw new DBAccessError
;
248 function forEachLB( $callback, $params = array() ) {}
252 * Exception class for attempted DB access
254 class DBAccessError
extends MWException
{
255 function __construct() {
256 parent
::__construct( "Mediawiki tried to access the database via wfGetDB(). This is not allowed." );
261 * Class for ensuring a consistent ordering of events as seen by the user, despite replication.
262 * Kind of like Hawking's [[Chronology Protection Agency]].
264 class ChronologyProtector
{
266 var $shutdownPos = array();
269 * Initialise a LoadBalancer to give it appropriate chronology protection.
271 * @param $lb LoadBalancer
273 function initLB( $lb ) {
274 if ( $this->startupPos
=== null ) {
275 if ( !empty( $_SESSION[__CLASS__
] ) ) {
276 $this->startupPos
= $_SESSION[__CLASS__
];
279 if ( !$this->startupPos
) {
282 $masterName = $lb->getServerName( 0 );
284 if ( $lb->getServerCount() > 1 && !empty( $this->startupPos
[$masterName] ) ) {
285 $info = $lb->parentInfo();
286 $pos = $this->startupPos
[$masterName];
287 wfDebug( __METHOD__
.": LB " . $info['id'] . " waiting for master pos $pos\n" );
288 $lb->waitFor( $this->startupPos
[$masterName] );
293 * Notify the ChronologyProtector that the LoadBalancer is about to shut
294 * down. Saves replication positions.
296 * @param $lb LoadBalancer
298 function shutdownLB( $lb ) {
299 // Don't start a session, don't bother with non-replicated setups
300 if ( strval( session_id() ) == '' ||
$lb->getServerCount() <= 1 ) {
303 $masterName = $lb->getServerName( 0 );
304 if ( isset( $this->shutdownPos
[$masterName] ) ) {
308 // Only save the position if writes have been done on the connection
309 $db = $lb->getAnyOpenConnection( 0 );
310 $info = $lb->parentInfo();
311 if ( !$db ||
!$db->doneWrites() ) {
312 wfDebug( __METHOD__
.": LB {$info['id']}, no writes done\n" );
315 $pos = $db->getMasterPos();
316 wfDebug( __METHOD__
.": LB {$info['id']} has master pos $pos\n" );
317 $this->shutdownPos
[$masterName] = $pos;
321 * Notify the ChronologyProtector that the LBFactory is done calling shutdownLB() for now.
322 * May commit chronology data to persistent storage.
324 function shutdown() {
325 if ( session_id() != '' && count( $this->shutdownPos
) ) {
326 wfDebug( __METHOD__
.": saving master pos for " .
327 count( $this->shutdownPos
) . " master(s)\n" );
328 $_SESSION[__CLASS__
] = $this->shutdownPos
;