interface is intended to be more or less compatible with the PHP memcached client. More...

Inheritance diagram for BagOStuff:

Collaboration diagram for BagOStuff:

Public Member Functions
	__construct (array $params=[])
	$params include: More...

	add ($key, $value, $exptime=0)

	clearLastError ()
	Clear the "last error" registry. More...

	decr ($key, $value=1)
	Decrease stored value of $key by $value while preserving its TTL. More...

	delete ($key)
	Delete an item. More...

	deleteObjectsExpiringBefore ($date, $progressCallback=false)
	Delete all objects expiring before a certain date. More...

	get ($key, $flags=0, $oldFlags=null)
	Get an item with the given key. More...

	getLastError ()
	Get the "last error" registered; clearLastError() should be called manually. More...

	getMulti (array $keys, $flags=0)
	Get an associative array containing the item for each of the keys that have items. More...

	getScopedLock ($key, $timeout=6, $expiry=30, $rclass= '')
	Get a lightweight exclusive self-unlocking lock. More...

	getWithSetCallback ($key, $ttl, $callback, $flags=0)
	Get an item with the given key, regenerating and setting it if not found. More...

	incr ($key, $value=1)
	Increase stored value of $key by $value while preserving its TTL. More...

	incrWithInit ($key, $ttl, $value=1, $init=1)
	Increase stored value of $key by $value while preserving its TTL. More...

	lock ($key, $timeout=6, $expiry=6, $rclass= '')
	Acquire an advisory lock on a key string. More...

	makeGlobalKey ()
	Make a global cache key. More...

	makeKey ()
	Make a cache key, scoped to this instance's keyspace. More...

	makeKeyInternal ($keyspace, $args)
	Construct a cache key. More...

	merge ($key, callable $callback, $exptime=0, $attempts=10, $flags=0)
	Merge changes into the existing cache value (possibly creating a new one) More...

	modifySimpleRelayEvent (array $event)
	Modify a cache update operation array for EventRelayer::notify() More...

	set ($key, $value, $exptime=0, $flags=0)
	Set an item. More...

	setDebug ($bool)

	setLogger (LoggerInterface $logger)

	setMulti (array $data, $exptime=0)
	Batch insertion. More...

	unlock ($key)
	Release an advisory lock on a key string. More...

Public Attributes
const	ERR_NO_RESPONSE = 1

const	ERR_NONE = 0
	Possible values for getLastError() More...

const	ERR_UNEXPECTED = 3

const	ERR_UNREACHABLE = 2

const	READ_LATEST = 1
	Bitfield constants for get()/getMulti() More...

const	READ_VERIFIED = 2

const	WRITE_CACHE_ONLY = 2

const	WRITE_SYNC = 1
	Bitfield constants for set()/merge() More...

Public Attributes inherited from IExpiringStore
const	TTL_DAY = 86400

const	TTL_HOUR = 3600

const	TTL_INDEFINITE = 0

const	TTL_MINUTE = 60

const	TTL_MONTH = 2592000

const	TTL_PROC_LONG = 30

const	TTL_PROC_SHORT = 3

const	TTL_WEEK = 604800

const	TTL_YEAR = 31536000

Protected Member Functions
	cas ($casToken, $key, $value, $exptime=0)
	Check and set an item. More...

	convertExpiry ($exptime)
	Convert an optionally relative time to an absolute time. More...

	convertToRelative ($exptime)
	Convert an optionally absolute expiry time to a relative time. More...

	debug ($text)

	doGet ($key, $flags=0)

	getWithToken ($key, &$casToken, $flags=0)

	isInteger ($value)
	Check if a value is an integer. More...

	mergeViaCas ($key, $callback, $exptime=0, $attempts=10)

	mergeViaLock ($key, $callback, $exptime=0, $attempts=10, $flags=0)

	setLastError ($err)
	Set the "last error" registry. More...

Protected Attributes
callback null	$asyncHandler

string	$keyspace = 'local'

integer	$lastError = self::ERR_NONE

array[]	$locks = []
	Lock tracking. More...

LoggerInterface	$logger

Private Member Functions
	trackDuplicateKeys ($key)
	Track the number of times that a given key has been used. More...

Private Attributes
bool	$debugMode = false

bool	$dupeTrackScheduled = false

array	$duplicateKeyLookups = []

bool	$reportDupes = false

Detailed Description

interface is intended to be more or less compatible with the PHP memcached client.

backends for local hash array and SQL table included:

$bag = new HashBagOStuff();

