MediaWiki  master
Wikimedia\Rdbms\ChronologyProtector Class Reference

Helper class for mitigating DB replication lag in order to provide "session consistency". More...

Inheritance diagram for Wikimedia\Rdbms\ChronologyProtector:
Collaboration diagram for Wikimedia\Rdbms\ChronologyProtector:

Public Member Functions

 __construct (BagOStuff $store, array $client, $posIndex, $secret='')
 
 applySessionReplicationPosition (ILoadBalancer $lb)
 Apply the "session consistency" DB replication position to a new ILoadBalancer. More...
 
 getClientId ()
 
 getTouched ( $dbName)
 
 setEnabled ( $enabled)
 
 setLogger (LoggerInterface $logger)
 
 setWaitEnabled ( $enabled)
 
 shutdown (callable $workCallback=null, $mode='sync', &$cpIndex=null)
 Notify the ChronologyProtector that the LBFactory is done calling shutdownLB() for now. More...
 
 storeSessionReplicationPosition (ILoadBalancer $lb)
 Save the "session consistency" DB replication position for an end-of-life ILoadBalancer. More...
 

Protected Member Functions

 getStartupMasterPositions ()
 Load in previous master positions for the client. More...
 
 mergePositions ( $curValue, array $shutdownPositions, &$cpIndex=null)
 

Protected Attributes

string $clientId
 Hash of client parameters. More...
 
string [] $clientLogInfo
 Map of client information fields for logging. More...
 
bool $enabled = true
 Whether to no-op all method calls. More...
 
bool $initialized = false
 Whether the client data was loaded. More...
 
string $key
 Storage key name. More...
 
LoggerInterface $logger
 
DBMasterPos [] $shutdownPositions = []
 Map of (DB master name => position) More...
 
float [] $shutdownTouchDBs = []
 Map of (DB master name => 1) More...
 
DBMasterPos [] $startupPositions = []
 Map of (DB master name => position) More...
 
BagOStuff $store
 
bool $wait = true
 Whether to check and wait on positions. More...
 
int null $waitForPosIndex
 Expected minimum index of the last write to the position store. More...
 
int $waitForPosStoreTimeout = self::POS_STORE_WAIT_TIMEOUT
 Max seconds to wait on positions to appear. More...
 

Private Member Functions

 getTouchedKey (BagOStuff $store, $dbName)
 

Detailed Description

Helper class for mitigating DB replication lag in order to provide "session consistency".

This helps to ensure a consistent ordering of events as seen by an client

Kind of like Hawking's [[Chronology Protection Agency]].

Definition at line 39 of file ChronologyProtector.php.

Constructor & Destructor Documentation

◆ __construct()

Wikimedia\Rdbms\ChronologyProtector::__construct ( BagOStuff  $store,
array  $client,
  $posIndex,
  $secret = '' 
)
Parameters
BagOStuff$store
array$clientMap of (ip: <IP>, agent: <user-agent> [, clientId: <hash>] )
int | null$posIndexWrite counter index
string$secretSecret string for HMAC hashing [optional]
Since
1.27

Definition at line 83 of file ChronologyProtector.php.

References Wikimedia\Rdbms\ChronologyProtector\$store, and BagOStuff\makeGlobalKey().

Member Function Documentation

◆ applySessionReplicationPosition()

Wikimedia\Rdbms\ChronologyProtector::applySessionReplicationPosition ( ILoadBalancer  $lb)

Apply the "session consistency" DB replication position to a new ILoadBalancer.

If the stash has a previous master position recorded, this will try to make sure that the next query to a replica DB of that master will see changes up to that position by delaying execution. The delay may timeout and allow stale data if no non-lagged replica DBs are available.

This method should only be called from LBFactory.

Parameters
ILoadBalancer$lb
Returns
void

Definition at line 145 of file ChronologyProtector.php.

References Wikimedia\Rdbms\ILoadBalancer\getServerName(), Wikimedia\Rdbms\ChronologyProtector\getStartupMasterPositions(), Wikimedia\Rdbms\ILoadBalancer\getWriterIndex(), and Wikimedia\Rdbms\ILoadBalancer\waitFor().

