MediaWiki  1.27.2
WANObjectCache Class Reference

Multi-datacenter aware caching interface. More...

Inheritance diagram for WANObjectCache:
Collaboration diagram for WANObjectCache:

Public Member Functions

 __construct (array $params)
 
 clearLastError ()
 Clear the "last error" registry. More...
 
 clearProcessCache ()
 Clear the in-process caches; useful for testing. More...
 
 delete ($key, $ttl=self::HOLDOFF_TTL)
 Purge a key from all datacenters. More...
 
 get ($key, &$curTTL=null, array $checkKeys=[])
 Fetch the value of a key from cache. More...
 
 getCheckKeyTime ($key)
 Fetch the value of a timestamp "check" key. More...
 
 getLastError ()
 Get the "last error" registered; clearLastError() should be called manually. More...
 
 getMulti (array $keys, &$curTTLs=[], array $checkKeys=[])
 Fetch the value of several keys from cache. More...
 
 getWithSetCallback ($key, $ttl, $callback, array $opts=[])
 Method to fetch/regenerate cache keys. More...
 
 makeGlobalKey ()
 
 makeKey ()
 
 resetCheckKey ($key)
 Delete a "check" key from all datacenters, invalidating keys that use it. More...
 
 set ($key, $value, $ttl=0, array $opts=[])
 Set the value of a key in cache. More...
 
 setLogger (LoggerInterface $logger)
 
 touchCheckKey ($key, $holdoff=self::HOLDOFF_TTL)
 Purge a "check" key from all datacenters, invalidating keys that use it. More...
 

Static Public Member Functions

static newEmpty ()
 Get an instance that wraps EmptyBagOStuff. More...
 

Public Attributes

const CHECK_KEY_TTL = self::TTL_YEAR
 Seconds to keep dependency purge keys around. More...
 
const DEFAULT_PURGE_CHANNEL = 'wancache-purge'
 
const ERR_NO_RESPONSE = 1
 
const ERR_NONE = 0
 
const ERR_RELAY = 4
 
const ERR_UNEXPECTED = 3
 
const ERR_UNREACHABLE = 2
 
const FLD_FLAGS = 4
 
const FLD_HOLDOFF = 5
 
const FLD_TIME = 3
 
const FLD_TTL = 2
 
const FLD_VALUE = 1
 
const FLD_VERSION = 0
 
const HOLDOFF_NONE = 0
 Idiom for delete() for "no hold-off". More...
 
const HOLDOFF_TTL = 11
 Seconds to tombstone keys on delete() More...
 
const LOCK_TSE = 1
 Default time-since-expiry on a miss that makes a key "hot". More...
 
const LOCK_TTL = 10
 Seconds to keep lock keys around. More...
 
const LOW_TTL = 30
 Default remaining TTL at which to consider pre-emptive regeneration. More...
 
const MAX_COMMIT_DELAY = 3
 Max time expected to pass between delete() and DB commit finishing. More...
 
const MAX_PC_KEYS = 1000
 
const MAX_READ_LAG = 7
 Max replication+snapshot lag before applying TTL_LAGGED or disallowing set() More...
 
const PURGE_VAL_PREFIX = 'PURGED:'
 
const STASH_KEY_PREFIX = 'WANCache:s:'
 
const TIME_KEY_PREFIX = 'WANCache:t:'
 
const TINY_NEGATIVE = -0.000001
 Tiny negative float to use when CTL comes up >= 0 due to clock skew. More...
 
const TSE_NONE = -1
 Idiom for getWithSetCallback() callbacks to 'lockTSE' logic. More...
 
const TTL_LAGGED = 30
 Max TTL to store keys when a data sourced is lagged. More...
 
const TTL_UNCACHEABLE = -1
 Idiom for getWithSetCallback() callbacks to avoid calling set() More...
 
const VALUE_KEY_PREFIX = 'WANCache:v:'
 
const VERSION = 1
 Cache format version number. 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_WEEK = 604800
 
const TTL_YEAR = 31536000
 

Protected Member Functions

 doGetWithSetCallback ($key, $ttl, $callback, array $opts)
 Do the actual I/O for getWithSetCallback() when needed. More...
 
 makePurgeValue ($timestamp, $holdoff)
 
 relayDelete ($key)
 Do the actual async bus delete of a key. More...
 
 relayPurge ($key, $ttl, $holdoff)
 Do the actual async bus purge of a key. More...
 
 unwrap ($wrapped, $now)
 Do not use this method outside WANObjectCache. More...
 
 worthRefresh ($curTTL, $lowTTL)
 Check if a key should be regenerated (using random probability) More...
 
 wrap ($value, $ttl)
 Do not use this method outside WANObjectCache. More...
 