$bag = new SqlBagOStuff(); # connect to db first

Definition at line 45 of file BagOStuff.php.

Constructor & Destructor Documentation

BagOStuff::__construct ( array $params = [] )

$params include:

logger: Psr\Log\LoggerInterface instance
keyspace: Default keyspace for $this->makeKey()
asyncHandler: Callable to use for scheduling tasks after the web request ends. In CLI mode, it should run the task immediately.
reportDupes: Whether to emit warning log messages for all keys that were requested more than once (requires an asyncHandler).
Parameters

array $params

Definition at line 96 of file BagOStuff.php.

References $params, and setLogger().

Member Function Documentation

BagOStuff::add	(	$key,
		$value,
		$exptime = `0`
	)

Parameters

string	$key
mixed	$value
int	$exptime

Returns: bool Success

Definition at line 537 of file BagOStuff.php.

References $value, and set().

Referenced by incrWithInit(), lock(), and mergeViaCas().

BagOStuff::cas	(	$casToken,
		$key,
		$value,
		$exptime = `0`
	)

protected

Check and set an item.

Parameters

mixed	$casToken
string	$key
mixed	$value
int	$exptime	Either an interval in seconds or a unix timestamp for expiry

Returns: bool Success

Exceptions

Exception

Definition at line 327 of file BagOStuff.php.

Referenced by mergeViaCas().

BagOStuff::clearLastError ( )

Clear the "last error" registry.

Since: 1.23

Definition at line 615 of file BagOStuff.php.

Referenced by lock(), mergeViaCas(), and mergeViaLock().

BagOStuff::convertExpiry ( $exptime )

protected

Convert an optionally relative time to an absolute time.

Parameters

int $exptime

Returns: int

Definition at line 662 of file BagOStuff.php.

Referenced by SqlBagOStuff\cas(), HashBagOStuff\set(), and SqlBagOStuff\setMulti().

BagOStuff::convertToRelative ( $exptime )

protected

Convert an optionally absolute expiry time to a relative time.

If an absolute time is specified which is in the past, use a short expiry time.

Parameters

int $exptime

Returns: int

Definition at line 677 of file BagOStuff.php.

Referenced by RedisBagOStuff\add(), RedisBagOStuff\set(), and RedisBagOStuff\setMulti().

BagOStuff::debug ( $text )

protected

Parameters

string $text

Definition at line 649 of file BagOStuff.php.

Referenced by RedisBagOStuff\getMulti(), SqlBagOStuff\getMulti(), RedisBagOStuff\logRequest(), and RedisBagOStuff\setMulti().

BagOStuff::decr	(	$key,
		$value = `1`
	)

Decrease stored value of $key by $value while preserving its TTL.

Parameters

string	$key
int	$value

Returns: int|bool New value or false on failure

Definition at line 572 of file BagOStuff.php.

References $value, and incr().

BagOStuff::delete ( $key )

abstract

Delete an item.

Parameters

string $key

Returns: bool True if the item was deleted or not found, false on failure

BagOStuff::deleteObjectsExpiringBefore	(	$date,
		$progressCallback = `false`
	)

Delete all objects expiring before a certain date.

Parameters

string	$date	The reference date in MW format
callable \| bool	$progressCallback	Optional, a function which will be called regularly during long-running operations with the percentage progress as the first parameter.

Returns: bool Success, false if unimplemented

Definition at line 492 of file BagOStuff.php.

BagOStuff::doGet	(	$key,
		$flags = `0`
	)

abstractprotected

Parameters

string	$key
integer	$flags	Bitfield of BagOStuff::READ_* constants [optional]

Returns: mixed Returns false on failure and if the item does not exist

Referenced by get().

BagOStuff::get	(	$key,
		$flags = `0`,
		$oldFlags = `null`
	)

Get an item with the given key.

If the key includes a determistic input hash (e.g. the key can only have the correct value) or complete staleness checks are handled by the caller (e.g. nothing relies on the TTL), then the READ_VERIFIED flag should be set. This lets tiered backends know they can safely upgrade a cached value to higher tiers using standard TTLs.

Parameters

string	$key
integer	$flags	Bitfield of BagOStuff::READ_* constants [optional]
integer	$oldFlags	[unused]

Returns: mixed Returns false on failure and if the item does not exist

Definition at line 173 of file BagOStuff.php.

References $flags, doGet(), and trackDuplicateKeys().

Referenced by MediaWiki\Session\SessionBackend\__construct(), Title\newFromTextThrow(), and BagOStuffTest\testReportDupes().

