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 (ILoadBalancer $lb)
 Get the UNIX timestamp when the client last touched the DB, if they did so recently. More...
 
 setEnabled ( $enabled)
 
 setLogger (LoggerInterface $logger)
 
 setMockTime (&$time)
 
 setWaitEnabled ( $enabled)
 
 shutdown (&$cpIndex=null)
 Save any remarked "session consistency" DB replication positions to persistent storage. More...
 
 stageSessionReplicationPosition (ILoadBalancer $lb)
 Update the "session consistency" DB replication position for an end-of-life ILoadBalancer. More...
 

Public Attributes

const POSITION_COOKIE_TTL = 10
 Seconds to store position write index cookies (safely less than POSITION_STORE_TTL) More...
 

Protected Member Functions

 getCurrentTime ()
 
 getStartupSessionPositions ()
 
 getStartupSessionTimestamps ()
 
 lazyStartup ()
 Load the stored DB replication positions and touch timestamps for the client. More...
 
 mergePositions ( $storedValue, array $shutdownPositions, array $shutdownTimestamps, &$cpIndex=null)
 Merge the new DB replication positions with the currently stored ones (highest wins) More...
 

Protected Attributes

string $clientId
 Hash of client parameters. More...
 
string[] $clientLogInfo
 Map of client information fields for logging. More...
 
bool $enabled = true
 Whether reading/writing session consistency replication positions is enabled. More...
 
string $key
 Storage key name. More...
 
LoggerInterface $logger
 
bool $positionWaitsEnabled = true
 Whether waiting on DB servers to reach replication positions is enabled. More...
 
array< string, DBMasterPos$shutdownPositionsByMaster = []
 Map of (DB master name => position) More...
 
array< string, float > $shutdownTimestampsByCluster = []
 Map of (DB cluster name => UNIX timestamp) More...
 
array< string, DBMasterPos$startupPositionsByMaster = []
 Map of (DB master name => position) More...
 
float null $startupTimestamp
 UNIX timestamp when the client data was loaded. More...
 
array< string, float > $startupTimestampsByCluster = []
 Map of (DB cluster name => UNIX timestamp) More...
 
BagOStuff $store
 
int null $waitForPosIndex
 Expected minimum index of the last write to the position store. More...
 

Private Attributes

float null $wallClockOverride
 
const FLD_POSITIONS = 'positions'
 
const FLD_TIMESTAMPS = 'timestamps'
 
const FLD_WRITE_INDEX = 'writeIndex'
 
const LOCK_TIMEOUT = 3
 Lock timeout to use for key updates. More...
 
const LOCK_TTL = 6
 Lock expiry to use for key updates. More...
 
