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 
46 interface ILBFactory {
48  public const SHUTDOWN_NORMAL = 0;
50  public const SHUTDOWN_NO_CHRONPROT = 1;
51 
53  public const CLUSTER_MAIN_DEFAULT = 'DEFAULT';
54 
76  public function __construct( array $conf );
77 
85  public function destroy();
86 
91  public function autoReconfigure(): void;
92 
100  public function getLocalDomainID();
101 
107  public function resolveDomainID( $domain );
108 
119  public function redefineLocalDomain( $domain );
120 
138  public function newMainLB( $domain = false ): ILoadBalancerForOwner;
139 
151  public function getMainLB( $domain = false ): ILoadBalancer;
152 
168  public function newExternalLB( $cluster ): ILoadBalancerForOwner;
169 
179  public function getExternalLB( $cluster ): ILoadBalancer;
180 
191  public function getAllMainLBs(): array;
192 
201  public function getAllExternalLBs(): array;
202 
209  public function getAllLBs();
210 
219  public function shutdown(
220  $flags = self::SHUTDOWN_NORMAL,
221  callable $workCallback = null,
222  &$cpIndex = null,
223  &$cpClientId = null
224  );
225 
235  public function flushReplicaSnapshots( $fname = __METHOD__ );
236 
252  public function beginPrimaryChanges( $fname = __METHOD__ );
253 
264  public function commitPrimaryChanges( $fname = __METHOD__, int $maxWriteDuration = 0 );
265 
274  public function rollbackPrimaryChanges( $fname = __METHOD__ );
275 
287  public function flushPrimarySessions( $fname = __METHOD__ );
288 
295  public function hasTransactionRound();
296 
305  public function isReadyForRoundOperations();
306 
315  public function hasPrimaryChanges();
316 
324  public function laggedReplicaUsed();
325 
334  public function hasOrMadeRecentPrimaryChanges( $age = null );
335 
361  public function waitForReplication( array $opts = [] );
362 
371  public function setWaitForReplicationListener( $name, callable $callback = null );
372 
379  public function getEmptyTransactionTicket( $fname );
380 
395  public function commitAndWaitForReplication( $fname, $ticket, array $opts = [] );
396 
403  public function getChronologyProtectorTouched( $domain = false );
404 
410  public function disableChronologyProtection();
411 
418  public function setLocalDomainPrefix( $prefix );
419 
425  public function closeAll( $fname = __METHOD__ );
426 
430  public function setAgentName( $agent );
431 
441  public function appendShutdownCPIndexAsQuery( $url, $index );
442 
452  public function setRequestInfo( array $info );
453 
461  public function setDefaultReplicationWaitTimeout( $seconds );
462 
476  public function setTableAliases( array $aliases );
477 
490  public function setIndexAliases( array $aliases );
491 
500  public function setDomainAliases( array $aliases );
501 
509 }
Detect high-contention DB queries via profiling calls.
Manager of ILoadBalancer objects and, indirectly, IDatabase connections.
Definition: ILBFactory.php:46
getLocalDomainID()
Get the local (and default) database domain ID of connection handles.
autoReconfigure()
Reload the configuration if necessary.
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.
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.
setLocalDomainPrefix( $prefix)
Set a new table prefix for the existing local domain ID for testing.
commitPrimaryChanges( $fname=__METHOD__, int $maxWriteDuration=0)
Commit changes and clear view snapshots on all primary connections.
hasPrimaryChanges()
Determine if any primary connection has pending changes.
waitForReplication(array $opts=[])
Waits for the replica database server 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 database server connection was used.
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:50
hasTransactionRound()
Check if an explicit transaction round is active.
const SHUTDOWN_NORMAL
Idiom for "no special shutdown flags".
Definition: ILBFactory.php:48
getAllMainLBs()
Get the tracked load balancer instances for all main clusters.
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 database server transactions, clearing any REPEATABLE-READ/SSI snapshots.
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.
This class is a delegate to ILBFactory for a given database cluster.