BagOStuff::getLastError ( )

Get the "last error" registered; clearLastError() should be called manually.

Returns: int ERR_* constant for the "last error" registry

Since: 1.23

Definition at line 607 of file BagOStuff.php.

References $lastError.

Referenced by lock(), mergeViaCas(), and mergeViaLock().

BagOStuff::getMulti	(	array	$keys,
			$flags = `0`
	)

Get an associative array containing the item for each of the keys that have items.

Parameters

array	$keys	List of strings
integer	$flags	Bitfield; supports READ_LATEST [optional]

Returns: array

Definition at line 503 of file BagOStuff.php.

References $res, and as.

BagOStuff::getScopedLock	(	$key,
		$timeout = `6`,
		$expiry = `30`,
		$rclass = `''`
	)

final

Get a lightweight exclusive self-unlocking lock.

Note that the same lock cannot be acquired twice.

This is useful for task de-duplication or to avoid obtrusive (though non-corrupting) DB errors like INSERT key conflicts or deadlocks when using LOCK IN SHARE MODE.

Parameters

string	$key
int	$timeout	Lock wait timeout; 0 for non-blocking [optional]
int	$expiry	Lock expiry [optional]; 1 day maximum
string	$rclass	Allow reentry if set and the current lock used this value

Returns: ScopedCallback|null Returns null on failure

Since: 1.26

Definition at line 463 of file BagOStuff.php.

References lock(), unlock(), and use.

BagOStuff::getWithSetCallback	(	$key,
		$ttl,
		$callback,
		$flags = `0`
	)

final

Get an item with the given key, regenerating and setting it if not found.

If the callback returns false, then nothing is stored.

Parameters

string	$key
int	$ttl	Time-to-live (seconds)
callable	$callback	Callback that derives the new value
integer	$flags	Bitfield of BagOStuff::READ_* constants [optional]

Returns: mixed The cached value if found or the result of $callback otherwise

Since: 1.27

Definition at line 143 of file BagOStuff.php.

References $flags, $value, and set().

BagOStuff::getWithToken	(		$key,
		&	$casToken,
			$flags = `0`
	)

protected

Note: : This method is only needed if merge() uses mergeViaCas()

Parameters

string	$key
mixed	$casToken
integer	$flags	Bitfield of BagOStuff::READ_* constants [optional]

Returns: mixed Returns false on failure and if the item does not exist

Exceptions

Exception

Definition at line 231 of file BagOStuff.php.

Referenced by mergeViaCas().

BagOStuff::incr	(	$key,
		$value = `1`
	)

Increase stored value of $key by $value while preserving its TTL.

Parameters

string	$key	Key to increase
int	$value	Value to add to $key (Default 1)

Returns: int|bool New value or false on failure

Definition at line 550 of file BagOStuff.php.

References $value, isInteger(), lock(), set(), and unlock().

Referenced by decr(), and incrWithInit().

BagOStuff::incrWithInit	(	$key,
		$ttl,
		$value = `1`,
		$init = `1`
	)

Increase stored value of $key by $value while preserving its TTL.

This will create the key with value $init and TTL $ttl instead if not present

Parameters

string	$key
int	$ttl
int	$value
int	$init

Returns: int|bool New value or false on failure

Since: 1.24

Definition at line 588 of file BagOStuff.php.

References $value, add(), and incr().

BagOStuff::isInteger ( $value )

protected

Check if a value is an integer.

Parameters

mixed $value

Returns: bool

Definition at line 695 of file BagOStuff.php.

References $value.

Referenced by XCacheBagOStuff\doGet(), APCBagOStuff\doGet(), incr(), XCacheBagOStuff\set(), and APCBagOStuff\set().

BagOStuff::lock	(	$key,
		$timeout = `6`,
		$expiry = `6`,
		$rclass = `''`
	)

Acquire an advisory lock on a key string.

Note that if reentry is enabled, duplicate calls ignore $expiry

Parameters

string	$key
int	$timeout	Lock wait timeout; 0 for non-blocking [optional]
int	$expiry	Lock expiry [optional]; 1 day maximum
string	$rclass	Allow reentry if set and the current lock used this value

Returns: bool Success

Definition at line 383 of file BagOStuff.php.

References $sleep, $timestamp, add(), clearLastError(), and getLastError().

Referenced by getScopedLock(), incr(), and mergeViaLock().

BagOStuff::makeGlobalKey ( )

Make a global cache key.

Since: 1.27

Parameters

string ... Key component (variadic)

Returns: string

Definition at line 723 of file BagOStuff.php.

References makeKeyInternal().

Referenced by ChronologyProtector\__construct(), and BagOStuffTest\testMakeKey().

BagOStuff::makeKey ( )

Make a cache key, scoped to this instance's keyspace.

Since: 1.27

Parameters

string ... Key component (variadic)

Returns: string

Definition at line 734 of file BagOStuff.php.

References makeKeyInternal().

Referenced by BagOStuffTest\testMakeKey().

BagOStuff::makeKeyInternal	(	$keyspace,
		$args
	)

Construct a cache key.

Since: 1.27

Parameters

string	$keyspace
array	$args

Returns: string

Definition at line 707 of file BagOStuff.php.

References $args, $keyspace, and as.

Referenced by makeGlobalKey(), makeKey(), and BagOStuffTest\testMakeKey().

BagOStuff::merge	(		$key,
		callable	$callback,
			$exptime = `0`,
			$attempts = `10`,
			$flags = `0`
	)

Merge changes into the existing cache value (possibly creating a new one)

The callback function returns the new value given the current value (which will be false if not present), and takes the arguments: (this BagOStuff, cache key, current value, TTL). The TTL parameter is reference set to $exptime. It can be overriden in the callback.

Parameters

string	$key
callable	$callback	Callback method to be executed
int	$exptime	Either an interval in seconds or a unix timestamp for expiry
int	$attempts	The amount of times to attempt a merge in case of failure
int	$flags	Bitfield of BagOStuff::WRITE_* constants

Returns: bool Success

Exceptions

InvalidArgumentException

Definition at line 270 of file BagOStuff.php.

References $flags, and mergeViaLock().

BagOStuff::mergeViaCas	(	$key,
		$callback,
		$exptime = `0`,
		$attempts = `10`
	)

protected

See Also: BagOStuff::merge()

Parameters

string	$key
callable	$callback	Callback method to be executed
int	$exptime	Either an interval in seconds or a unix timestamp for expiry
int	$attempts	The amount of times to attempt a merge in case of failure

Returns: bool Success

Definition at line 283 of file BagOStuff.php.

References $reportDupes, $success, $value, add(), cas(), clearLastError(), getLastError(), and getWithToken().

Referenced by WinCacheBagOStuff\merge(), MemcachedBagOStuff\merge(), and SqlBagOStuff\merge().

BagOStuff::mergeViaLock	(	$key,
		$callback,
		$exptime = `0`,
		$attempts = `10`,
		$flags = `0`
	)

protected

See Also: BagOStuff::merge()

Parameters

string	$key
callable	$callback	Callback method to be executed
int	$exptime	Either an interval in seconds or a unix timestamp for expiry
int	$attempts	The amount of times to attempt a merge in case of failure
int	$flags	Bitfield of BagOStuff::WRITE_* constants

Returns: bool Success

Definition at line 341 of file BagOStuff.php.

References $flags, $reportDupes, $success, $value, clearLastError(), getLastError(), lock(), set(), and unlock().

Referenced by merge().

BagOStuff::modifySimpleRelayEvent ( array $event )

Modify a cache update operation array for EventRelayer::notify()

This is used for relayed writes, e.g. for broadcasting a change to multiple data-centers. If the array contains a 'val' field then the command involves setting a key to that value. Note that for simplicity, 'val' is always a simple scalar value. This method is used to possibly serialize the value and add any cache-specific key/values needed for the relayer daemon (e.g. memcached flags).

Parameters

array $event

Returns: array

Since: 1.26

Definition at line 642 of file BagOStuff.php.

BagOStuff::set	(	$key,
		$value,
		$exptime = `0`,
		$flags = `0`
	)

abstract

Set an item.

Parameters

string	$key
mixed	$value
int	$exptime	Either an interval in seconds or a unix timestamp for expiry
int	$flags	Bitfield of BagOStuff::WRITE_* constants

Returns: bool Success

Referenced by add(), getWithSetCallback(), incr(), mergeViaLock(), and setMulti().

BagOStuff::setDebug ( $bool )

Parameters

bool $bool

Definition at line 127 of file BagOStuff.php.

BagOStuff::setLastError ( $err )

protected

Set the "last error" registry.

Parameters

int $err ERR_* constant

Since: 1.23

Definition at line 624 of file BagOStuff.php.

Referenced by MemcachedPeclBagOStuff\checkResult(), RedisBagOStuff\getConnection(), RESTBagOStuff\handleError(), RedisBagOStuff\handleException(), SqlBagOStuff\handleReadError(), and SqlBagOStuff\handleWriteError().

