MediaWiki  1.27.2
LBFactory Class Reference

An interface for generating database load balancers. More...

Inheritance diagram for LBFactory:
Collaboration diagram for LBFactory:

Public Member Functions

 __construct (array $conf)
 Construct a factory based on a configuration array (typically from $wgLBFactoryConf) More...
 
 commitAll ($fname=__METHOD__)
 Commit on all connections. More...
 
 commitMasterChanges ($fname=__METHOD__, array $options=[])
 Commit changes on all master connections. More...
 
 disableChronologyProtection ()
 Disable the ChronologyProtector for all load balancers. More...
 
 forEachLB ($callback, array $params=[])
 Execute a function for each tracked load balancer The callback is called with the load balancer as the first parameter, and $params passed as the subsequent parameters. More...
 
getExternalLB ($cluster, $wiki=false)
 Get a cached (tracked) load balancer for external storage. More...
 
 getMainLB ($wiki=false)
 Get a cached (tracked) load balancer object. More...
 
 hasMasterChanges ()
 Determine if any master connection has pending changes. More...
 
 hasOrMadeRecentMasterChanges ()
 Determine if any master connection has pending/written changes from this request. More...
 
 laggedSlaveUsed ()
 Detemine if any lagged slave connection was used. More...
 
 newMainLB ($wiki=false)
 Create a new load balancer object. More...
 
 rollbackMasterChanges ($fname=__METHOD__)
 Rollback changes on all master connections. More...
 
 shutdown ($flags=0)
 Prepare all tracked load balancers for shutdown. More...
 
 waitForReplication (array $opts=[])
 Waits for the slave DBs to catch up to the current master position. More...
 

Static Public Member Functions

static destroyInstance ()
 Shut down, close connections and destroy the cached instance. More...
 
static disableBackend ()
 Disables all access to the load balancer, will cause all database access to throw a DBAccessError. More...
 
static getLBFactoryClass (array $config)
 Returns the LBFactory class to use and the load balancer configuration. More...
 
static setInstance ($instance)
 Set the instance to be the given object. More...
 
static singleton ()
 Get an LBFactory instance. More...
 

Public Attributes

const SHUTDOWN_NO_CHRONPROT = 1
 

Protected Member Functions

 newChronologyProtector ()
 
 newExternalLB ($cluster, $wiki=false)
 Create a new load balancer for external storage. More...
 
 shutdownChronologyProtector (ChronologyProtector $cp)
 

Protected Attributes

ChronologyProtector $chronProt
 
LoggerInterface $logger
 
string bool $readOnlyReason = false
 Reason all LBs are read-only or false if not. More...
 
TransactionProfiler $trxProfiler
 

Private Member Functions

 forEachLBCallMethod ($methodName, array $args=[])
 Call a method of each tracked load balancer. More...
 
 logMultiDbTransaction ()
 Log query info if multi DB transactions are going to be committed now. More...
 

Static Private Attributes

static LBFactory $instance
 

Detailed Description

An interface for generating database load balancers.

Definition at line 31 of file LBFactory.php.

Constructor & Destructor Documentation

LBFactory::__construct ( array  $conf)

Construct a factory based on a configuration array (typically from $wgLBFactoryConf)

Parameters
array$conf

Definition at line 53 of file LBFactory.php.

References Profiler\instance(), and newChronologyProtector().

Member Function Documentation

LBFactory::commitAll (   $fname = __METHOD__)

Commit on all connections.

Done for two reasons:

  1. To commit changes to the masters.
  2. To release the snapshot on all connections, master and slave.
    Parameters
    string$fnameCaller name

Definition at line 218 of file LBFactory.php.

References $fname, forEachLBCallMethod(), RequestContext\getMain(), and logMultiDbTransaction().

LBFactory::commitMasterChanges (   $fname = __METHOD__,
array  $options = [] 
)

Commit changes on all master connections.

Parameters
string$fnameCaller name
array$optionsOptions map:
  • maxWriteDuration: abort if more than this much time was spent in write queries

