MediaWiki master
|
Multi-datacenter aware caching interface. More...
Inherits Wikimedia\LightweightObjectStore\ExpirationAwareness, Wikimedia\LightweightObjectStore\StorageAwareness, Wikimedia\ObjectCache\IStoreKeyEncoder, and LoggerAwareInterface.
Public Member Functions | |
__construct (array $params) | |
adaptiveTTL ( $mtime, $maxTTL, $minTTL=30, $factor=0.2) | |
Get a TTL that is higher for objects that have not changed recently. | |
clearLastError () | |
Clear the "last error" registry. | |
clearProcessCache () | |
Clear the in-process caches; useful for testing. | |
delete ( $key, $ttl=self::HOLDOFF_TTL) | |
Purge a key from all datacenters. | |
get ( $key, &$curTTL=null, array $checkKeys=[], &$info=[]) | |
Fetch the value of a key from cache. | |
getCheckKeyTime ( $key) | |
Fetch the value of a timestamp "check" key. | |
getLastError ( $watchPoint=0) | |
Get the "last error" registry. | |
getMulti (array $keys, &$curTTLs=[], array $checkKeys=[], &$info=[]) | |
Fetch the value of several keys from cache. | |
getMultiCheckKeyTime (array $keys) | |
Fetch the values of each timestamp "check" key. | |
getMultiWithSetCallback (ArrayIterator $keyedIds, $ttl, callable $callback, array $opts=[]) | |
Method to fetch multiple cache keys at once with regeneration. | |
getMultiWithUnionSetCallback (ArrayIterator $keyedIds, $ttl, callable $callback, array $opts=[]) | |
Method to fetch/regenerate multiple cache keys at once. | |
getQoS ( $flag) | |
getWarmupKeyMisses () | |
getWithSetCallback ( $key, $ttl, $callback, array $opts=[], array $cbParams=[]) | |
Method to fetch/regenerate a cache key. | |
hash256 ( $component) | |
Hash a possibly long string into a suitable component for makeKey()/makeGlobalKey() | |
makeGlobalKey ( $keygroup,... $components) | |
makeKey ( $keygroup,... $components) | |
makeMultiKeys (array $ids, $keyCallback) | |
Get an iterator of (cache key => entity ID) for a list of entity IDs. | |
multiRemap (array $ids, array $res) | |
Get an (ID => value) map from (i) a non-unique list of entity IDs, and (ii) the list of corresponding entity values by first appearance of each ID in the entity ID list. | |
resetCheckKey ( $key) | |
Clear the last-purge timestamp of a "check" key in all datacenters. | |
set ( $key, $value, $ttl=self::TTL_INDEFINITE, array $opts=[]) | |
Set the value of a key in cache. | |
setLogger (LoggerInterface $logger) | |
setMockTime (&$time) | |
touchCheckKey ( $key, $holdoff=self::HOLDOFF_TTL) | |
Increase the last-purge timestamp of a "check" key in all datacenters. | |
useInterimHoldOffCaching ( $enabled) | |
Enable or disable the use of brief caching for tombstoned keys. | |
watchErrors () | |
Get a "watch point" token that can be used to get the "last error" to occur after now. | |
Static Public Member Functions | |
static | newEmpty () |
Get an instance that wraps EmptyBagOStuff. | |
Public Attributes | |
const | GRACE_TTL_NONE = 0 |
Idiom for set()/getWithSetCallback() meaning "no post-expiration grace period". | |
const | HOLDOFF_TTL = self::MAX_COMMIT_DELAY + self::MAX_READ_LAG + 1 |
Seconds to tombstone keys on delete() and to treat keys as volatile after purges. | |
const | HOLDOFF_TTL_NONE = 0 |
Idiom for delete()/touchCheckKey() meaning "no hold-off period". | |
const | KEY_AS_OF = 'asOf' |
Generation completion timestamp attribute for a key; keep value for b/c (< 1.36) | |
const | KEY_CHECK_AS_OF = 'lastCKPurge' |
Highest "check" key timestamp for a key; keep value for b/c (< 1.36) | |
const | KEY_CUR_TTL = 'curTTL' |
Remaining TTL attribute for a key; keep value for b/c (< 1.36) | |
const | KEY_TOMB_AS_OF = 'tombAsOf' |
Tomstone timestamp attribute for a key; keep value for b/c (< 1.36) | |
const | KEY_TTL = 'ttl' |
Logical TTL attribute for a key. | |
const | KEY_VERSION = 'version' |
Version number attribute for a key; keep value for b/c (< 1.36) | |
const | PASS_BY_REF = [] |
Idiom for get()/getMulti() to return extra information by reference. | |
const | STALE_TTL_NONE = 0 |
Idiom for set()/getWithSetCallback() meaning "no post-expiration persistence". | |
const | TTL_LAGGED = 30 |
Max TTL, in seconds, to store keys when a data source has high replication lag. | |
Public Attributes inherited from Wikimedia\LightweightObjectStore\StorageAwareness | |
const | ATTR_DURABILITY = 2 |
Durability of writes; see QOS_DURABILITY_* (higher means stronger) | |
const | ATTR_EMULATION = 1 |
const | ERR_NO_RESPONSE = 1 |
Storage medium failed to yield a complete response to an operation. | |
const | ERR_NONE = 0 |
No storage medium error. | |
const | ERR_UNEXPECTED = 3 |
Storage medium operation failed due to usage limitations or an I/O error. | |
const | ERR_UNREACHABLE = 2 |
Storage medium could not be reached to establish a connection. | |
const | QOS_DURABILITY_DISK = 4 |
Data is saved to disk and writes do not usually block on fsync() | |
const | QOS_DURABILITY_NONE = 1 |
Data is never saved to begin with (blackhole store) | |
const | QOS_DURABILITY_RDBMS = 5 |
Data is saved to disk and writes usually block on fsync(), like a standard RDBMS. | |
const | QOS_DURABILITY_SCRIPT = 2 |
Data is lost at the end of the current web request or CLI script. | |
const | QOS_DURABILITY_SERVICE = 3 |
Data is lost once the service storing the data restarts. | |
const | QOS_UNKNOWN = INF |
Generic "unknown" value; useful for comparisons (always "good enough") | |
Protected Member Functions | |
fetchKeys (array $keys, array $checkKeys, float $now, $touchedCb=null) | |
Fetch the value and key metadata of several keys from cache. | |
getCurrentTime () | |
isLotteryRefreshDue ( $res, $lowTTL, $ageNew, $hotTTR, $now) | |
Check if a key is due for randomized regeneration due to near-expiration/popularity. | |
isValid ( $value, $asOf, $minAsOf) | |
Check that a wrapper value exists and has an acceptable age. | |
prependRoute (string $sisterKey, string $route) | |
relayNonVolatilePurge (string $sisterKey) | |
Remove a sister key from all datacenters. | |
relayVolatilePurge (string $sisterKey, string $purgeValue, int $ttl) | |
Set a sister key to a purge value in all datacenters. | |
worthRefreshExpiring ( $curTTL, $logicalTTL, $lowTTL) | |
Check if a key is nearing expiration and thus due for randomized regeneration. | |
worthRefreshPopular ( $asOf, $ageNew, $timeTillRefresh, $now) | |
Check if a key is due for randomized regeneration due to its popularity. | |
Protected Attributes | |
callable null | $asyncHandler |
Function that takes a WAN cache callback and runs it later. | |
string null | $broadcastRoute |
Routing prefix for operations that should be broadcasted to all data centers. | |
BagOStuff | $cache |
The local datacenter cache. | |
int | $coalesceScheme |
Scheme to use for key coalescing (Hash Tags or Hash Stops) | |
float | $epoch |
Unix timestamp of the oldest possible valid values. | |
LoggerInterface | $logger |
MapCacheLRU[] | $processCaches = [] |
Map of group PHP instance caches. | |
string | $secret |
Stable secret used for hashing long strings into key components. | |
StatsFactory | $stats |
bool | $useInterimHoldOffCaching = true |
Whether to use "interim" caching while keys are tombstoned. | |
Multi-datacenter aware caching interface.
WANObjectCache (known as WANCache, pronounced whan-cache) improves performance by reducing database load, increasing web server capacity (fewer repeated computations) and providing faster access to data. The data cached here follows a "cache-aside" strategy, with data potentially derived from database rows. Generally speaking, cache data should be treated as equally up-to-date to data from a replica database, and is thus essentially subject to the same replication lag.
The primary way to interact with this class is via the getWithSetCallback() method.
Each data center has its own cache cluster, with web servers in a given datacenter populating and reading from the local datacenter only. The exceptions are methods delete(), touchCheckKey(), and resetCheckKey(), which also asynchronously broadcast the equivalent purge to other datacenters.
To learn how this is used and configured at Wikimedia Foundation, refer to https://wikitech.wikimedia.org/wiki/Memcached_for_MediaWiki.
For broader guidance on how to approach caching in MediaWiki at scale, refer to https://wikitech.wikimedia.org/wiki/MediaWiki_Engineering/Guides/Backend_performance_practices.
For your code to "see" new values in a timely manner, you need to follow either the validation strategy, or the purge strategy.
The validation strategy refers to the natural avoidance of stale data by one of the following means:
A) The cached value is immutable.
If you can obtain all the information needed to uniquely describe the value, then the value never has to change or be purged. Instead, the key changes, which naturally creates a miss where you can compute the right value. For example, a transformation like parsing or transforming some input, could have a cache key like example-myparser, option-xyz, v2, hash1234
which would describe the transformation, the version/parameters, and a hash of the exact input.
This also naturally avoids oscillation or corruption in the context of multiple servers and data centers, where your code may not always be running the same version everywhere at the same time. Newer code would have its own set of cache keys, ensuring a deterministic outcome.
B) The value is cached with a low TTL.
If you can tolerate a few seconds or minutes of delay before changes are reflected in the way your data is used, and if re-computation is quick, you can consider caching it with a "blind" TTL – using the value's age as your method of validation.
C) Validity is checked against an external source.
Perhaps you prefer to utilize the old data as fallback or to help compute the new value, or for other reasons you need to have a stable key across input changes (e.g. cache by page title instead of revision ID). If you put the variable identifier (e.g. input hash, or revision ID) in the cache value, and validate this on retrieval then you don't need purging or expiration.
After calling get() you can validate the ID inside the cached value against what you know. When needed, recompute the value and call set().
The purge strategy refers to the approach whereby your application knows that source data has changed and can react by purging the relevant cache keys. The simplest purge method is delete().
Note that cache updates and purges are not immediately visible to all application servers in all data centers. The cache should be treated like a replica database in this regard. If immediate synchronization is required, then solutions must be sought outside WANCache.
Write operations like delete() and the "set" part of getWithSetCallback(), may return true as soon as the command has been sent or buffered to an open connection to the cache cluster. It will be processed and/or broadcasted asynchronously.
There are two supported ways for sysadmins to set up multi-DC cache purging:
Broadcasted operations like delete() and touchCheckKey() are intended to run immediately in the local datacenter and asynchronously in remote datacenters.
This means that callers in all datacenters may see older values for however many milliseconds that the purge took to reach that datacenter. 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, except when reading immutable data.
Internally, access to a given key actually involves the use of one or more "sister" keys. A sister key is constructed by prefixing the base key with "WANCache:" (used to distinguish WANObjectCache formatted keys) and suffixing a colon followed by a single-character sister key type. The sister key types include the following:
v
: used to store "regular" values (metadata-wrapped) and temporary purge "tombstones".t
: used to store "last purge" timestamps for "check" keys.m
: used to store temporary mutex locks to avoid cache stampedes.i
: used to store temporary interim values (metadata-wrapped) for tombstoned keys.c
: used to store temporary "cool-off" indicators, which specify a period during which values cannot be stored, neither regularly nor using interim keys.Definition at line 164 of file WANObjectCache.php.
Wikimedia\ObjectCache\WANObjectCache::__construct | ( | array | $params | ) |
array | $params |
|
Definition at line 366 of file WANObjectCache.php.
References $params, Wikimedia\ObjectCache\WANObjectCache\setLogger(), and wfDeprecated().
Wikimedia\ObjectCache\WANObjectCache::adaptiveTTL | ( | $mtime, | |
$maxTTL, | |||
$minTTL = 30, | |||
$factor = 0.2 ) |
Get a TTL that is higher for objects that have not changed recently.
This is useful for keys that get explicit purges and DB or purge relay lag is a potential concern (especially how it interacts with CDN cache)
Example usage:
Another use case is when there are no applicable "last modified" fields in the DB, and there are too many dependencies for explicit purges to be viable, and the rate of change to relevant content is unstable, and it is highly valued to have the cached value be as up-to-date as possible.
Example usage:
int | float | string | null | $mtime | UNIX timestamp; null if none |
int | $maxTTL | Maximum TTL (seconds) |
int | $minTTL | Minimum TTL (seconds); Default: 30 |
float | $factor | Value in the range (0,1); Default: .2 |
Definition at line 2606 of file WANObjectCache.php.
References Wikimedia\ObjectCache\WANObjectCache\getCurrentTime().
|
final |
Clear the "last error" registry.
Definition at line 2496 of file WANObjectCache.php.
References wfDeprecated().
Wikimedia\ObjectCache\WANObjectCache::clearProcessCache | ( | ) |
Clear the in-process caches; useful for testing.
Definition at line 2506 of file WANObjectCache.php.
|
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:
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:
Note that set() can also be lag-aware and lower the TTL if it's high.
Be aware that this does not clear the process cache. Even if it did, callbacks used by getWithSetCallback() might still return stale data in the case of either uncommitted or not-yet-replicated changes (callback generally use replica DBs).
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 upon purge relay. It also avoids the following race condition:
Example usage:
The $ttl parameter can be used when purging values that have not actually changed recently. For example, user-requested purges or cache cleanup scripts might not need to invoke a hold-off period on cache backfills, so they can use HOLDOFF_TTL_NONE.
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.
string | $key | Cache key made with makeKey()/makeGlobalKey() |
int | $ttl | Tombstone TTL; Default: WANObjectCache::HOLDOFF_TTL |
Definition at line 1061 of file WANObjectCache.php.
References Wikimedia\ObjectCache\WANObjectCache\getCurrentTime(), Wikimedia\ObjectCache\WANObjectCache\relayNonVolatilePurge(), and Wikimedia\ObjectCache\WANObjectCache\relayVolatilePurge().
|
protected |
Fetch the value and key metadata of several keys from cache.
$checkKeys holds the "check" keys used to validate values of applicable keys. The integer indexes hold "check" keys that apply to all of $keys while the string indexes hold "check" keys that only apply to the cache key with that name.
string[] | $keys | List/map with makeKey()/makeGlobalKey() cache keys as values |
string[] | string[][] | $checkKeys | Map of (integer or cache key => "check" key(s)); "check" keys must also be made with makeKey()/makeGlobalKey() |
float | $now | The current UNIX timestamp |
callable | null | $touchedCb | Callback yielding a UNIX timestamp from a value, or null |
Definition at line 574 of file WANObjectCache.php.
Referenced by Wikimedia\ObjectCache\WANObjectCache\get(), Wikimedia\ObjectCache\WANObjectCache\getMulti(), and Wikimedia\ObjectCache\WANObjectCache\getMultiWithUnionSetCallback().
|
final |
Fetch the value of a key from cache.
If supplied, $curTTL is set to the remaining TTL (current time left):
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 key purges by updating a single key:
Source data entities might exist 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:
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(), which has cache slam avoidance and key versioning features, instead of bare get()/set() calls.
Do not use this method on versioned keys accessed via getWithSetCallback().
When using the $info parameter, it should be passed in as WANObjectCache::PASS_BY_REF. In that case, it becomes a key metadata map. Otherwise, for backwards compatibility, $info becomes the value generation timestamp (null if the key is nonexistant/tombstoned). Key metadata map fields include:
string | $key | Cache key made with makeKey()/makeGlobalKey() |
float | null | &$curTTL | Seconds of TTL left [returned] |
string[] | $checkKeys | Map of (integer or cache key => "check" key(s)); "check" keys must also be made with makeKey()/makeGlobalKey() |
array | &$info | Metadata map [returned] |
Definition at line 467 of file WANObjectCache.php.
References Wikimedia\ObjectCache\WANObjectCache\fetchKeys(), Wikimedia\ObjectCache\WANObjectCache\getCurrentTime(), and Wikimedia\ObjectCache\WANObjectCache\PASS_BY_REF.
|
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.
string | $key | Cache key made with makeKey()/makeGlobalKey() |
Definition at line 1115 of file WANObjectCache.php.
References Wikimedia\ObjectCache\WANObjectCache\getMultiCheckKeyTime().
|
protected |
Definition at line 3114 of file WANObjectCache.php.
Referenced by Wikimedia\ObjectCache\WANObjectCache\adaptiveTTL(), Wikimedia\ObjectCache\WANObjectCache\delete(), Wikimedia\ObjectCache\WANObjectCache\get(), Wikimedia\ObjectCache\WANObjectCache\getMulti(), Wikimedia\ObjectCache\WANObjectCache\getMultiCheckKeyTime(), Wikimedia\ObjectCache\WANObjectCache\getMultiWithUnionSetCallback(), and Wikimedia\ObjectCache\WANObjectCache\touchCheckKey().
|
final |
Get the "last error" registry.
The method should be invoked by a caller as part of the following pattern:
External callers can also invoke this method as part of the following pattern:
int | $watchPoint | Only consider errors from after this "watch point" [optional] |
Definition at line 2478 of file WANObjectCache.php.
References Wikimedia\LightweightObjectStore\StorageAwareness\ERR_NO_RESPONSE, Wikimedia\LightweightObjectStore\StorageAwareness\ERR_NONE, Wikimedia\LightweightObjectStore\StorageAwareness\ERR_UNEXPECTED, and Wikimedia\LightweightObjectStore\StorageAwareness\ERR_UNREACHABLE.
|
final |
Fetch the value of several keys from cache.
$curTTLs becomes a map of only present/tombstoned $keys to their current time-to-live.
$checkKeys holds the "check" keys used to validate values of applicable keys. The integer indexes hold "check" keys that apply to all of $keys while the string indexes hold "check" keys that only apply to the cache key with that name. The logic of "check" keys otherwise works the same as in WANObjectCache::get().
When using the $info parameter, it should be passed in as WANObjectCache::PASS_BY_REF. In that case, it becomes a mapping of all the $keys to their metadata maps, each in the style of WANObjectCache::get(). Otherwise, for backwards compatibility, $info becomes a map of only present/tombstoned $keys to their value generation timestamps.
string[] | $keys | List/map with makeKey()/makeGlobalKey() cache keys as values |
array<string,float> | &$curTTLs Map of (key => seconds of TTL left) [returned] | |
string[] | string[][] | $checkKeys | Map of (integer or cache key => "check" key(s)); "check" keys must also be made with makeKey()/makeGlobalKey() |
array<string,array> | &$info Map of (key => metadata map) [returned] |
Definition at line 520 of file WANObjectCache.php.
References Wikimedia\ObjectCache\WANObjectCache\fetchKeys(), Wikimedia\ObjectCache\WANObjectCache\getCurrentTime(), and Wikimedia\ObjectCache\WANObjectCache\PASS_BY_REF.
|
final |
Fetch the values of each timestamp "check" key.
This works like getCheckKeyTime() except it takes a list of keys and returns a map of timestamps instead of just that of one key
This might be useful if both:
The later entities can each use a "check" key to purge their dependee entities. However, it is expensive for the former entities to verify against all of the relevant "check" keys during each getWithSetCallback() call. A less expensive approach is to do these verifications only after a "time-till-verify" (TTV) has passed. This is a middle ground between using blind TTLs and using constant verification. The adaptiveTTL() method can be used to dynamically adjust the TTV. Also, the initial TTV can make use of the last-modified times of the dependent entities (either from the DB or the "check" keys).
Example usage:
string[] | $keys | Cache keys made with makeKey()/makeGlobalKey() |
Definition at line 1180 of file WANObjectCache.php.
References Wikimedia\ObjectCache\WANObjectCache\getCurrentTime().
Referenced by Wikimedia\ObjectCache\WANObjectCache\getCheckKeyTime().
|
final |
Method to fetch multiple cache keys at once with regeneration.
This works the same as getWithSetCallback() except:
Example usage:
ArrayIterator | $keyedIds | Result of WANObjectCache::makeMultiKeys() |
int | $ttl | Seconds to live for key updates |
callable | $callback | Callback that yields entity generation callbacks |
array | $opts | Options map similar to that of getWithSetCallback() |
Definition at line 2106 of file WANObjectCache.php.
References $params, and Wikimedia\ObjectCache\WANObjectCache\getWithSetCallback().
|
final |
Method to fetch/regenerate multiple cache keys at once.
This works the same as getWithSetCallback() except:
Example usage:
ArrayIterator | $keyedIds | Result of WANObjectCache::makeMultiKeys() |
int | $ttl | Seconds to live for key updates |
callable | $callback | Callback that yields entity generation callbacks |
array | $opts | Options map similar to that of getWithSetCallback() |
Definition at line 2209 of file WANObjectCache.php.
References $params, Wikimedia\ObjectCache\WANObjectCache\fetchKeys(), Wikimedia\ObjectCache\WANObjectCache\getCurrentTime(), and Wikimedia\ObjectCache\WANObjectCache\getWithSetCallback().
Wikimedia\ObjectCache\WANObjectCache::getQoS | ( | $flag | ) |
int | $flag | ATTR_* class constant |
Definition at line 2539 of file WANObjectCache.php.
|
final |
Definition at line 2624 of file WANObjectCache.php.
|
final |
Method to fetch/regenerate a cache key.
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:
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 $ttl argument and "hotTTR" option (in $opts) use time-dependent randomization to avoid stampedes. Keys that are slow to regenerate and either heavily used or subject to explicit (unpredictable) purges, may need additional mechanisms. The simplest way to avoid stampedes for such keys is to use 'lockTSE' (in $opts). If explicit purges are needed, also:
This applies cache server I/O stampede protection against duplicate cache sets. This is important when the callback is slow and/or yields large values for a key.
Example usage (typical key):
Example usage (key that is expensive and hot):
Example usage (key with dynamic dependencies):
Example usage (key that is expensive with too many DB dependencies for "check" keys):
Example usage (hot key holding most recent 100 events):
Example usage (key holding an LRU subkey:value map; this can avoid flooding cache with keys for an unlimited set of (constraint,situation) pairs, thereby avoiding elevated cache evictions and wasted memory):
string | $key | Cache key made with makeKey()/makeGlobalKey() |
int | $ttl | Nominal seconds-to-live for newly computed values. Special values are:
|
callable | $callback | Value generation function |
array | $opts | Options map:
|
array | $cbParams | Custom field/value map to pass to the callback (since 1.35) @phpcs:ignore Generic.Files.LineLength |
Definition at line 1603 of file WANObjectCache.php.
References Wikimedia\ObjectCache\WANObjectCache\makeGlobalKey().
Referenced by Wikimedia\ObjectCache\WANObjectCache\getMultiWithSetCallback(), and Wikimedia\ObjectCache\WANObjectCache\getMultiWithUnionSetCallback().
Wikimedia\ObjectCache\WANObjectCache::hash256 | ( | $component | ) |
Hash a possibly long string into a suitable component for makeKey()/makeGlobalKey()
string | $component | A raw component used in building a cache key |
Definition at line 2327 of file WANObjectCache.php.
|
protected |
Check if a key is due for randomized regeneration due to near-expiration/popularity.
array | $res | Current value WANObjectCache::RES_* data map |
float | $lowTTL | Consider a refresh when $curTTL is less than this; the "low" threshold |
int | $ageNew | Age of key when this might recommend refreshing (seconds) |
int | $hotTTR | Age of key when it should be refreshed if popular (seconds) |
float | $now | The current UNIX timestamp |
Definition at line 2767 of file WANObjectCache.php.
References Wikimedia\ObjectCache\WANObjectCache\worthRefreshExpiring(), and Wikimedia\ObjectCache\WANObjectCache\worthRefreshPopular().
|
protected |
Check that a wrapper value exists and has an acceptable age.
array | false | $value | Value wrapper or false |
float | $asOf | Value generation "as of" timestamp |
float | $minAsOf | Minimum acceptable value "as of" UNIX timestamp |
Definition at line 2868 of file WANObjectCache.php.
Wikimedia\ObjectCache\WANObjectCache::makeGlobalKey | ( | $keygroup, | |
$components ) |
string | $keygroup | Key group component, should be under 48 characters. |
string|int | ...$components Additional, ordered, key components for entity IDs |
Implements Wikimedia\ObjectCache\IStoreKeyEncoder.
Definition at line 2305 of file WANObjectCache.php.
Referenced by MediaWiki\User\User\getCacheKey(), and Wikimedia\ObjectCache\WANObjectCache\getWithSetCallback().
Wikimedia\ObjectCache\WANObjectCache::makeKey | ( | $keygroup, | |
$components ) |
string | $keygroup | Key group component, should be under 48 characters. |
string|int | ...$components Additional, ordered, key components for entity IDs |
Implements Wikimedia\ObjectCache\IStoreKeyEncoder.
Definition at line 2316 of file WANObjectCache.php.
Referenced by InfoAction\getCacheKey().
|
final |
Get an iterator of (cache key => entity ID) for a list of entity IDs.
The $callback argument expects a function that returns the key for an entity ID via makeKey()/makeGlobalKey(). There should be no network nor filesystem I/O used in the callback. The entity ID/key mapping must be 1:1 or an exception will be thrown. Use the hash256() method for any hashing. The callback takes the following arguments:
Example usage for the default keyspace:
Example usage for mixed default and global keyspace:
Example usage with hashing:
string[] | int[] | $ids | List of entity IDs |
callable | $keyCallback | Function returning makeKey()/makeGlobalKey() on the input ID |
Definition at line 2382 of file WANObjectCache.php.
|
final |
Get an (ID => value) map from (i) a non-unique list of entity IDs, and (ii) the list of corresponding entity values by first appearance of each ID in the entity ID list.
For use with getMultiWithSetCallback() and getMultiWithUnionSetCallback().
Only use this method if the entity ID/key mapping is trivially 1:1 without exception. Key generation method must utilize the full entity ID in the key (not a hash of it).
Example usage:
string[] | int[] | $ids | Entity ID list makeMultiKeys() |
mixed[] | $res | Result of getMultiWithSetCallback()/getMultiWithUnionSetCallback() |
Definition at line 2438 of file WANObjectCache.php.
|
static |
Get an instance that wraps EmptyBagOStuff.
Definition at line 408 of file WANObjectCache.php.
|
protected |
string | $sisterKey | |
string | $route | Key routing prefix |
Definition at line 2681 of file WANObjectCache.php.
Referenced by Wikimedia\ObjectCache\WANObjectCache\relayNonVolatilePurge(), and Wikimedia\ObjectCache\WANObjectCache\relayVolatilePurge().
|
protected |
Remove a sister key from all datacenters.
This method should not wait for the operation to complete on remote datacenters
string | $sisterKey | A value key or "check" key |
Definition at line 2666 of file WANObjectCache.php.
References Wikimedia\ObjectCache\WANObjectCache\prependRoute().
Referenced by Wikimedia\ObjectCache\WANObjectCache\delete(), and Wikimedia\ObjectCache\WANObjectCache\resetCheckKey().
|
protected |
Set a sister key to a purge value in all datacenters.
This method should not wait for the operation to complete on remote datacenters
Since older purge values can sometimes arrive after newer ones, use a relative expiry so that even if the older value replaces the newer value, the TTL will greater than the remaining TTL on the older value (assuming that all purges for a key use the same TTL).
string | $sisterKey | A value key or "check" key |
string | $purgeValue | Result of makeTombstonePurgeValue()/makeCheckKeyPurgeValue() |
int | $ttl | Seconds to keep the purge value around |
Definition at line 2643 of file WANObjectCache.php.
References Wikimedia\ObjectCache\WANObjectCache\prependRoute().
Referenced by Wikimedia\ObjectCache\WANObjectCache\delete(), and Wikimedia\ObjectCache\WANObjectCache\touchCheckKey().
|
final |
Clear the last-purge timestamp of a "check" key in all datacenters.
Similar to touchCheckKey(), in that keys fetched using get*() calls, that include the given "check" key, will be seen as purged. However, there are some differences:
The advantage over touchCheckKey() is that the "check" keys, which have high TTLs, will only be created when a get*() method actually uses those keys. This is better when a large number of "check" keys must be changed in a short period of time.
Note that "check" keys won't collide with other regular keys.
string | $key | Cache key made with makeKey()/makeGlobalKey() |
Definition at line 1287 of file WANObjectCache.php.
References Wikimedia\ObjectCache\WANObjectCache\relayNonVolatilePurge().
|
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 data was read using "view snapshots" (e.g. innodb REPEATABLE-READ), use 'since' to avoid the following race condition:
Setting 'lag' and 'since' help avoids keys getting stuck in stale states.
Be aware that this does not update the process cache for getWithSetCallback() callers. Keys accessed via that method are not generally meant to also be set using this primitive method.
Consider using getWithSetCallback(), which has cache slam avoidance and key versioning features, instead of bare get()/set() calls.
Do not use this method on versioned keys accessed via getWithSetCallback().
Example usage:
string | $key | Cache key made with makeKey()/makeGlobalKey() |
mixed | $value | Value to set for the cache key |
int | $ttl | Seconds to live. Special values are:
|
array | $opts | Options map:
|
Definition at line 811 of file WANObjectCache.php.
Referenced by MediaWiki\ResourceLoader\MessageBlobStore\recacheMessageBlob().
Wikimedia\ObjectCache\WANObjectCache::setLogger | ( | LoggerInterface | $logger | ) |
LoggerInterface | $logger |
Definition at line 399 of file WANObjectCache.php.
References Wikimedia\ObjectCache\WANObjectCache\$logger.
Referenced by Wikimedia\ObjectCache\WANObjectCache\__construct().
Wikimedia\ObjectCache\WANObjectCache::setMockTime | ( | & | $time | ) |
float | null | &$time | Mock UNIX timestamp for testing |
Definition at line 3122 of file WANObjectCache.php.
|
final |
Increase the last-purge timestamp of a "check" key in all datacenters.
This method should only be called when some heavily referenced data changes in a significant way, such that it is impractical to call delete() on all the cache keys that should be purged. The get*() method calls used to fetch these keys must include the given "check" key in the relevant "check" keys argument/option.
A "check" key essentially represents a last-modified time of an entity. When the key is touched, the timestamp will be updated to the current time. Keys fetched using get*() calls, that include the "check" key, will be seen as purged.
The timestamp of the "check" key is treated as being HOLDOFF_TTL seconds in the future by get*() methods in order to avoid race conditions where keys are updated with stale values (e.g. from a lagged replica DB). A high TTL is set on the "check" key, making it possible to know the timestamp of the last change to the corresponding entities in most cases. This might use more cache space than resetCheckKey().
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, causing any get() after the reset to treat the key as being "hot", resulting in more stale value usage.
Note that "check" keys won't collide with other regular keys.
string | $key | Cache key made with makeKey()/makeGlobalKey() |
int | $holdoff | HOLDOFF_TTL or HOLDOFF_TTL_NONE constant |
Definition at line 1242 of file WANObjectCache.php.
References Wikimedia\ObjectCache\WANObjectCache\getCurrentTime(), and Wikimedia\ObjectCache\WANObjectCache\relayVolatilePurge().
Referenced by MediaWiki\ResourceLoader\MessageBlobStore\clearGlobalCacheEntry().
|
final |
Enable or disable the use of brief caching for tombstoned keys.
When a key is purged via delete(), there normally is a period where caching is hold-off limited to an extremely short time. This method will disable that caching, forcing the callback to run for any of:
This is useful when both:
bool | $enabled | Whether to enable interim caching |
Definition at line 2530 of file WANObjectCache.php.
References Wikimedia\ObjectCache\WANObjectCache\useInterimHoldOffCaching().
Referenced by Wikimedia\ObjectCache\WANObjectCache\useInterimHoldOffCaching().
Wikimedia\ObjectCache\WANObjectCache::watchErrors | ( | ) |
Get a "watch point" token that can be used to get the "last error" to occur after now.
Definition at line 2457 of file WANObjectCache.php.
|
protected |
Check if a key is nearing expiration and thus due for randomized regeneration.
If $curTTL is greater than the "low" threshold (e.g. not nearing expiration) then this returns false. If $curTTL <= 0 (e.g. value already expired), then this returns false. Otherwise, the chance of this returning true increases steadily from 0% to 100% as $curTTL moves from the "low" threshold down to 0 seconds.
The logical TTL will be used as the "low" threshold if it is less than $lowTTL.
This method uses deadline-aware randomization in order to handle wide variations of cache access traffic without the need for configuration or expensive state.
float | $curTTL | Approximate TTL left on the key |
float | $logicalTTL | Full logical TTL assigned to the key; 0 for "infinite" |
float | $lowTTL | Consider a refresh when $curTTL is less than this; the "low" threshold |
Definition at line 2837 of file WANObjectCache.php.
Referenced by Wikimedia\ObjectCache\WANObjectCache\isLotteryRefreshDue().
|
protected |
Check if a key is due for randomized regeneration due to its popularity.
This is used so that popular keys can preemptively refresh themselves for higher consistency (especially in the case of purge loss/delay). Unpopular keys can remain in cache with their high nominal TTL. This means popular keys keep good consistency, whether the data changes frequently or not, and long-tail keys get to stay in cache and get hits too. Similar to worthRefreshExpiring(), randomization is used.
float | $asOf | UNIX timestamp of the value |
int | $ageNew | Age of key when this might recommend refreshing (seconds) |
int | $timeTillRefresh | Age of key when it should be refreshed if popular (seconds) |
float | $now | The current UNIX timestamp |
Definition at line 2793 of file WANObjectCache.php.
Referenced by Wikimedia\ObjectCache\WANObjectCache\isLotteryRefreshDue().
|
protected |
Function that takes a WAN cache callback and runs it later.
Definition at line 179 of file WANObjectCache.php.
|
protected |
Routing prefix for operations that should be broadcasted to all data centers.
If null, the there is only one datacenter or a backend proxy broadcasts everything.
Definition at line 188 of file WANObjectCache.php.
|
protected |
The local datacenter cache.
Definition at line 171 of file WANObjectCache.php.
|
protected |
Scheme to use for key coalescing (Hash Tags or Hash Stops)
Definition at line 196 of file WANObjectCache.php.
|
protected |
Unix timestamp of the oldest possible valid values.
Definition at line 192 of file WANObjectCache.php.
|
protected |
Definition at line 175 of file WANObjectCache.php.
Referenced by Wikimedia\ObjectCache\WANObjectCache\setLogger().
|
protected |
Map of group PHP instance caches.
Definition at line 173 of file WANObjectCache.php.
|
protected |
Stable secret used for hashing long strings into key components.
Definition at line 194 of file WANObjectCache.php.
|
protected |
Definition at line 177 of file WANObjectCache.php.
|
protected |
Whether to use "interim" caching while keys are tombstoned.
Definition at line 190 of file WANObjectCache.php.
const Wikimedia\ObjectCache\WANObjectCache::GRACE_TTL_NONE = 0 |
Idiom for set()/getWithSetCallback() meaning "no post-expiration grace period".
Definition at line 234 of file WANObjectCache.php.
const Wikimedia\ObjectCache\WANObjectCache::HOLDOFF_TTL = self::MAX_COMMIT_DELAY + self::MAX_READ_LAG + 1 |
Seconds to tombstone keys on delete() and to treat keys as volatile after purges.
Definition at line 216 of file WANObjectCache.php.
const Wikimedia\ObjectCache\WANObjectCache::HOLDOFF_TTL_NONE = 0 |
Idiom for delete()/touchCheckKey() meaning "no hold-off period".
Definition at line 236 of file WANObjectCache.php.
const Wikimedia\ObjectCache\WANObjectCache::KEY_AS_OF = 'asOf' |
Generation completion timestamp attribute for a key; keep value for b/c (< 1.36)
Definition at line 286 of file WANObjectCache.php.
const Wikimedia\ObjectCache\WANObjectCache::KEY_CHECK_AS_OF = 'lastCKPurge' |
Highest "check" key timestamp for a key; keep value for b/c (< 1.36)
Definition at line 294 of file WANObjectCache.php.
const Wikimedia\ObjectCache\WANObjectCache::KEY_CUR_TTL = 'curTTL' |
Remaining TTL attribute for a key; keep value for b/c (< 1.36)
Definition at line 290 of file WANObjectCache.php.
const Wikimedia\ObjectCache\WANObjectCache::KEY_TOMB_AS_OF = 'tombAsOf' |
Tomstone timestamp attribute for a key; keep value for b/c (< 1.36)
Definition at line 292 of file WANObjectCache.php.
const Wikimedia\ObjectCache\WANObjectCache::KEY_TTL = 'ttl' |
Logical TTL attribute for a key.
Definition at line 288 of file WANObjectCache.php.
const Wikimedia\ObjectCache\WANObjectCache::KEY_VERSION = 'version' |
Version number attribute for a key; keep value for b/c (< 1.36)
Definition at line 284 of file WANObjectCache.php.
const Wikimedia\ObjectCache\WANObjectCache::PASS_BY_REF = [] |
Idiom for get()/getMulti() to return extra information by reference.
Definition at line 245 of file WANObjectCache.php.
Referenced by Wikimedia\ObjectCache\WANObjectCache\get(), and Wikimedia\ObjectCache\WANObjectCache\getMulti().
const Wikimedia\ObjectCache\WANObjectCache::STALE_TTL_NONE = 0 |
Idiom for set()/getWithSetCallback() meaning "no post-expiration persistence".
Definition at line 232 of file WANObjectCache.php.
const Wikimedia\ObjectCache\WANObjectCache::TTL_LAGGED = 30 |
Max TTL, in seconds, to store keys when a data source has high replication lag.
Definition at line 221 of file WANObjectCache.php.