◆ getClientId()

Wikimedia\Rdbms\ChronologyProtector::getClientId ( )
Returns
string Client ID hash
Since
1.32

Definition at line 112 of file ChronologyProtector.php.

References Wikimedia\Rdbms\ChronologyProtector\$clientId.

Referenced by Wikimedia\Rdbms\LBFactory\shutdown().

◆ getStartupMasterPositions()

Wikimedia\Rdbms\ChronologyProtector::getStartupMasterPositions ( )
protected

◆ getTouched()

Wikimedia\Rdbms\ChronologyProtector::getTouched (   $dbName)
Parameters
string$dbNameDB master name (e.g. "db1052")
Returns
float|bool UNIX timestamp when client last touched the DB; false if not on record
Since
1.28

Definition at line 276 of file ChronologyProtector.php.

References Wikimedia\Rdbms\ChronologyProtector\getTouchedKey().

◆ getTouchedKey()

Wikimedia\Rdbms\ChronologyProtector::getTouchedKey ( BagOStuff  $store,
  $dbName 
)
private
Parameters
BagOStuff$store
string$dbName
Returns
string

Definition at line 285 of file ChronologyProtector.php.

References BagOStuff\makeGlobalKey().

Referenced by Wikimedia\Rdbms\ChronologyProtector\getTouched(), and Wikimedia\Rdbms\ChronologyProtector\shutdown().

◆ mergePositions()

Wikimedia\Rdbms\ChronologyProtector::mergePositions (   $curValue,
array  $shutdownPositions,
$cpIndex = null 
)
protected
Parameters
array | bool$curValue
DBMasterPos[]$shutdownPositions
int | null&$cpIndex
Returns
array

Definition at line 366 of file ChronologyProtector.php.

Referenced by Wikimedia\Rdbms\ChronologyProtector\shutdown().

◆ setEnabled()

Wikimedia\Rdbms\ChronologyProtector::setEnabled (   $enabled)
Parameters
bool$enabledWhether to no-op all method calls
Since
1.27

Definition at line 120 of file ChronologyProtector.php.

References Wikimedia\Rdbms\ChronologyProtector\$enabled.

◆ setLogger()

Wikimedia\Rdbms\ChronologyProtector::setLogger ( LoggerInterface  $logger)

◆ setWaitEnabled()

Wikimedia\Rdbms\ChronologyProtector::setWaitEnabled (   $enabled)
Parameters
bool$enabledWhether to check and wait on positions
Since
1.27

Definition at line 128 of file ChronologyProtector.php.

References Wikimedia\Rdbms\ChronologyProtector\$enabled.

◆ shutdown()

Wikimedia\Rdbms\ChronologyProtector::shutdown ( callable  $workCallback = null,
  $mode = 'sync',
$cpIndex = null 
)

Notify the ChronologyProtector that the LBFactory is done calling shutdownLB() for now.

May commit chronology data to persistent storage.

Parameters
callable | null$workCallbackWork to do instead of waiting on syncing positions
string$modeOne of (sync, async); whether to wait on remote datacenters
int | null&$cpIndexDB position key write counter; incremented on update
Returns
DBMasterPos[] Empty on success; returns the (db name => position) map on failure

Definition at line 200 of file ChronologyProtector.php.

References Wikimedia\Rdbms\ChronologyProtector\$shutdownPositions, Wikimedia\Rdbms\ChronologyProtector\$store, BagOStuff\addBusyCallback(), BagOStuff\get(), BagOStuff\getQoS(), Wikimedia\Rdbms\ChronologyProtector\getTouchedKey(), BagOStuff\lock(), Wikimedia\Rdbms\ChronologyProtector\mergePositions(), BagOStuff\set(), and BagOStuff\unlock().

Referenced by Wikimedia\Rdbms\LBFactory\shutdownChronologyProtector().

◆ storeSessionReplicationPosition()