Definition at line 234 of file LBFactory.php.

References $fname, $limit, $options, $time, forEachLB(), forEachLBCallMethod(), LoadBalancer\forEachOpenConnection(), logMultiDbTransaction(), IDatabase\pendingWriteQueryDuration(), text, use, and wfMessage().

Referenced by LBFactorySimple\shutdown(), and LBFactoryMulti\shutdown().

static LBFactory::destroyInstance ( )
static

Shut down, close connections and destroy the cached instance.

Definition at line 124 of file LBFactory.php.

Referenced by Maintenance\finalSetup().

static LBFactory::disableBackend ( )
static

Disables all access to the load balancer, will cause all database access to throw a DBAccessError.

Definition at line 67 of file LBFactory.php.

References $wgLBFactoryConf, and global.

Referenced by Installer\__construct().

LBFactory::disableChronologyProtection ( )

Disable the ChronologyProtector for all load balancers.

This can be called at the start of special API entry points

Since
1.27

Definition at line 417 of file LBFactory.php.

LBFactory::forEachLB (   $callback,
array  $params = [] 
)
abstract

Execute a function for each tracked load balancer The callback is called with the load balancer as the first parameter, and $params passed as the subsequent parameters.

Parameters
callable$callback
array$params

Referenced by commitMasterChanges(), forEachLBCallMethod(), hasMasterChanges(), hasOrMadeRecentMasterChanges(), laggedSlaveUsed(), logMultiDbTransaction(), shutdownChronologyProtector(), and waitForReplication().

LBFactory::forEachLBCallMethod (   $methodName,
array  $args = [] 
)
private

Call a method of each tracked load balancer.

Parameters
string$methodName
array$args

Definition at line 203 of file LBFactory.php.

References $args, array(), and forEachLB().

Referenced by commitAll(), commitMasterChanges(), and rollbackMasterChanges().

& LBFactory::getExternalLB (   $cluster,
  $wiki = false 
)
abstract

Get a cached (tracked) load balancer for external storage.

Parameters
string$clusterExternal storage cluster, or false for core
bool | string$wikiWiki ID, or false for the current wiki
Returns
LoadBalancer

Referenced by waitForReplication().

static LBFactory::getLBFactoryClass ( array  $config)
static

Returns the LBFactory class to use and the load balancer configuration.

Parameters
array$config(e.g. $wgLBFactoryConf)
Returns
string Class name

Definition at line 98 of file LBFactory.php.

References wfDeprecated().

Referenced by LBFactoryTest\testGetLBFactoryClass().

LBFactory::getMainLB (   $wiki = false)
abstract

Get a cached (tracked) load balancer object.

Parameters
bool | string$wikiWiki ID, or false for the current wiki
Returns
LoadBalancer

Referenced by waitForReplication().

LBFactory::hasMasterChanges ( )

Determine if any master connection has pending changes.

Returns
bool
Since
1.23

Definition at line 290 of file LBFactory.php.

References $ret, forEachLB(), LoadBalancer\hasMasterChanges(), and use.

LBFactory::hasOrMadeRecentMasterChanges ( )

Determine if any master connection has pending/written changes from this request.

Returns
bool
Since
1.27

Definition at line 318 of file LBFactory.php.

References $ret, forEachLB(), LoadBalancer\hasOrMadeRecentMasterChanges(), and use.

LBFactory::laggedSlaveUsed ( )

Detemine if any lagged slave connection was used.

Since
1.27
Returns
bool

Definition at line 304 of file LBFactory.php.

References $ret, forEachLB(), LoadBalancer\laggedSlaveUsed(), and use.

LBFactory::logMultiDbTransaction ( )
private

Log query info if multi DB transactions are going to be committed now.

Definition at line 265 of file LBFactory.php.

References as, forEachLB(), LoadBalancer\getServerName(), LoadBalancer\getWriterIndex(), LoadBalancer\pendingMasterChangeCallers(), and use.