Static Protected Member Functions

static parsePurgeValue ($value)
 
static prefixCacheKeys (array $keys, $prefix)
 

Protected Attributes

BagOStuff $cache
 The local datacenter cache. More...
 
int $lastRelayError = self::ERR_NONE
 ERR_* constant for the "last error" registry. More...
 
LoggerInterface $logger
 
HashBagOStuff $procCache
 Script instance PHP cache. More...
 
string $purgeChannel
 Purge channel name. More...
 
EventRelayer $purgeRelayer
 Bus that handles purge broadcasts. More...
 

Private Member Functions

 processCheckKeys (array $timeKeys, array $wrappedValues, $now)
 

Detailed Description

Multi-datacenter aware caching interface.

All operations go to the local datacenter cache, except for delete(), touchCheckKey(), and resetCheckKey(), which broadcast to all datacenters.

This class is intended for caching data from primary stores. If the get() method does not return a value, then the caller should query the new value and backfill the cache using set(). When querying the store on cache miss, the closest DB replica should be used. Try to avoid heavyweight DB master or quorum reads. When the source data changes, a purge method should be called. Since purges are expensive, they should be avoided. One can do so if:

  • a) The object cached is immutable; or
  • b) Validity is checked against the source after get(); or
  • c) Using a modest TTL is reasonably correct and performant

The simplest purge method is delete().

Instances of this class must be configured to point to a valid PubSub endpoint, and there must be listeners on the cache servers that subscribe to the endpoint and update the caches.

Broadcasted operations like delete() and touchCheckKey() are done synchronously in the local datacenter, but are relayed asynchronously. This means that callers in other datacenters will see older values for however many milliseconds the datacenters are apart. As with any cache, this should not be relied on for cases where reads are used to determine writes to source (e.g. non-cache) data stores.

All values are wrapped in metadata arrays. Keys use a "WANCache:" prefix to avoid collisions with keys that are not wrapped as metadata arrays. The prefixes are as follows:

  • a) "WANCache:v" : used for regular value keys
  • b) "WANCache:s" : used for temporarily storing values of tombstoned keys
  • c) "WANCache:t" : used for storing timestamp "check" keys
Since
1.26

Definition at line 67 of file WANObjectCache.php.

Constructor & Destructor Documentation

WANObjectCache::__construct ( array  $params)
Parameters
array$params
  • cache : BagOStuff object for a persistent cache
  • channels : Map of (action => channel string). Actions include "purge".
  • relayers : Map of (action => EventRelayer object). Actions include "purge".
  • logger : LoggerInterface object

Definition at line 146 of file WANObjectCache.php.

References cache, and setLogger().

Member Function Documentation

WANObjectCache::clearLastError ( )
final

Clear the "last error" registry.

Definition at line 922 of file WANObjectCache.php.

References cache.

WANObjectCache::clearProcessCache ( )

Clear the in-process caches; useful for testing.

Since
1.27

Definition at line 932 of file WANObjectCache.php.

WANObjectCache::delete (   $key,
  $ttl = self::HOLDOFF_TTL 
)
final

Purge a key from all datacenters.

This should only be called when the underlying data (being cached) changes in a significant way. This deletes the key and starts a hold-off period where the key cannot be written to for a few seconds (HOLDOFF_TTL). This is done to avoid the following race condition:

  • a) Some DB data changes and delete() is called on a corresponding key
  • b) A request refills the key with a stale value from a lagged DB
  • c) The stale value is stuck there until the key is expired/evicted

This is implemented by storing a special "tombstone" value at the cache key that this class recognizes; get() calls will return false for the key and any set() calls will refuse to replace tombstone values at the key. For this to always avoid stale value writes, the following must hold:

  • a) Replication lag is bounded to being less than HOLDOFF_TTL; or
  • b) If lag is higher, the DB will have gone into read-only mode already

Note that set() can also be lag-aware and lower the TTL if it's high.

When using potentially long-running ACID transactions, a good pattern is to use a pre-commit hook to issue the delete. This means that immediately after commit, callers will see the tombstone in cache in the local datacenter and in the others upon relay. It also avoids the following race condition:

  • a) T1 begins, changes a row, and calls delete()
  • b) The HOLDOFF_TTL passes, expiring the delete() tombstone
  • c) T2 starts, reads the row and calls set() due to a cache miss
  • d) T1 finally commits
  • e) Stale value is stuck in cache

Example usage:

$dbw->begin( __METHOD__ ); // start of request
... <execute some stuff> ...
// Update the row in the DB
$dbw->update( ... );
$key = $cache->makeKey( 'homes', $homeId );
// Purge the corresponding cache entry just before committing
$dbw->onTransactionPreCommitOrIdle( function() use ( $cache, $key ) {
} );
... <execute some stuff> ...
$dbw->commit( __METHOD__ ); // end of request

The $ttl parameter can be used when purging values that have not actually changed recently. For example, a cleanup script to purge cache entries does not really need a hold-off period, so it can use HOLDOFF_NONE. Likewise for user-requested purge. Note that $ttl limits the effective range of 'lockTSE' for getWithSetCallback().

If called twice on the same key, then the last hold-off TTL takes precedence. For idempotence, the $ttl should not vary for different delete() calls on the same key.

Parameters
string$keyCache key
integer$ttlTombstone TTL; Default: WANObjectCache::HOLDOFF_TTL
Returns
bool True if the item was purged or not found, false on failure

Definition at line 484 of file WANObjectCache.php.

References $key, cache, makePurgeValue(), relayDelete(), and relayPurge().

Referenced by WANObjectCacheTest\testGetWithSetCallback().

WANObjectCache::doGetWithSetCallback (   $key,
  $ttl,
  $callback,
array  $opts 
)
protected

Do the actual I/O for getWithSetCallback() when needed.

See also
WANObjectCache::getWithSetCallback()
Parameters
string$key
integer$ttl
callback$callback
array$opts
Returns
mixed

Definition at line 800 of file WANObjectCache.php.

References $key, $value, cache, false, set(), and worthRefresh().

Referenced by getWithSetCallback().

WANObjectCache::get (   $key,
$curTTL = null,
array  $checkKeys = [] 
)
final

Fetch the value of a key from cache.

If supplied, $curTTL is set to the remaining TTL (current time left):

  • a) INF; if $key exists, has no TTL, and is not expired by $checkKeys
  • b) float (>=0); if $key exists, has a TTL, and is not expired by $checkKeys
  • c) float (<0); if $key is tombstoned, stale, or existing but expired by $checkKeys
  • d) null; if $key does not exist and is not tombstoned

If a key is tombstoned, $curTTL will reflect the time since delete().

The timestamp of $key will be checked against the last-purge timestamp of each of $checkKeys. Those $checkKeys not in cache will have the last-purge initialized to the current timestamp. If any of $checkKeys have a timestamp greater than that of $key, then $curTTL will reflect how long ago $key became invalid. Callers can use $curTTL to know when the value is stale. The $checkKeys parameter allow mass invalidations by updating a single key:

  • a) Each "check" key represents "last purged" of some source data
  • b) Callers pass in relevant "check" keys as $checkKeys in get()
  • c) When the source data that "check" keys represent changes, the touchCheckKey() method is called on them

Source data entities might exists in a DB that uses snapshot isolation (e.g. the default REPEATABLE-READ in innoDB). Even for mutable data, that isolation can largely be maintained by doing the following:

  • a) Calling delete() on entity change and creation, before DB commit
  • b) Keeping transaction duration shorter than delete() hold-off TTL

However, pre-snapshot values might still be seen if an update was made in a remote datacenter but the purge from delete() didn't relay yet.

Consider using getWithSetCallback() instead of get() and set() cycles. That method has cache slam avoiding features for hot/expensive keys.

Parameters
string$keyCache key
mixed$curTTLApproximate TTL left on the key if present [returned]
array$checkKeysList of "check" keys
Returns
mixed Value of cache key or false on failure

Definition at line 214 of file WANObjectCache.php.

References $key, and getMulti().

Referenced by JobQueueDB\doDeduplicateRootJob(), WANObjectCacheTest\testCheckKeyInitHoldoff(), WANObjectCacheTest\testGetWithSetCallback(), and WANObjectCacheTest\testLockTSESlow().

WANObjectCache::getCheckKeyTime (   $key)
final

Fetch the value of a timestamp "check" key.

The key will be initialized to the current time if not set, so only call this method if this behavior is actually desired

The timestamp can be used to check whether a cached value is valid. Callers should not assume that this returns the same timestamp in all datacenters due to relay delays.

The level of staleness can roughly be estimated from this key, but if the key was evicted from cache, such calculations may show the time since expiry as ~0 seconds.

Note that "check" keys won't collide with other regular keys.

Parameters
string$key
Returns
float UNIX timestamp of the check key

Definition at line 524 of file WANObjectCache.php.

References $key, $time, cache, makePurgeValue(), and string.

Referenced by WANObjectCacheTest\testGetMulti(), and WANObjectCacheTest\testGetWithSetCallback().

WANObjectCache::getLastError ( )
final

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

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

Definition at line 896 of file WANObjectCache.php.

References $code, $lastRelayError, cache, BagOStuff\ERR_NO_RESPONSE, BagOStuff\ERR_NONE, and BagOStuff\ERR_UNREACHABLE.

WANObjectCache::getMulti ( array  $keys,
$curTTLs = [],
array  $checkKeys = [] 
)
final

Fetch the value of several keys from cache.

See also
WANObjectCache::get()
Parameters
array$keysList of cache keys
array$curTTLsMap of (key => approximate TTL left) for existing keys [returned]
array$checkKeysList of check keys to apply to all $keys. May also apply "check" keys to specific cache keys only by using cache keys as keys in the $checkKeys array.
Returns
array Map of (key => value) for keys that exist

Definition at line 233 of file WANObjectCache.php.

References $key, $value, array(), as, cache, list, processCheckKeys(), and unwrap().

Referenced by get(), WANObjectCacheTest\testGetMulti(), and WANObjectCacheTest\testGetMultiCheckKeys().

WANObjectCache::getWithSetCallback (   $key,
  $ttl,
  $callback,
array  $opts = [] 
)
final

Method to fetch/regenerate cache keys.

On cache miss, the key will be set to the callback result via set() (unless the callback returns false) and that result will be returned. The arguments supplied to the callback are:

  • $oldValue : current cache value or false if not present
  • &$ttl : a reference to the TTL which can be altered
  • &$setOpts : a reference to options for set() which can be altered

It is strongly recommended to set the 'lag' and 'since' fields to avoid race conditions that can cause stale values to get stuck at keys. Usually, callbacks ignore the current value, but it can be used to maintain "most recent X" values that come from time or sequence based source data, provided that the "as of" id/time is tracked. Note that preemptive regeneration and $checkKeys can result in a non-false current value.

Usage of $checkKeys is similar to get() and getMulti(). However, rather than the caller having to inspect a "current time left" variable (e.g. $curTTL, $curTTLs), a cache regeneration will automatically be triggered using the callback.

The simplest way to avoid stampedes for hot keys is to use the 'lockTSE' option in $opts. If cache purges are needed, also:

  • a) Pass $key into $checkKeys
  • b) Use touchCheckKey( $key ) instead of delete( $key )

Example usage (typical key):

// Key to store the cached value under
$cache->makeKey( 'cat-attributes', $catId ),
// Time-to-live (in seconds)
$cache::TTL_MINUTE,
// Function that derives the new key value
function ( $oldValue, &$ttl, array &$setOpts ) {
// Account for any snapshot/slave lag
return $dbr->selectRow( ... );
}
);

Example usage (key that is expensive and hot):

$catConfig = $cache->getWithSetCallback(
// Key to store the cached value under
$cache->makeKey( 'site-cat-config' ),
// Time-to-live (in seconds)
$cache::TTL_DAY,
// Function that derives the new key value
function ( $oldValue, &$ttl, array &$setOpts ) {
// Account for any snapshot/slave lag
return CatConfig::newFromRow( $dbr->selectRow( ... ) );
},
[
// Calling touchCheckKey() on this key invalidates the cache
'checkKeys' => [ $cache->makeKey( 'site-cat-config' ) ],
// Try to only let one datacenter thread manage cache updates at a time
'lockTSE' => 30
]
);

Example usage (key with dynamic dependencies):

// Key to store the cached value under
$cache->makeKey( 'cat-state', $cat->getId() ),
// Time-to-live (seconds)
$cache::TTL_HOUR,
// Function that derives the new key value
function ( $oldValue, &$ttl, array &$setOpts ) {
// Determine new value from the DB
// Account for any snapshot/slave lag
return CatState::newFromResults( $dbr->select( ... ) );
},
[
// The "check" keys that represent things the value depends on;
// Calling touchCheckKey() on any of them invalidates the cache
'checkKeys' => [
$cache->makeKey( 'sustenance-bowls', $cat->getRoomId() ),
$cache->makeKey( 'people-present', $cat->getHouseId() ),
$cache->makeKey( 'cat-laws', $cat->getCityId() ),
]
]
);

Example usage (hot key holding most recent 100 events):

$lastCatActions = $cache->getWithSetCallback(
// Key to store the cached value under
$cache->makeKey( 'cat-last-actions', 100 ),
// Time-to-live (in seconds)
10,
// Function that derives the new key value
function ( $oldValue, &$ttl, array &$setOpts ) {
// Account for any snapshot/slave lag
// Start off with the last cached list
$list = $oldValue ?: [];
// Fetch the last 100 relevant rows in descending order;
// only fetch rows newer than $list[0] to reduce scanning
$rows = iterator_to_array( $dbr->select( ... ) );
// Merge them and get the new "last 100" rows
return array_slice( array_merge( $new, $list ), 0, 100 );
},
// Try to only let one datacenter thread manage cache updates at a time
[ 'lockTSE' => 30 ]
);
See also
WANObjectCache::get()
WANObjectCache::set()
Parameters
string$keyCache key
integer$ttlSeconds to live for key updates. Special values are:
callable$callbackValue generation function
array$optsOptions map:
  • checkKeys: List of "check" keys. The key at $key will be seen as invalid when either touchCheckKey() or resetCheckKey() is called on any of these keys.
  • lowTTL: Consider pre-emptive updates when the current TTL (sec) of the key is less than this. It becomes more likely over time, becoming a certainty once the key is expired. Default: WANObjectCache::LOW_TTL seconds.
  • lockTSE: If the key is tombstoned or expired (by checkKeys) less than this many seconds ago, then try to have a single thread handle cache regeneration at any given time. Other threads will try to use stale values if possible. If, on miss, the time since expiration is low, the assumption is that the key is hot and that a stampede is worth avoiding. Setting this above WANObjectCache::HOLDOFF_TTL makes no difference. The higher this is set, the higher the worst-case staleness can be. Use WANObjectCache::TSE_NONE to disable this logic. Default: WANObjectCache::TSE_NONE.
  • pcTTL : process cache the value in this PHP instance with this TTL. This avoids network I/O when a key is read several times. This will not cache if the callback returns false however. Note that any purges will not be seen while process cached; since the callback should use slave DBs and they may be lagged or have snapshot isolation anyway, this should not typically matter. Default: WANObjectCache::TTL_UNCACHEABLE.
Returns
mixed Value to use for the key

Definition at line 771 of file WANObjectCache.php.

References $key, $value, and doGetWithSetCallback().

Referenced by WANObjectCacheTest\testGetWithSetCallback(), WANObjectCacheTest\testLockTSE(), and WANObjectCacheTest\testLockTSESlow().

WANObjectCache::makeGlobalKey ( )
See also
BagOStuff::makeGlobalKey()
Parameters
string... Key component
Returns
string
Since
1.27

Definition at line 888 of file WANObjectCache.php.

References cache.

Referenced by User\getCacheKey().

WANObjectCache::makeKey ( )
See also
BagOStuff::makeKey()
Parameters
string... Key component
Returns
string
Since
1.27

Definition at line 878 of file WANObjectCache.php.

References cache.

WANObjectCache::makePurgeValue (   $timestamp,
  $holdoff 
)
protected
Parameters
float$timestamp
int$holdoffIn seconds
Returns
string Wrapped purge value

Definition at line 1107 of file WANObjectCache.php.

References $timestamp.

Referenced by delete(), getCheckKeyTime(), processCheckKeys(), and touchCheckKey().

static WANObjectCache::newEmpty ( )
static

Get an instance that wraps EmptyBagOStuff.

Returns
WANObjectCache

Definition at line 167 of file WANObjectCache.php.

Referenced by FileBackendStore\__construct().

static WANObjectCache::parsePurgeValue (   $value)
staticprotected
Parameters
string$valueWrapped value like "PURGED:<timestamp>:<holdoff>"
Returns
array|bool Array containing a UNIX timestamp (float) and holdoff period (integer), or false if value isn't a valid purge value

Definition at line 1082 of file WANObjectCache.php.

References $value.

static WANObjectCache::prefixCacheKeys ( array  $keys,
  $prefix 
)
staticprotected
Parameters
array$keys
string$prefix
Returns
string[]

Definition at line 1068 of file WANObjectCache.php.

References $key, $res, and as.

WANObjectCache::processCheckKeys ( array  $timeKeys,
array  $wrappedValues,
  $now 
)
private
Since
1.27
Parameters
array$timeKeysList of prefixed time check keys
array$wrappedValues
float$now
Returns
array List of purge value arrays

Definition at line 312 of file WANObjectCache.php.

References as, cache, and makePurgeValue().

Referenced by getMulti().

WANObjectCache::relayDelete (   $key)
protected

Do the actual async bus delete of a key.

Parameters
string$keyCache key
Returns
bool Success

Definition at line 969 of file WANObjectCache.php.

References $key, and cache.

Referenced by delete(), and resetCheckKey().

WANObjectCache::relayPurge (   $key,
  $ttl,
  $holdoff 
)
protected

Do the actual async bus purge of a key.

This must set the key to "PURGED:<UNIX timestamp>:<holdoff>"

Parameters
string$keyCache key
integer$ttlHow long to keep the tombstone [seconds]
integer$holdoffHOLDOFF_* constant controlling how long to ignore sets for this key
Returns
bool Success

Definition at line 946 of file WANObjectCache.php.

References $key, and cache.

Referenced by delete(), and touchCheckKey().

WANObjectCache::resetCheckKey (   $key)
final

Delete a "check" key from all datacenters, invalidating keys that use it.

This is similar to touchCheckKey() in that keys using it via get(), getMulti(), or getWithSetCallback() will be invalidated. The differences are:

  • a) The timestamp will be deleted from all caches and lazily re-initialized when accessed (rather than set everywhere)
  • b) Thus, dependent keys will be known to be invalid, but not for how long (they are treated as "just" purged), which effects any lockTSE logic in getWithSetCallback()

The advantage is that this does not place high TTL keys on every cache server, making it better for code that will cache many different keys and either does not use lockTSE or uses a low enough TTL anyway.

This is typically useful for keys with dynamically generated names where a high number of combinations exist.

Note that "check" keys won't collide with other regular keys.

See also
WANObjectCache::get()
WANObjectCache::getWithSetCallback()
WANObjectCache::touchCheckKey()
Parameters
string$keyCache key
Returns
bool True if the item was purged or not found, false on failure

Definition at line 612 of file WANObjectCache.php.

References $key, cache, and relayDelete().

WANObjectCache::set (   $key,
  $value,
  $ttl = 0,
array  $opts = [] 
)
final

Set the value of a key in cache.

Simply calling this method when source data changes is not valid because the changes do not replicate to the other WAN sites. In that case, delete() should be used instead. This method is intended for use on cache misses.

If the data was read from a snapshot-isolated transactions (e.g. the default REPEATABLE-READ in innoDB), use 'since' to avoid the following race condition:

  • a) T1 starts
  • b) T2 updates a row, calls delete(), and commits
  • c) The HOLDOFF_TTL passes, expiring the delete() tombstone
  • d) T1 reads the row and calls set() due to a cache miss
  • e) Stale value is stuck in cache

Setting 'lag' and 'since' help avoids keys getting stuck in stale states.

Example usage:

// Fetch the row from the DB
$row = $dbr->selectRow( ... );
$key = $cache->makeKey( 'building', $buildingId );
$cache->set( $key, $row, $cache::TTL_DAY, $setOpts );
Parameters
string$keyCache key
mixed$value
integer$ttlSeconds to live. Special values are:
array$optsOptions map:
  • lag : Seconds of slave lag. Typically, this is either the slave lag before the data was read or, if applicable, the slave lag before the snapshot-isolated transaction the data was read from started. Default: 0 seconds
  • since : UNIX timestamp of the data in $value. Typically, this is either the current time the data was read or (if applicable) the time when the snapshot-isolated transaction the data was read from started. Default: 0 seconds
  • pending : Whether this data is possibly from an uncommitted write transaction. Generally, other threads should not see values from the future and they certainly should not see ones that ended up getting rolled back. Default: false
  • lockTSE : if excessive replication/snapshot lag is detected, then store the value with this TTL and flag it as stale. This is only useful if the reads for this key use getWithSetCallback() with "lockTSE" set. Default: WANObjectCache::TSE_NONE
Returns
bool Success

Definition at line 379 of file WANObjectCache.php.

References $cache, $key, $value, cache, use, and wrap().

Referenced by JobQueueDB\doDeduplicateRootJob(), doGetWithSetCallback(), WANObjectCacheTest\testCheckKeyInitHoldoff(), WANObjectCacheTest\testGetMulti(), and WANObjectCacheTest\testGetMultiCheckKeys().

WANObjectCache::setLogger ( LoggerInterface  $logger)

Definition at line 158 of file WANObjectCache.php.

References $logger.

Referenced by __construct().

WANObjectCache::touchCheckKey (   $key,
  $holdoff = self::HOLDOFF_TTL 
)
final

Purge a "check" key from all datacenters, invalidating keys that use it.

This should only be called when the underlying data (being cached) changes in a significant way, and it is impractical to call delete() on all keys that should be changed. When get() is called on those keys, the relevant "check" keys must be supplied for this to work.

The "check" key essentially represents a last-modified field. When touched, keys using it via get(), getMulti(), or getWithSetCallback() will be invalidated. It is treated as being HOLDOFF_TTL seconds in the future by those methods to avoid race conditions where dependent keys get updated with stale values (e.g. from a DB slave).

This is typically useful for keys with hardcoded names or in some cases dynamically generated names where a low number of combinations exist. When a few important keys get a large number of hits, a high cache time is usually desired as well as "lockTSE" logic. The resetCheckKey() method is less appropriate in such cases since the "time since expiry" cannot be inferred.

Note that "check" keys won't collide with other regular keys.

See also
WANObjectCache::get()
WANObjectCache::getWithSetCallback()
WANObjectCache::resetCheckKey()
Parameters
string$keyCache key
int$holdoffHOLDOFF_TTL or HOLDOFF_NONE constant
Returns
bool True if the item was purged or not found, false on failure

Definition at line 574 of file WANObjectCache.php.

References $key, cache, makePurgeValue(), and relayPurge().

Referenced by WANObjectCacheTest\testGetMultiCheckKeys().

WANObjectCache::unwrap (   $wrapped,
  $now 
)
protected

Do not use this method outside WANObjectCache.

Parameters
array | string | bool$wrapped
float$nowUnix Current timestamp (preferrable pre-query)
Returns
array (mixed; false if absent/invalid, current time left)

Definition at line 1030 of file WANObjectCache.php.

References $flags.

Referenced by getMulti().

WANObjectCache::worthRefresh (   $curTTL,
  $lowTTL 
)
protected

Check if a key should be regenerated (using random probability)

This returns false if $curTTL >= $lowTTL. Otherwise, the chance of returning true increases steadily from 0% to 100% as the $curTTL moves from $lowTTL to 0 seconds. This handles widely varying levels of cache access traffic.

Parameters
float$curTTLApproximate TTL left on the key if present
float$lowTTLConsider a refresh when $curTTL is less than this
Returns
bool

Definition at line 995 of file WANObjectCache.php.

Referenced by doGetWithSetCallback().

WANObjectCache::wrap (   $value,
  $ttl 
)
protected

Do not use this method outside WANObjectCache.

Parameters
mixed$value
integer$ttl[0=forever]
Returns
array

Definition at line 1014 of file WANObjectCache.php.

References $value.

Referenced by set().

Member Data Documentation

BagOStuff WANObjectCache::$cache
protected

The local datacenter cache.

Definition at line 69 of file WANObjectCache.php.

Referenced by set().

int WANObjectCache::$lastRelayError = self::ERR_NONE
protected

ERR_* constant for the "last error" registry.

Definition at line 80 of file WANObjectCache.php.

Referenced by getLastError().

LoggerInterface WANObjectCache::$logger
protected

Definition at line 77 of file WANObjectCache.php.

Referenced by setLogger().

HashBagOStuff WANObjectCache::$procCache
protected

Script instance PHP cache.

Definition at line 71 of file WANObjectCache.php.

string WANObjectCache::$purgeChannel
protected

Purge channel name.

Definition at line 73 of file WANObjectCache.php.

EventRelayer WANObjectCache::$purgeRelayer
protected

Bus that handles purge broadcasts.

Definition at line 75 of file WANObjectCache.php.

const WANObjectCache::CHECK_KEY_TTL = self::TTL_YEAR

Seconds to keep dependency purge keys around.

Definition at line 90 of file WANObjectCache.php.

const WANObjectCache::DEFAULT_PURGE_CHANNEL = 'wancache-purge'

Definition at line 137 of file WANObjectCache.php.

const WANObjectCache::ERR_NO_RESPONSE = 1

Definition at line 124 of file WANObjectCache.php.

const WANObjectCache::ERR_NONE = 0

Definition at line 123 of file WANObjectCache.php.

const WANObjectCache::ERR_RELAY = 4

Definition at line 127 of file WANObjectCache.php.

const WANObjectCache::ERR_UNEXPECTED = 3

Definition at line 126 of file WANObjectCache.php.

const WANObjectCache::ERR_UNREACHABLE = 2

Definition at line 125 of file WANObjectCache.php.

const WANObjectCache::FLD_FLAGS = 4

Definition at line 117 of file WANObjectCache.php.

const WANObjectCache::FLD_HOLDOFF = 5

Definition at line 118 of file WANObjectCache.php.

const WANObjectCache::FLD_TIME = 3

Definition at line 116 of file WANObjectCache.php.

const WANObjectCache::FLD_TTL = 2

Definition at line 115 of file WANObjectCache.php.

const WANObjectCache::FLD_VALUE = 1

Definition at line 114 of file WANObjectCache.php.

const WANObjectCache::FLD_VERSION = 0

Definition at line 113 of file WANObjectCache.php.

const WANObjectCache::HOLDOFF_NONE = 0

Idiom for delete() for "no hold-off".

Definition at line 105 of file WANObjectCache.php.

Referenced by WANObjectCacheTest\testDelete(), and WANObjectCacheTest\testGetMultiCheckKeys().

const WANObjectCache::HOLDOFF_TTL = 11

Seconds to tombstone keys on delete()

Definition at line 87 of file WANObjectCache.php.

Referenced by MessageCache\getValidationHash().

const WANObjectCache::LOCK_TSE = 1

Default time-since-expiry on a miss that makes a key "hot".

Definition at line 96 of file WANObjectCache.php.

const WANObjectCache::LOCK_TTL = 10

Seconds to keep lock keys around.

Definition at line 92 of file WANObjectCache.php.

const WANObjectCache::LOW_TTL = 30

Default remaining TTL at which to consider pre-emptive regeneration.

Definition at line 94 of file WANObjectCache.php.

const WANObjectCache::MAX_COMMIT_DELAY = 3

Max time expected to pass between delete() and DB commit finishing.

Definition at line 83 of file WANObjectCache.php.

const WANObjectCache::MAX_PC_KEYS = 1000

Definition at line 135 of file WANObjectCache.php.

const WANObjectCache::MAX_READ_LAG = 7

Max replication+snapshot lag before applying TTL_LAGGED or disallowing set()

Definition at line 85 of file WANObjectCache.php.

const WANObjectCache::PURGE_VAL_PREFIX = 'PURGED:'
const WANObjectCache::STASH_KEY_PREFIX = 'WANCache:s:'

Definition at line 130 of file WANObjectCache.php.

const WANObjectCache::TIME_KEY_PREFIX = 'WANCache:t:'

Definition at line 131 of file WANObjectCache.php.

Referenced by WANObjectCacheTest\testGetWithSeveralCheckKeys().

const WANObjectCache::TINY_NEGATIVE = -0.000001

Tiny negative float to use when CTL comes up >= 0 due to clock skew.

Definition at line 108 of file WANObjectCache.php.

const WANObjectCache::TSE_NONE = -1

Idiom for getWithSetCallback() callbacks to 'lockTSE' logic.

Definition at line 101 of file WANObjectCache.php.

const WANObjectCache::TTL_LAGGED = 30

Max TTL to store keys when a data sourced is lagged.

Definition at line 103 of file WANObjectCache.php.

const WANObjectCache::TTL_UNCACHEABLE = -1

Idiom for getWithSetCallback() callbacks to avoid calling set()

Definition at line 99 of file WANObjectCache.php.

Referenced by ForeignDBFile\getDescriptionText(), File\getDescriptionText(), and ApiMain\makeHelpMsg().

const WANObjectCache::VALUE_KEY_PREFIX = 'WANCache:v:'

Definition at line 129 of file WANObjectCache.php.

const WANObjectCache::VERSION = 1

Cache format version number.

Definition at line 111 of file WANObjectCache.php.


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