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
{
35 * Disables all access to the load balancer, will cause all database access
36 * to throw a DBAccessError
38 public static function disableBackend() {
39 global $wgLBFactoryConf;
40 self
::$instance = new LBFactory_Fake( $wgLBFactoryConf );
44 * Get an LBFactory instance
48 static function &singleton() {
49 if ( is_null( self
::$instance ) ) {
50 global $wgLBFactoryConf;
51 $class = $wgLBFactoryConf['class'];
52 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 string $wiki 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 string $wiki 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 string $cluster external storage cluster, or false for core
108 * @param string $wiki 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 string $cluster external storage cluster, or false for core
118 * @param string $wiki 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() {
141 * Call a method of each tracked load balancer
142 * @param $methodName string
145 function forEachLBCallMethod( $methodName, $args = array() ) {
146 $this->forEachLB( array( $this, 'callMethod' ), array( $methodName, $args ) );
150 * Private helper for forEachLBCallMethod
151 * @param $loadBalancer
152 * @param $methodName string
155 function callMethod( $loadBalancer, $methodName, $args ) {
156 call_user_func_array( array( $loadBalancer, $methodName ), $args );
160 * Commit changes on all master connections
162 function commitMasterChanges() {
163 $this->forEachLBCallMethod( 'commitMasterChanges' );
168 * A simple single-master LBFactory that gets its configuration from the b/c globals
170 class LBFactory_Simple
extends LBFactory
{
176 var $extLBs = array();
178 # Chronology protector
181 function __construct( $conf ) {
182 $this->chronProt
= new ChronologyProtector
;
187 * @return LoadBalancer
189 function newMainLB( $wiki = false ) {
190 global $wgDBservers, $wgMasterWaitTimeout;
191 if ( $wgDBservers ) {
192 $servers = $wgDBservers;
194 global $wgDBserver, $wgDBuser, $wgDBpassword, $wgDBname, $wgDBtype, $wgDebugDumpSql;
195 global $wgDBssl, $wgDBcompress;
197 $flags = ( $wgDebugDumpSql ? DBO_DEBUG
: 0 ) | DBO_DEFAULT
;
201 if ( $wgDBcompress ) {
202 $flags |
= DBO_COMPRESS
;
205 $servers = array( array(
206 'host' => $wgDBserver,
208 'password' => $wgDBpassword,
209 'dbname' => $wgDBname,
216 return new LoadBalancer( array(
217 'servers' => $servers,
218 'masterWaitTimeout' => $wgMasterWaitTimeout
224 * @return LoadBalancer
226 function getMainLB( $wiki = false ) {
227 if ( !isset( $this->mainLB
) ) {
228 $this->mainLB
= $this->newMainLB( $wiki );
229 $this->mainLB
->parentInfo( array( 'id' => 'main' ) );
230 $this->chronProt
->initLB( $this->mainLB
);
233 return $this->mainLB
;
237 * @throws MWException
240 * @return LoadBalancer
242 function newExternalLB( $cluster, $wiki = false ) {
243 global $wgExternalServers;
244 if ( !isset( $wgExternalServers[$cluster] ) ) {
245 throw new MWException( __METHOD__
. ": Unknown cluster \"$cluster\"" );
248 return new LoadBalancer( array(
249 'servers' => $wgExternalServers[$cluster]
258 function &getExternalLB( $cluster, $wiki = false ) {
259 if ( !isset( $this->extLBs
[$cluster] ) ) {
260 $this->extLBs
[$cluster] = $this->newExternalLB( $cluster, $wiki );
261 $this->extLBs
[$cluster]->parentInfo( array( 'id' => "ext-$cluster" ) );
262 $this->chronProt
->initLB( $this->extLBs
[$cluster] );
265 return $this->extLBs
[$cluster];
269 * Execute a function for each tracked load balancer
270 * The callback is called with the load balancer as the first parameter,
271 * and $params passed as the subsequent parameters.
273 * @param $params array
275 function forEachLB( $callback, $params = array() ) {
276 if ( isset( $this->mainLB
) ) {
277 call_user_func_array( $callback, array_merge( array( $this->mainLB
), $params ) );
279 foreach ( $this->extLBs
as $lb ) {
280 call_user_func_array( $callback, array_merge( array( $lb ), $params ) );
284 function shutdown() {
285 if ( $this->mainLB
) {
286 $this->chronProt
->shutdownLB( $this->mainLB
);
288 foreach ( $this->extLBs
as $extLB ) {
289 $this->chronProt
->shutdownLB( $extLB );
291 $this->chronProt
->shutdown();
292 $this->commitMasterChanges();
297 * LBFactory class that throws an error on any attempt to use it.
298 * This will typically be done via wfGetDB().
299 * Call LBFactory::disableBackend() to start using this, and
300 * LBFactory::enableBackend() to return to normal behavior
302 class LBFactory_Fake
extends LBFactory
{
303 function __construct( $conf ) {
306 function newMainLB( $wiki = false ) {
307 throw new DBAccessError
;
310 function getMainLB( $wiki = false ) {
311 throw new DBAccessError
;
314 function newExternalLB( $cluster, $wiki = false ) {
315 throw new DBAccessError
;
318 function &getExternalLB( $cluster, $wiki = false ) {
319 throw new DBAccessError
;
322 function forEachLB( $callback, $params = array() ) {
327 * Exception class for attempted DB access
329 class DBAccessError
extends MWException
{
330 function __construct() {
331 parent
::__construct( "Mediawiki tried to access the database via wfGetDB(). " .
332 "This is not allowed." );