Wikimedia\Rdbms\ChronologyProtector::storeSessionReplicationPosition ( ILoadBalancer  $lb)

Save the "session consistency" DB replication position for an end-of-life ILoadBalancer.

This saves the replication position of the master DB if this request made writes to it.

This method should only be called from LBFactory.

Parameters
ILoadBalancer$lb
Returns
void

Definition at line 170 of file ChronologyProtector.php.

References Wikimedia\Rdbms\ILoadBalancer\getReplicaResumePos(), Wikimedia\Rdbms\ILoadBalancer\getServerName(), Wikimedia\Rdbms\ILoadBalancer\getWriterIndex(), Wikimedia\Rdbms\ILoadBalancer\hasOrMadeRecentMasterChanges(), and Wikimedia\Rdbms\ILoadBalancer\hasStreamingReplicaServers().

Referenced by Wikimedia\Rdbms\LBFactory\shutdownChronologyProtector().

Member Data Documentation

◆ $clientId

string Wikimedia\Rdbms\ChronologyProtector::$clientId
protected

Hash of client parameters.

Definition at line 48 of file ChronologyProtector.php.

Referenced by Wikimedia\Rdbms\ChronologyProtector\getClientId().

◆ $clientLogInfo

string [] Wikimedia\Rdbms\ChronologyProtector::$clientLogInfo
protected

Map of client information fields for logging.

Definition at line 50 of file ChronologyProtector.php.

◆ $enabled

bool Wikimedia\Rdbms\ChronologyProtector::$enabled = true
protected

Whether to no-op all method calls.

Definition at line 56 of file ChronologyProtector.php.

Referenced by Wikimedia\Rdbms\ChronologyProtector\setEnabled(), and Wikimedia\Rdbms\ChronologyProtector\setWaitEnabled().

◆ $initialized

bool Wikimedia\Rdbms\ChronologyProtector::$initialized = false
protected

Whether the client data was loaded.

Definition at line 61 of file ChronologyProtector.php.

◆ $key

string Wikimedia\Rdbms\ChronologyProtector::$key
protected

Storage key name.

Definition at line 46 of file ChronologyProtector.php.

◆ $logger

LoggerInterface Wikimedia\Rdbms\ChronologyProtector::$logger
protected

◆ $shutdownPositions

DBMasterPos [] Wikimedia\Rdbms\ChronologyProtector::$shutdownPositions = []
protected

Map of (DB master name => position)

Definition at line 65 of file ChronologyProtector.php.

Referenced by Wikimedia\Rdbms\ChronologyProtector\shutdown().

◆ $shutdownTouchDBs

float [] Wikimedia\Rdbms\ChronologyProtector::$shutdownTouchDBs = []
protected

Map of (DB master name => 1)

Definition at line 67 of file ChronologyProtector.php.

◆ $startupPositions

DBMasterPos [] Wikimedia\Rdbms\ChronologyProtector::$startupPositions = []
protected

Map of (DB master name => position)

Definition at line 63 of file ChronologyProtector.php.

Referenced by Wikimedia\Rdbms\ChronologyProtector\getStartupMasterPositions().

◆ $store

BagOStuff Wikimedia\Rdbms\ChronologyProtector::$store
protected

◆ $wait

bool Wikimedia\Rdbms\ChronologyProtector::$wait = true
protected

Whether to check and wait on positions.

Definition at line 58 of file ChronologyProtector.php.

◆ $waitForPosIndex

int null Wikimedia\Rdbms\ChronologyProtector::$waitForPosIndex
protected

Expected minimum index of the last write to the position store.

Definition at line 52 of file ChronologyProtector.php.

◆ $waitForPosStoreTimeout

int Wikimedia\Rdbms\ChronologyProtector::$waitForPosStoreTimeout = self::POS_STORE_WAIT_TIMEOUT
protected

Max seconds to wait on positions to appear.

Definition at line 54 of file ChronologyProtector.php.

Referenced by Wikimedia\Rdbms\ChronologyProtector\getStartupMasterPositions().


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