Referenced by commitAll(), and commitMasterChanges().

LBFactory::newChronologyProtector ( )
protected
LBFactory::newExternalLB (   $cluster,
  $wiki = false 
)
abstractprotected

Create a new load balancer for external storage.

The resulting object will be untracked, not chronology-protected, and the caller is responsible for cleaning it up.

Parameters
string$clusterExternal storage cluster, or false for core
bool | string$wikiWiki ID, or false for the current wiki
Returns
LoadBalancer
LBFactory::newMainLB (   $wiki = false)
abstract

Create a new load balancer object.

The resulting object will be untracked, not chronology-protected, and the caller is responsible for cleaning it up.

Parameters
bool | string$wikiWiki ID, or false for the current wiki
Returns
LoadBalancer
LBFactory::rollbackMasterChanges (   $fname = __METHOD__)

Rollback changes on all master connections.

Parameters
string$fnameCaller name
Since
1.23

Definition at line 258 of file LBFactory.php.

References $fname, and forEachLBCallMethod().

static LBFactory::setInstance (   $instance)
static

Set the instance to be the given object.

Parameters
LBFactory$instance

Definition at line 137 of file LBFactory.php.

References $instance.

Referenced by DatabaseInstaller\enableLB().

LBFactory::shutdown (   $flags = 0)

Prepare all tracked load balancers for shutdown.

Parameters
integer$flagsSupports SHUTDOWN_* flags STUB

Definition at line 194 of file LBFactory.php.

static LBFactory::singleton ( )
static

Get an LBFactory instance.

Returns
LBFactory

Definition at line 77 of file LBFactory.php.

References $wgLBFactoryConf, global, and wfConfiguredReadOnlyReason().

LBFactory::waitForReplication ( array  $opts = [])

Waits for the slave DBs to catch up to the current master position.

Use this when updating very large numbers of rows, as in maintenance scripts, to avoid causing too much lag. Of course, this is a no-op if there are no slaves.

By default this waits on all DB clusters actually used in this request. This makes sense when lag being waiting on is caused by the code that does this check. In that case, setting "ifWritesSince" can avoid the overhead of waiting for clusters that were not changed since the last wait check. To forcefully wait on a specific cluster for a given wiki, use the 'wiki' parameter. To forcefully wait on an "external" cluster, use the "cluster" parameter.

Never call this function after a large DB write that is still in a transaction. It only makes sense to call this after the possible lag inducing changes were committed.

Parameters
array$optsOptional fields that include:
  • wiki : wait on the load balancer DBs that handles the given wiki
  • cluster : wait on the given external load balancer DBs
  • timeout : Max wait time. Default: ~60 seconds
  • ifWritesSince: Only wait if writes were done since this UNIX timestamp
Exceptions
DBReplicationWaitErrorIf a timeout or error occured waiting on a DB cluster
Since
1.27

Definition at line 350 of file LBFactory.php.

References as, forEachLB(), getExternalLB(), getMainLB(), and use.

Member Data Documentation

ChronologyProtector LBFactory::$chronProt
protected

Definition at line 33 of file LBFactory.php.

Referenced by newChronologyProtector().

LBFactory LBFactory::$instance
staticprivate

Definition at line 42 of file LBFactory.php.

Referenced by setInstance().

LoggerInterface LBFactory::$logger
protected

Definition at line 39 of file LBFactory.php.

string bool LBFactory::$readOnlyReason = false
protected

Reason all LBs are read-only or false if not.

Definition at line 45 of file LBFactory.php.

Referenced by LBFactoryMulti\newLoadBalancer(), and LBFactoryMulti\newMainLB().

TransactionProfiler LBFactory::$trxProfiler
protected

Definition at line 36 of file LBFactory.php.

const LBFactory::SHUTDOWN_NO_CHRONPROT = 1

Definition at line 47 of file LBFactory.php.

Referenced by MediaWiki\restInPeace().


The documentation for this class was generated from the following file: