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:

[legend]

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)

	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, $masterName)

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	$client	Map of (ip: <IP>, agent: <user-agent> [, clientId: <hash>] )
int \| null	$posIndex	Write counter index
string	$secret	Secret string for HMAC hashing [optional]

Since: 1.27

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

References Wikimedia\Rdbms\ChronologyProtector\$startupPositions, 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 114 of file ChronologyProtector.php.

References Wikimedia\Rdbms\ChronologyProtector\$clientId.

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

◆ getStartupMasterPositions()

Wikimedia\Rdbms\ChronologyProtector::getStartupMasterPositions ( )

protected

Load in previous master positions for the client.

Returns: DBMasterPos[]

Definition at line 297 of file ChronologyProtector.php.

References Wikimedia\Rdbms\ChronologyProtector\$startupPositions, and Wikimedia\Rdbms\ChronologyProtector\$waitForPosStoreTimeout.

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

◆ getTouched()

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

Parameters

ILoadBalancer $lb The load balancer. Prior to 1.35, the first parameter was the master name.

Returns: float|bool UNIX timestamp when client last touched the DB; false if not on record

Since: 1.35

Definition at line 279 of file ChronologyProtector.php.

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

◆ getTouchedKey()

Wikimedia\Rdbms\ChronologyProtector::getTouchedKey	(	BagOStuff	$store,
			$masterName
	)

private

Parameters

BagOStuff	$store
string	$masterName

Returns: string

Definition at line 289 of file ChronologyProtector.php.

References Wikimedia\Rdbms\ChronologyProtector\$store, and 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 371 of file ChronologyProtector.php.

References Wikimedia\Rdbms\ChronologyProtector\$shutdownPositions.

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

◆ setEnabled()

Wikimedia\Rdbms\ChronologyProtector::setEnabled ( $enabled )

Parameters

bool $enabled Whether to no-op all method calls

Since: 1.27

Definition at line 122 of file ChronologyProtector.php.

References Wikimedia\Rdbms\ChronologyProtector\$enabled.

◆ setLogger()

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

Definition at line 106 of file ChronologyProtector.php.

References Wikimedia\Rdbms\ChronologyProtector\$logger.

◆ setWaitEnabled()

Wikimedia\Rdbms\ChronologyProtector::setWaitEnabled ( $enabled )

Parameters

bool $enabled Whether to check and wait on positions

Since: 1.27

Definition at line 130 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	$workCallback	Work to do instead of waiting on syncing positions
string	$mode	One of (sync, async); whether to wait on remote datacenters
int \| null	&$cpIndex	DB position key write counter; incremented on update

Returns: DBMasterPos[] Empty on success; returns the (db name => position) map on failure

Definition at line 202 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 172 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 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 to no-op all method calls.

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

◆ $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

Definition at line 45 of file ChronologyProtector.php.

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

◆ $shutdownPositions

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

protected

Map of (DB master name => position)

Definition at line 67 of file ChronologyProtector.php.

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

◆ $shutdownTouchDBs

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

protected

Map of (DB master name => 1)

Definition at line 69 of file ChronologyProtector.php.

◆ $startupPositions

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

protected

Map of (DB master name => position)

Definition at line 65 of file ChronologyProtector.php.

Referenced by Wikimedia\Rdbms\ChronologyProtector\applySessionReplicationPosition(), and Wikimedia\Rdbms\ChronologyProtector\getStartupMasterPositions().

◆ $store

BagOStuff Wikimedia\Rdbms\ChronologyProtector::$store

protected

Definition at line 43 of file ChronologyProtector.php.

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

◆ $wait

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

protected

Whether to check and wait on positions.

Definition at line 60 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 54 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 56 of file ChronologyProtector.php.

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

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

includes/libs/rdbms/ChronologyProtector.php

Public Member Functions

Protected Member Functions

Protected Attributes

Private Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ __construct()

Member Function Documentation

◆ applySessionReplicationPosition()

◆ getClientId()

◆ getStartupMasterPositions()

◆ getTouched()

◆ getTouchedKey()

◆ mergePositions()

◆ setEnabled()

◆ setLogger()

◆ setWaitEnabled()

◆ shutdown()

◆ storeSessionReplicationPosition()

Member Data Documentation

◆ $clientId

◆ $clientLogInfo

◆ $enabled

◆ $initialized

◆ $key

◆ $logger

◆ $shutdownPositions

◆ $shutdownTouchDBs

◆ $startupPositions

◆ $store

◆ $wait

◆ $waitForPosIndex

◆ $waitForPosStoreTimeout