MediaWiki  master
ILBFactory.php
Go to the documentation of this file.
1 <?php
20 namespace Wikimedia\Rdbms;
21 
22 use Generator;
23 use InvalidArgumentException;
24 
31 interface ILBFactory {
33  public const SHUTDOWN_NORMAL = 0;
35  public const SHUTDOWN_NO_CHRONPROT = 1;
36 
38  public const CLUSTER_MAIN_DEFAULT = 'DEFAULT';
39 
64  public function __construct( array $conf );
65 
73  public function destroy();
74 
82  public function getLocalDomainID();
83 
89  public function resolveDomainID( $domain );
90 
101  public function redefineLocalDomain( $domain );
102 
120  public function newMainLB( $domain = false ): ILoadBalancerForOwner;
121 
133  public function getMainLB( $domain = false ): ILoadBalancer;
134 
150  public function newExternalLB( $cluster ): ILoadBalancerForOwner;
151 
161  public function getExternalLB( $cluster ): ILoadBalancer;
162 
173  public function getAllMainLBs(): array;
174 
183  public function getAllExternalLBs(): array;
184 
196  public function forEachLB( $callback, array $params = [] );
197 
204  public function getAllLBs();
205 
214  public function shutdown(
215  $flags = self::SHUTDOWN_NORMAL,
216  callable $workCallback = null,
217  &$cpIndex = null,
218  &$cpClientId = null
219  );
220 
230  public function flushReplicaSnapshots( $fname = __METHOD__ );
231 
245  public function commitAll( $fname = __METHOD__, array $options = [] );
246 
263  public function beginPrimaryChanges( $fname = __METHOD__ );
264 
276  public function commitPrimaryChanges( $fname = __METHOD__, array $options = [] );
277 
286  public function rollbackPrimaryChanges( $fname = __METHOD__ );
287 
299  public function flushPrimarySessions( $fname = __METHOD__ );
300 
307  public function hasTransactionRound();
308 
317  public function isReadyForRoundOperations();
318 
327  public function hasPrimaryChanges();
328 
336  public function laggedReplicaUsed();
337 
346  public function hasOrMadeRecentPrimaryChanges( $age = null );
347 
373  public function waitForReplication( array $opts = [] );
374 
383  public function setWaitForReplicationListener( $name, callable $callback = null );
384 
391  public function getEmptyTransactionTicket( $fname );
392 
407  public function commitAndWaitForReplication( $fname, $ticket, array $opts = [] );
408 
415  public function getChronologyProtectorTouched( $domain = false );
416 
422  public function disableChronologyProtection();
423 
430  public function setLocalDomainPrefix( $prefix );
431 
437  public function closeAll( $fname = __METHOD__ );
438 
442  public function setAgentName( $agent );
443 
453  public function appendShutdownCPIndexAsQuery( $url, $index );
454 
462 
472  public function setRequestInfo( array $info );
473 
481  public function setDefaultReplicationWaitTimeout( $seconds );
482 
496  public function setTableAliases( array $aliases );
497 
510  public function setIndexAliases( array $aliases );
511 
520  public function setDomainAliases( array $aliases );
521 
529 }
Detect high-contention DB queries via profiling calls.
Manager of ILoadBalancer objects, and indirectly of IDatabase connections.
Definition: ILBFactory.php:31
getLocalDomainID()
Get the local (and default) database domain ID of connection handles.
redefineLocalDomain( $domain)
Close all connections and redefine the local database domain.
beginPrimaryChanges( $fname=__METHOD__)
Flush any primary transaction snapshots and set DBO_TRX (if DBO_DEFAULT is set)
getAllExternalLBs()
Get the tracked load balancer instances for all external clusters.
commitAll( $fname=__METHOD__, array $options=[])
Commit open transactions on all connections.
setRequestInfo(array $info)
Inject HTTP request header/cookie information during setup of this instance.
setTableAliases(array $aliases)
Make certain table names use their own database, schema, and table prefix when passed into SQL querie...
newMainLB( $domain=false)
Create a new load balancer instance for the main cluster that handles the given domain.
commitPrimaryChanges( $fname=__METHOD__, array $options=[])
Commit changes and clear view snapshots on all primary connections.
setLocalDomainPrefix( $prefix)
Set a new table prefix for the existing local domain ID for testing.
hasPrimaryChanges()
Determine if any primary connection has pending changes.
waitForReplication(array $opts=[])
Waits for the replica DBs to catch up to the current primary position.
rollbackPrimaryChanges( $fname=__METHOD__)
Rollback changes on all primary connections.
closeAll( $fname=__METHOD__)
Close all connections on instantiated tracked load balancer instances.
commitAndWaitForReplication( $fname, $ticket, array $opts=[])
Call commitPrimaryChanges() and waitForReplication() if $ticket indicates it is safe.
flushPrimarySessions( $fname=__METHOD__)
Release important session-level state (named lock, table locks) as post-rollback cleanup.
__construct(array $conf)
Sub-classes may extend the required keys in $conf with additional parameters.
shutdown( $flags=self::SHUTDOWN_NORMAL, callable $workCallback=null, &$cpIndex=null, &$cpClientId=null)
Prepare all instantiated tracked load balancer instances for shutdown.
destroy()
Close all connections and make further attempts to open connections result in DBAccessError.
laggedReplicaUsed()
Determine if any lagged replica DB connection was used.
getChronologyProtectorClientId()
Get the client ID of the ChronologyProtector instance.
getAllLBs()
Get all tracked load balancer instances (generator)
setDomainAliases(array $aliases)
Convert certain database domains to alternative ones.
getExternalLB( $cluster)
Get the tracked load balancer instance for an external cluster.
getMainLB( $domain=false)
Get the tracked load balancer instance for the main cluster that handles the given domain.
disableChronologyProtection()
Disable the ChronologyProtector on all instantiated tracked load balancer instances.
setDefaultReplicationWaitTimeout( $seconds)
Set the default timeout for replication wait checks.
const SHUTDOWN_NO_CHRONPROT
Do not save "session consistency" DB replication positions.
Definition: ILBFactory.php:35
hasTransactionRound()
Check if an explicit transaction round is active.
const SHUTDOWN_NORMAL
Idiom for "no special shutdown flags".
Definition: ILBFactory.php:33
getAllMainLBs()
Get the tracked load balancer instances for all main clusters.
forEachLB( $callback, array $params=[])
Execute a function for each instantiated tracked load balancer instance.
getTransactionProfiler()
Get the TransactionProfiler used by this instance.
setIndexAliases(array $aliases)
Convert certain index names to alternative names before querying the DB.
appendShutdownCPIndexAsQuery( $url, $index)
Append ?cpPosIndex parameter to a URL for ChronologyProtector purposes if needed.
getChronologyProtectorTouched( $domain=false)
Get the UNIX timestamp when the client last touched the DB, if they did so recently.
hasOrMadeRecentPrimaryChanges( $age=null)
Determine if any primary connection has pending/written changes from this request.
getEmptyTransactionTicket( $fname)
Get a token asserting that no transaction writes are active on tracked load balancers.
newExternalLB( $cluster)
Create a new load balancer instance for an external cluster.
isReadyForRoundOperations()
Check if transaction rounds can be started, committed, or rolled back right now.
flushReplicaSnapshots( $fname=__METHOD__)
Commit all replica DB transactions so as to flush any REPEATABLE-READ or SSI snapshot.
setWaitForReplicationListener( $name, callable $callback=null)
Add a callback to be run in every call to waitForReplication() before waiting.
Internal interface for LoadBalancer methods used by LBFactory.
Create and track the database connections and transactions for a given database cluster.