BagOStuff::setLogger ( LoggerInterface $logger )

Parameters

LoggerInterface $logger

Returns: null

Definition at line 120 of file BagOStuff.php.

References $logger.

Referenced by __construct().

BagOStuff::setMulti	(	array	$data,
			$exptime = `0`
	)

Batch insertion.

Parameters

array	$data	$key => $value assoc array
int	$exptime	Either an interval in seconds or a unix timestamp for expiry

Returns: bool Success

Since: 1.24

Definition at line 521 of file BagOStuff.php.

References $res, $value, as, and set().

BagOStuff::trackDuplicateKeys ( $key )

private

Track the number of times that a given key has been used.

Parameters

string $key

Definition at line 186 of file BagOStuff.php.

References $count, and as.

Referenced by get().

BagOStuff::unlock ( $key )

Release an advisory lock on a key string.

Parameters

string $key

Returns: bool Success

Definition at line 437 of file BagOStuff.php.

Referenced by getScopedLock(), incr(), and mergeViaLock().

Member Data Documentation

callback null BagOStuff::$asyncHandler

protected

Definition at line 59 of file BagOStuff.php.

bool BagOStuff::$debugMode = false

private

Definition at line 62 of file BagOStuff.php.

bool BagOStuff::$dupeTrackScheduled = false

private

Definition at line 71 of file BagOStuff.php.

array BagOStuff::$duplicateKeyLookups = []

private

Definition at line 65 of file BagOStuff.php.

string BagOStuff::$keyspace = 'local'

protected

Definition at line 53 of file BagOStuff.php.

Referenced by MemcachedBagOStuff\makeKeyInternal(), and makeKeyInternal().

integer BagOStuff::$lastError = self::ERR_NONE

protected

Definition at line 50 of file BagOStuff.php.

Referenced by getLastError().

array [] BagOStuff::$locks = []

protected

Lock tracking.

Definition at line 47 of file BagOStuff.php.

LoggerInterface BagOStuff::$logger

protected

Definition at line 56 of file BagOStuff.php.

Referenced by MultiWriteBagOStuff\doWrite(), and setLogger().

bool BagOStuff::$reportDupes = false

private

Definition at line 68 of file BagOStuff.php.

Referenced by mergeViaCas(), and mergeViaLock().

const BagOStuff::ERR_NO_RESPONSE = 1

Definition at line 75 of file BagOStuff.php.

Referenced by WANObjectCache\getLastError().

const BagOStuff::ERR_NONE = 0

Possible values for getLastError()

Definition at line 74 of file BagOStuff.php.

Referenced by WANObjectCache\getLastError().

const BagOStuff::ERR_UNEXPECTED = 3

Definition at line 77 of file BagOStuff.php.

Referenced by MemcachedPeclBagOStuff\checkResult(), RedisBagOStuff\handleException(), SqlBagOStuff\handleReadError(), SqlBagOStuff\handleWriteError(), and RESTBagOStuffTest\testGetBadServer().

const BagOStuff::ERR_UNREACHABLE = 2

Definition at line 76 of file BagOStuff.php.

Referenced by RedisBagOStuff\getConnection(), WANObjectCache\getLastError(), SqlBagOStuff\handleReadError(), SqlBagOStuff\handleWriteError(), and RESTBagOStuffTest\testGetBadClient().

const BagOStuff::READ_LATEST = 1

Bitfield constants for get()/getMulti()

Definition at line 80 of file BagOStuff.php.

Referenced by SiteStatsUpdate\getPendingDeltas().

const BagOStuff::READ_VERIFIED = 2

Definition at line 81 of file BagOStuff.php.

Referenced by ParserCache\get(), and ParserCache\getKey().

const BagOStuff::WRITE_CACHE_ONLY = 2

Definition at line 84 of file BagOStuff.php.

Referenced by MediaWiki\Session\SessionBackend\save(), and CachedBagOStuffTest\testWriteCacheOnly().

const BagOStuff::WRITE_SYNC = 1

Bitfield constants for set()/merge()

Definition at line 83 of file BagOStuff.php.

Referenced by ChronologyProtector\shutdown(), and MultiWriteBagOStuffTest\testSyncMerge().

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

includes/libs/objectcache/BagOStuff.php

Public Member Functions

Public Attributes

Protected Member Functions

Protected Attributes

Private Member Functions

Private Attributes

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation