Class for ensuring a consistent ordering of events as seen by the user, despite replication. More...

Inheritance diagram for Wikimedia\Rdbms\ChronologyProtector:

Collaboration diagram for Wikimedia\Rdbms\ChronologyProtector:

Public Member Functions
	__construct (BagOStuff $store, array $client, $posIndex, $secret='')

	getClientId ()

	getTouched ( $dbName)

	initLB (ILoadBalancer $lb)
	Initialise a ILoadBalancer to give it appropriate chronology protection. More...

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

	shutdownLB (ILoadBalancer $lb)
	Notify the ChronologyProtector that the ILoadBalancer is about to shut down. More...

Protected Member Functions
	initPositions ()
	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

Class for ensuring a consistent ordering of events as seen by the user, despite replication.

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

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

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

Member Function Documentation

◆ getClientId()

Wikimedia\Rdbms\ChronologyProtector::getClientId ( )

Returns: string Client ID hash

Since: 1.32

Definition at line 109 of file ChronologyProtector.php.

References Wikimedia\Rdbms\ChronologyProtector\$clientId.

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

◆ getTouched()

Wikimedia\Rdbms\ChronologyProtector::getTouched ( $dbName )

Parameters

string $dbName DB 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 269 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 278 of file ChronologyProtector.php.

References BagOStuff\makeGlobalKey().

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

◆ initLB()

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

Initialise a ILoadBalancer to give it appropriate chronology protection.

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.

Parameters

ILoadBalancer $lb

Returns: void

Definition at line 140 of file ChronologyProtector.php.

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

◆ initPositions()

Wikimedia\Rdbms\ChronologyProtector::initPositions ( )

protected

Load in previous master positions for the client.

Definition at line 285 of file ChronologyProtector.php.

References Wikimedia\Rdbms\ChronologyProtector\$waitForPosStoreTimeout, key, null, and use.

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

◆ 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 355 of file ChronologyProtector.php.

References as.

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 117 of file ChronologyProtector.php.

References Wikimedia\Rdbms\ChronologyProtector\$enabled.

◆ setLogger()

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

Definition at line 101 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 125 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 195 of file ChronologyProtector.php.

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

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

◆ shutdownLB()

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

Notify the ChronologyProtector that the ILoadBalancer is about to shut down.

Saves replication positions.

Parameters

ILoadBalancer $lb

Returns: void

Definition at line 165 of file ChronologyProtector.php.

References Wikimedia\Rdbms\ILoadBalancer\getMasterPos(), Wikimedia\Rdbms\ILoadBalancer\getServerCount(), Wikimedia\Rdbms\ILoadBalancer\getServerName(), Wikimedia\Rdbms\ILoadBalancer\getWriterIndex(), and Wikimedia\Rdbms\ILoadBalancer\hasOrMadeRecentMasterChanges().

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

Member Data Documentation

◆ $clientId

string Wikimedia\Rdbms\ChronologyProtector::$clientId

protected

Hash of client parameters.

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

◆ $enabled

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

protected

Whether to no-op all method calls.

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

◆ $key

string Wikimedia\Rdbms\ChronologyProtector::$key

protected

Storage key name.

Definition at line 43 of file ChronologyProtector.php.

◆ $logger

LoggerInterface Wikimedia\Rdbms\ChronologyProtector::$logger

protected

Definition at line 40 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 62 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 64 of file ChronologyProtector.php.

◆ $startupPositions

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

protected

Map of (DB master name => position)

Definition at line 60 of file ChronologyProtector.php.

◆ $store

BagOStuff Wikimedia\Rdbms\ChronologyProtector::$store

protected

Definition at line 38 of file ChronologyProtector.php.

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

◆ $wait

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

protected

Whether to check and wait on positions.

Definition at line 55 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 49 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 51 of file ChronologyProtector.php.

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

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

◆ getClientId()

◆ getTouched()

◆ getTouchedKey()

◆ initLB()

◆ initPositions()

◆ mergePositions()

◆ setEnabled()

◆ setLogger()

◆ setWaitEnabled()

◆ shutdown()

◆ shutdownLB()

Member Data Documentation

◆ $clientId

◆ $clientLogInfo

◆ $enabled

◆ $initialized

◆ $key

◆ $logger

◆ $shutdownPositions

◆ $shutdownTouchDBs

◆ $startupPositions

◆ $store

◆ $wait

◆ $waitForPosIndex

◆ $waitForPosStoreTimeout