const POSITION_INDEX_WAIT_TIMEOUT = 5
 Max seconds to wait for positions write indexes to appear (e.g. More...
 
const POSITION_STORE_TTL = 60
 Seconds to store replication positions. More...
 

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 41 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 98 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.

Definition at line 161 of file ChronologyProtector.php.

References Wikimedia\Rdbms\ILoadBalancer\getClusterName(), Wikimedia\Rdbms\ILoadBalancer\getServerName(), Wikimedia\Rdbms\ChronologyProtector\getStartupSessionPositions(), 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 128 of file ChronologyProtector.php.

References Wikimedia\Rdbms\ChronologyProtector\$clientId.

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

◆ getCurrentTime()

Wikimedia\Rdbms\ChronologyProtector::getCurrentTime ( )
protected

◆ getStartupSessionPositions()

Wikimedia\Rdbms\ChronologyProtector::getStartupSessionPositions ( )
protected

◆ getStartupSessionTimestamps()

Wikimedia\Rdbms\ChronologyProtector::getStartupSessionTimestamps ( )
protected

◆ getTouched()

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

Get the UNIX timestamp when the client last touched the DB, if they did so recently.

Definition at line 278 of file ChronologyProtector.php.

References Wikimedia\Rdbms\ILoadBalancer\getClusterName(), and Wikimedia\Rdbms\ChronologyProtector\getStartupSessionTimestamps().

◆ lazyStartup()

◆ mergePositions()

Wikimedia\Rdbms\ChronologyProtector::mergePositions (   $storedValue,
array  $shutdownPositions,
array  $shutdownTimestamps,
$cpIndex = null 
)
protected

Merge the new DB replication positions with the currently stored ones (highest wins)

Parameters
array<string,mixed>|false$storedValue Current DB replication position data
array<string,DBMasterPos>$shutdownPositions New DB replication positions
array<string,float>$shutdownTimestamps New DB post-commit shutdown timestamps
int | null&$cpIndexNew position write index
Returns
array<string,mixed> Combined DB replication position data

Definition at line 407 of file ChronologyProtector.php.

References Wikimedia\Rdbms\ChronologyProtector\FLD_POSITIONS, Wikimedia\Rdbms\ChronologyProtector\FLD_TIMESTAMPS, and Wikimedia\Rdbms\ChronologyProtector\FLD_WRITE_INDEX.

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

◆ setEnabled()

Wikimedia\Rdbms\ChronologyProtector::setEnabled (   $enabled)
Parameters
bool$enabledWhether reading/writing session replication positions is enabled
Since
1.27

Definition at line 136 of file ChronologyProtector.php.

References Wikimedia\Rdbms\ChronologyProtector\$enabled.

◆ setLogger()

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

◆ setMockTime()

Wikimedia\Rdbms\ChronologyProtector::setMockTime ( $time)

Definition at line 468 of file ChronologyProtector.php.

◆ setWaitEnabled()

Wikimedia\Rdbms\ChronologyProtector::setWaitEnabled (   $enabled)
Parameters
bool$enabledWhether session replication position wait barriers are enable
Since
1.27

Definition at line 144 of file ChronologyProtector.php.

References Wikimedia\Rdbms\ChronologyProtector\$enabled.

◆ shutdown()

Wikimedia\Rdbms\ChronologyProtector::shutdown ( $cpIndex = null)

Save any remarked "session consistency" DB replication positions to persistent storage.

Definition at line 221 of file ChronologyProtector.php.

References Wikimedia\Rdbms\ChronologyProtector\$shutdownPositionsByMaster, and Wikimedia\Rdbms\ChronologyProtector\mergePositions().

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

◆ stageSessionReplicationPosition()

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

Member Data Documentation

◆ $clientId

string Wikimedia\Rdbms\ChronologyProtector::$clientId
protected

Hash of client parameters.

Definition at line 50 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 52 of file ChronologyProtector.php.

◆ $enabled

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

Whether reading/writing session consistency replication positions is enabled.

Definition at line 57 of file ChronologyProtector.php.

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

◆ $key

string Wikimedia\Rdbms\ChronologyProtector::$key
protected

Storage key name.

Definition at line 48 of file ChronologyProtector.php.

◆ $logger

LoggerInterface Wikimedia\Rdbms\ChronologyProtector::$logger
protected

◆ $positionWaitsEnabled

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

Whether waiting on DB servers to reach replication positions is enabled.

Definition at line 59 of file ChronologyProtector.php.

◆ $shutdownPositionsByMaster

array<string,DBMasterPos> Wikimedia\Rdbms\ChronologyProtector::$shutdownPositionsByMaster = []
protected

Map of (DB master name => position)

Definition at line 66 of file ChronologyProtector.php.

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

◆ $shutdownTimestampsByCluster

array<string,float> Wikimedia\Rdbms\ChronologyProtector::$shutdownTimestampsByCluster = []
protected

Map of (DB cluster name => UNIX timestamp)

Definition at line 70 of file ChronologyProtector.php.

◆ $startupPositionsByMaster

array<string,DBMasterPos> Wikimedia\Rdbms\ChronologyProtector::$startupPositionsByMaster = []
protected

Map of (DB master name => position)

Definition at line 64 of file ChronologyProtector.php.

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

◆ $startupTimestamp

float null Wikimedia\Rdbms\ChronologyProtector::$startupTimestamp
protected

UNIX timestamp when the client data was loaded.

Definition at line 61 of file ChronologyProtector.php.

◆ $startupTimestampsByCluster

array<string,float> Wikimedia\Rdbms\ChronologyProtector::$startupTimestampsByCluster = []
protected

Map of (DB cluster name => UNIX timestamp)

Definition at line 68 of file ChronologyProtector.php.

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

◆ $store

BagOStuff Wikimedia\Rdbms\ChronologyProtector::$store
protected

◆ $waitForPosIndex

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

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

Definition at line 54 of file ChronologyProtector.php.

◆ $wallClockOverride

float null Wikimedia\Rdbms\ChronologyProtector::$wallClockOverride
private

◆ FLD_POSITIONS

const Wikimedia\Rdbms\ChronologyProtector::FLD_POSITIONS = 'positions'
private

◆ FLD_TIMESTAMPS

const Wikimedia\Rdbms\ChronologyProtector::FLD_TIMESTAMPS = 'timestamps'
private

◆ FLD_WRITE_INDEX

const Wikimedia\Rdbms\ChronologyProtector::FLD_WRITE_INDEX = 'writeIndex'
private

◆ LOCK_TIMEOUT

const Wikimedia\Rdbms\ChronologyProtector::LOCK_TIMEOUT = 3
private

Lock timeout to use for key updates.

Definition at line 83 of file ChronologyProtector.php.

◆ LOCK_TTL

const Wikimedia\Rdbms\ChronologyProtector::LOCK_TTL = 6
private

Lock expiry to use for key updates.

Definition at line 85 of file ChronologyProtector.php.

◆ POSITION_COOKIE_TTL

const Wikimedia\Rdbms\ChronologyProtector::POSITION_COOKIE_TTL = 10

Seconds to store position write index cookies (safely less than POSITION_STORE_TTL)

Definition at line 76 of file ChronologyProtector.php.

◆ POSITION_INDEX_WAIT_TIMEOUT

const Wikimedia\Rdbms\ChronologyProtector::POSITION_INDEX_WAIT_TIMEOUT = 5
private

Max seconds to wait for positions write indexes to appear (e.g.

replicate) in storage

Definition at line 80 of file ChronologyProtector.php.

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

◆ POSITION_STORE_TTL

const Wikimedia\Rdbms\ChronologyProtector::POSITION_STORE_TTL = 60
private

Seconds to store replication positions.

Definition at line 78 of file ChronologyProtector.php.


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