MediaWiki  master
WANObjectCache Class Reference

Multi-datacenter aware caching interface. More...

Inheritance diagram for WANObjectCache:
Collaboration diagram for WANObjectCache:

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. More...
 
 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=[], &$info=[])
 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=[], &$info=[])
 Fetch the value of several keys from cache. More...
 
 getMultiCheckKeyTime (array $keys)
 Fetch the values of each timestamp "check" key. More...
 
 getMultiWithSetCallback (ArrayIterator $keyedIds, $ttl, callable $callback, array $opts=[])
 Method to fetch multiple cache keys at once with regeneration. More...
 
 getMultiWithUnionSetCallback (ArrayIterator $keyedIds, $ttl, callable $callback, array $opts=[])
 Method to fetch/regenerate multiple cache keys at once. More...
 
 getQoS ( $flag)
 
 getWarmupKeyMisses ()
 
 getWithSetCallback ( $key, $ttl, $callback, array $opts=[], array $cbParams=[])
 Method to fetch/regenerate a cache key. More...
 
 hash256 ( $component)
 Hash a possibly long string into a suitable component for makeKey()/makeGlobalKey() More...
 
 makeGlobalKey ( $collection,... $components)
 Make a cache key for the global keyspace and given components. More...
 
 makeKey ( $collection,... $components)
 Make a cache key using the "global" keyspace for the given components. More...
 
 makeMultiKeys (array $ids, $keyCallback)
 Get an iterator of (cache key => entity ID) for a list of entity IDs. More...
 
 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. More...
 
 reap ( $key, $purgeTimestamp, &$isStale=false)
 Set a key to soon expire in the local cluster if it pre-dates $purgeTimestamp. More...
 
 reapCheckKey ( $key, $purgeTimestamp, &$isStale=false)
 Set a "check" key to soon expire in the local cluster if it pre-dates $purgeTimestamp. More...
 
 resetCheckKey ( $key)
 Delete a "check" key from all datacenters, invalidating keys that use it. More...
 
 set ( $key, $value, $ttl=self::TTL_INDEFINITE, array $opts=[])
 Set the value of a key in cache. More...
 
 setLogger (LoggerInterface $logger)
 
 setMockTime (&$time)
 
 touchCheckKey ( $key, $holdoff=self::HOLDOFF_TTL)
 Purge a "check" key from all datacenters, invalidating keys that use it. More...
 
 useInterimHoldOffCaching ( $enabled)
 Enable or disable the use of brief caching for tombstoned keys. More...
 

Static Public Member Functions

static getCollectionFromSisterKey (string $sisterKey)
 
static newEmpty ()
 Get an instance that wraps EmptyBagOStuff. More...
 

Public Attributes

const GRACE_TTL_NONE = 0
 Idiom for set()/getWithSetCallback() meaning "no post-expiration grace period". More...
 
const HOLDOFF_TTL = self::MAX_COMMIT_DELAY + self::MAX_READ_LAG + 1
 Seconds to tombstone keys on delete() and treat as volatile after invalidation. More...
 
const HOLDOFF_TTL_NONE = 0
 Idiom for delete()/touchCheckKey() meaning "no hold-off period". More...
 
const KEY_AS_OF = 'asOf'
 Generation timestamp attribute for a key; keep value for b/c (< 1.36) More...
 
const KEY_CHECK_AS_OF = 'lastCKPurge'
 Highest "check" key timestamp for a key; keep value for b/c (< 1.36) More...
 
const KEY_CUR_TTL = 'curTTL'
 Remaining TTL attribute for a key; keep value for b/c (< 1.36) More...
 
const KEY_TOMB_AS_OF = 'tombAsOf'
 Tomstone timestamp attribute for a key; keep value for b/c (< 1.36) More...
 
const KEY_TTL = 'ttl'
 Logical TTL attribute for a key. More...
 
const KEY_VERSION = 'version'
 Version number attribute for a key; keep value for b/c (< 1.36) More...
 
const PASS_BY_REF = []
 Idiom for get()/getMulti() to return extra information by reference. More...
 
const STALE_TTL_NONE = 0
 Idiom for set()/getWithSetCallback() meaning "no post-expiration persistence". More...
 
const TTL_LAGGED = 30
 Max TTL, in seconds, to store keys when a data source has high replication lag. More...
 
- Public Attributes inherited from Wikimedia\LightweightObjectStore\StorageAwareness
const ATTR_DURABILITY = 2
 Durability of writes; see QOS_DURABILITY_* (higher means stronger) More...
 
const ATTR_EMULATION = 1
 Emulation/fallback mode; see QOS_EMULATION_*; higher is better. More...
 
const ERR_NO_RESPONSE = 1
 Storage medium failed to yield a response. More...
 
const ERR_NONE = 0
 No storage medium error. More...
 
const ERR_UNEXPECTED = 3
 Storage medium operation failed due to usage limitations or an I/O error. More...
 
const ERR_UNREACHABLE = 2
 Storage medium could not be reached. More...
 
const QOS_DURABILITY_DISK = 4
 Data is saved to disk and writes do not usually block on fsync() More...
 
const QOS_DURABILITY_NONE = 1
 Data is never saved to begin with (blackhole store) More...
 
const QOS_DURABILITY_RDBMS = 5
 Data is saved to disk and writes usually block on fsync(), like a standard RDBMS. More...
 
const QOS_DURABILITY_SCRIPT = 2
 Data is lost at the end of the current web request or CLI script. More...
 
const QOS_DURABILITY_SERVICE = 3
 Data is lost once the service storing the data restarts. More...
 
const QOS_EMULATION_SQL = 1
 Fallback disk-based SQL store. More...
 
const QOS_LOCALITY_LAN = 1
 Data is stored on remote hosts and accessed via the local area network. More...
 
const QOS_LOCALITY_SRV = 2
 Data is stored on the local host and accessed via shared RAM, sockets, or filesystems. More...
 
const QOS_UNKNOWN = INF
 Generic "unknown" value; useful for comparisons (always "good enough") More...
 

Protected Member Functions

 fetchKeys (array $keys, array $checkKeys)
 Fetch the value and key metadata of several keys from cache. More...
 
 getCurrentTime ()
 
 isValid ( $value, $asOf, $minAsOf, $purgeTime=null)
 Check if $value is not false, versioned (if needed), and not older than $minTime (if set) More...
 
 prependRoute (string $sisterKey, string $route)
 
 relayNonVolatilePurge (string $sisterKey)
 Remove a sister key from all datacenters. More...
 
 relayVolatilePurges (array $purgeBySisterKey, int $ttl)
 Set a sister key to a purge value in all datacenters. More...
 
 worthRefreshExpiring ( $curTTL, $logicalTTL, $lowTTL)
 Check if a key is nearing expiration and thus due for randomized regeneration. More...
 
 worthRefreshPopular ( $asOf, $ageNew, $timeTillRefresh, $now)
 Check if a key is due for randomized regeneration due to its popularity. More...
 

Protected Attributes

callable null $asyncHandler
 Function that takes a WAN cache callback and runs it later. More...
 
string null $broadcastRoute
 Routing prefix for values that should be broadcasted to all data centers. More...
 
BagOStuff $cache
 The local datacenter cache. More...
 
int $coalesceScheme
 Scheme to use for key coalescing (Hash Tags or Hash Stops) More...
 
float $epoch
 Unix timestamp of the oldest possible valid values. More...
 
LoggerInterface $logger
 
string null $onHostRoute
 Routing prefix for value keys that support use of an on-host tier. More...
 
MapCacheLRU[] $processCaches = []
 Map of group PHP instance caches. More...
 
string $secret
 Stable secret used for hasing long strings into key components. More...
 
StatsdDataFactoryInterface $stats
 
bool $useInterimHoldOffCaching = true
 Whether to use "interim" caching while keys are tombstoned. More...
 

Private Member Functions

 checkAndSetCooloff ( $key, $kClass, $value, $elapsed, $hasLock)
 Check whether set() is rate-limited to avoid concurrent I/O spikes. More...
 
 claimStampedeLock ( $key)
 
 determineKeyClassForStats ( $key)
 
 fetchOrRegenerate ( $key, $ttl, $callback, array $opts, array $cbParams)
 Do the actual I/O for getWithSetCallback() when needed. More...
 
 fetchWrappedValuesForWarmupCache (array $keys, array $checkKeys)
 
 getInterimValue ( $key, $minAsOf, $now)
 
 getNonProcessCachedMultiKeys (ArrayIterator $keys, array $opts)
 
 getProcessCache ( $group)
 
 isAliveOrInGracePeriod ( $curTTL, $graceTTL)
 Check if a key is fresh or in the grace window and thus due for randomized reuse. More...
 
 isVolatileValueAgeNegligible ( $age)
 
 makeCheckPurgeValue (float $timestamp, int $holdoff, array &$purge=null)
 
 makeSisterKey (string $baseKey, string $typeChar, string $route=null)
 Get a sister key that should be collocated with a base cache key. More...
 
 makeSisterKeys (array $baseKeys, string $type, string $route=null)
 Get sister keys that should be collocated with their corresponding base cache keys. More...
 
 makeTombstonePurgeValue (float $timestamp)
 
 parsePurgeValue ( $value)
 Extract purge metadata from cached value if it is a valid purge value. More...
 
 processCheckKeys (array $checkSisterKeys, array $wrappedBySisterKey, float $now)
 
 processFluxKeys (array $keys, array $fluxSisterKeys, array $wrappedBySisterKey)
 
 resolveBusyValue ( $busyValue)
 
 resolveCTL ( $value, $curTTL, $curInfo, $touchedCallback)
 
 resolveTouched ( $value, $lastPurge, $touchedCallback)
 
 scheduleAsyncRefresh ( $key, $ttl, $callback, array $opts, array $cbParams)
 Schedule a deferred cache regeneration if possible. More...
 
 setInterimValue ( $key, $value, $ttl, $version, $now, $walltime)
 
 timeSinceLoggedMiss ( $key, $now)
 
 unwrap ( $wrapped, $now)
 
 wrap ( $value, $ttl, $version, $now, $walltime)
 
 yieldStampedeLock ( $key, $hasLock)
 

Private Attributes

int $callbackDepth = 0
 Callback stack depth for getWithSetCallback() More...
 
int $keyHighQps
 Reads/second assumed during a hypothetical cache write stampede for a key. More...
 
float $keyHighUplinkBps
 Max tolerable bytes/second to spend on a cache write stampede for a key. More...
 
array< int, array > $missLog
 List of (key, UNIX timestamp) tuples for get() cache misses. More...
 
float null $wallClockOverride
 
mixed[] $warmupCache = []
 Temporary warm-up cache. More...
 
int $warmupKeyMisses = 0
 Key fetched. More...
 
const AGE_NEW = 60
 Minimum key age, in seconds, for expected time-till-refresh to be considered. More...
 
const CHECK_KEY_TTL = self::TTL_YEAR
 Seconds to keep dependency purge keys around. More...
 
const COOLOFF_TTL = 1
 Seconds to no-op key set() calls to avoid large blob I/O stampedes. More...
 
const FLD_FLAGS = 4
 Key to the flags bit field (reserved number) More...
 
const FLD_FORMAT_VERSION = 0
 Key to WAN cache version number. More...
 
const FLD_GENERATION_TIME = 6
 Key to how long it took to generate the value. More...
 
const FLD_TIME = 3
 Key to the cache timestamp. More...
 
const FLD_TTL = 2
 Key to the original TTL. More...
 
const FLD_VALUE = 1
 Key to the cached value. More...
 
const FLD_VALUE_VERSION = 5
 Key to collection cache version number. More...
 
const GENERATION_HIGH_SEC = 0.2
 Consider value generation somewhat high if it takes this many seconds or more. More...
 
const GENERATION_SLOW_SEC = 3.0
 Consider value generation slow if it takes this many seconds or more. More...
 
const HOT_TTR = 900
 Expected time-till-refresh, in seconds, if the key is accessed once per second. More...
 
const INTERIM_KEY_TTL = 1
 Seconds to keep interim value keys for tombstoned keys around. More...
 
const LOCK_TTL = 10
 Seconds to keep lock keys around. More...
 
const LOW_TTL = 30
 Consider regeneration if the key will expire within this many seconds. More...
 
const MAX_COMMIT_DELAY = 3
 Max expected seconds to pass between delete() and DB commit finishing. More...
 
const MAX_READ_LAG = 7
 Max expected seconds of combined lag from replication and "view snapshots". More...
 
const PC_PRIMARY = 'primary:1000'
 Default process cache name and max key count. More...
 
const PURGE_HOLDOFF = 1
 Key to the tombstone entry hold-off TTL. More...
 
const PURGE_TIME = 0
 Key to the tombstone entry timestamp. More...
 
const PURGE_VAL_PREFIX = 'PURGED'
 Value prefix of purge values. More...
 
const RAMPUP_TTL = 30
 Seconds to ramp up the chance of regeneration due to expected time-till-refresh. More...
 
const RECENT_SET_HIGH_MS = 100
 Max millisecond set() backoff during hold-off (far less than INTERIM_KEY_TTL) More...
 
const RECENT_SET_LOW_MS = 50
 Min millisecond set() backoff during hold-off (far less than INTERIM_KEY_TTL) More...
 
const RES_METADATA = 1
 The key metadata component of a fetchMulti() result. More...
 
const RES_VALUE = 0
 The key value component of a fetchMulti() result. More...
 
const SCHEME_HASH_STOP = 2
 Use mcrouter-style Hash Stop key scheme (e.g. More...
 
const SCHEME_HASH_TAG = 1
 Use twemproxy-style Hash Tag key scheme (e.g. More...
 
const TSE_NONE = -1
 Idiom for getWithSetCallback() meaning "no cache stampede mutex". More...
 
const TYPE_COOLOFF = 'c'
 Single character component for cool-off bounce keys. More...
 
const TYPE_FLUX = 'f'
 Single character component for flux keys. More...
 
const TYPE_INTERIM = 'i'
 Single character component for interium value keys. More...
 
const TYPE_MUTEX = 'm'
 Single character component for mutex lock keys. More...
 
const TYPE_TIMESTAMP = 't'
 Single character component for timestamp check keys. More...
 
const TYPE_VALUE = 'v'
 Single character component for value keys. More...
 
const VERSION = 1
 Cache format version number. More...
 

Detailed Description

Multi-datacenter aware caching interface.

Using WANObjectCache

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(). The preferred way to do this logic is through getWithSetCallback(). When querying the store on cache miss, the closest DB replica should be used. Try to avoid heavyweight DB primary or quorum reads.

To ensure consumers of the cache see new values in a timely manner, you either 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 the consumer has access to an identifier that uniquely describes a value, cached value need not change. Instead, the key can change. This also allows all servers to access their perceived current version. This is important in context of multiple deployed versions of your application and/or cross-dc database replication, to ensure deterministic values without oscillation.
  • B) Validity is checked against the source after get(). This is the inverse of A. The unique identifier is embedded inside the value and validated after on retreival. If outdated, the value is recomputed.
  • C) The value is cached with a modest TTL (without validation). If value recomputation is reasonably performant, and the value is allowed to be stale, one should consider using TTL only – using the value's age as method of validation.

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. As purges are expensive, this strategy should be avoided if possible. The simplest purge method is delete().

No matter which strategy you choose, callers must not rely on updates or purges being immediately visible to other servers. It should be treated similarly as one would a database replica.

The need for immediate updates should be avoided. If needed, solutions must be sought outside WANObjectCache.

Deploying %WANObjectCache

There are two supported ways to set up broadcasted operations:

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".
  • f: used to store copies of temporary purge "tombstones" (only with onHostRoutingPrefix).
  • 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.
Since
1.26

Definition at line 123 of file WANObjectCache.php.

Constructor & Destructor Documentation

◆ __construct()

WANObjectCache::__construct ( array  $params)
Parameters
array$params
  • cache : BagOStuff object for a persistent cache
  • logger : LoggerInterface object
  • stats : StatsdDataFactoryInterface object
  • asyncHandler : A function that takes a callback and runs it later. If supplied, whenever a preemptive refresh would be triggered in getWithSetCallback(), the current cache value is still used instead. However, the async-handler function receives a WAN cache callback that, when run, will execute the value generation callback supplied by the getWithSetCallback() caller. The result will be saved as normal. The handler is expected to call the WAN cache callback at an opportune time (e.g. HTTP post-send), though generally within a few 100ms. [optional]
  • broadcastRoutingPrefix: a routing prefix used to broadcast "set" and "delete" operations to all datacenters; See also https://github.com/facebook/mcrouter/wiki/Config-Files for background on this. This prefix takes the form /<datacenter>/<name of wan route>/ where datacenter should generally be a wildcard, to select all matching routes (e.g. the WAN cluster in all DCs) See also https://github.com/facebook/mcrouter/wiki/Multi-cluster-broadcast-setup. This is required when using mcrouter as the backing store proxy. [optional]
  • onHostRoutingPrefix: a routing prefix that considers a server-local cache ("on-host tier") for "value" keys before reading from the main cache cluster in the current data center. The "helper" keys will still be read from the main cache cluster. An on-host tier can help reduce network saturation due to large value transfers yet without needing to explicitly know, opt-in, or measure which values are large. The on-host tier may blindy store and serve values from the main cluster for up to 10 seconds (must be less than WANObjectCache::HOLDOFF_TTL, as otherwise WANObjectCache will be unable to apply purges from the main cluster, which don't live longer than that). This prefix takes the form /<datacenter>/<name of onhost route>/ where datacenter may be a wildcard. This can be used with mcrouter. [optional]
  • epoch: lowest UNIX timestamp a value/tombstone must have to be valid. [optional]
  • secret: stable secret used for hashing long strings into key components. [optional]
  • coalesceScheme: which key scheme to use in order to encourage the backend to place any "helper" keys for a "value" key within the same cache server. This reduces network overhead and reduces the chance the a single downed cache server causes disruption. Use "hash_stop" with mcrouter and "hash_tag" with dynomite. [default: "hash_stop"]
  • keyHighQps: reads/second assumed during a hypothetical cache write stampede for a single key. This is used to decide when the overhead of checking short-lived write throttling keys is worth it. [default: 100]
  • keyHighUplinkBps: maximum tolerable bytes/second to spend on a cache write stampede for a single key. This is used to decide when the overhead of checking short-lived write throttling keys is worth it. [default: (1/100 of a 1Gbps link)]

Definition at line 345 of file WANObjectCache.php.

References SCHEME_HASH_STOP, SCHEME_HASH_TAG, and setLogger().

Member Function Documentation

◆ adaptiveTTL()

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:

// Last-modified time of page
$mtime = wfTimestamp( TS_UNIX, $page->getTimestamp() );
// Get adjusted TTL. If $mtime is 3600 seconds ago and $minTTL/$factor left at
// defaults, then $ttl is 3600 * .2 = 720. If $minTTL was greater than 720, then
// $ttl would be $minTTL. If $maxTTL was smaller than 720, $ttl would be $maxTTL.
$ttl = $cache->adaptiveTTL( $mtime, $cache::TTL_DAY );

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:

$query = "<some complex query>";
$idListFromComplexQuery = $cache->getWithSetCallback(
$cache->makeKey( 'complex-graph-query', $hashOfQuery ),
GraphQueryClass::STARTING_TTL,
function ( $oldValue, &$ttl, array &$setOpts, $oldAsOf ) use ( $query, $cache ) {
$gdb = $this->getReplicaGraphDbConnection();
// Account for any snapshot/replica DB lag
$setOpts += GraphDatabase::getCacheSetOptions( $gdb );
$newList = iterator_to_array( $gdb->query( $query ) );
sort( $newList, SORT_NUMERIC ); // normalize
$minTTL = GraphQueryClass::MIN_TTL;
$maxTTL = GraphQueryClass::MAX_TTL;
if ( $oldValue !== false ) {
// Note that $oldAsOf is the last time this callback ran
$ttl = ( $newList === $oldValue )
// No change: cache for 150% of the age of $oldValue
? $cache->adaptiveTTL( $oldAsOf, $maxTTL, $minTTL, 1.5 )
// Changed: cache for 50% of the age of $oldValue
: $cache->adaptiveTTL( $oldAsOf, $maxTTL, $minTTL, .5 );
}
return $newList;
},
[
// Keep stale values around for doing comparisons for TTL calculations.
// High values improve long-tail keys hit-rates, though might waste space.
'staleTTL' => GraphQueryClass::GRACE_TTL
]
);
Parameters
int | float$mtimeUNIX timestamp
int$maxTTLMaximum TTL (seconds)
int$minTTLMinimum TTL (seconds); Default: 30
float$factorValue in the range (0,1); Default: .2
Returns
int Adaptive TTL
Since
1.28

Definition at line 2635 of file WANObjectCache.php.

References getCurrentTime().

◆ checkAndSetCooloff()

WANObjectCache::checkAndSetCooloff (   $key,
  $kClass,
  $value,
  $elapsed,
  $hasLock 
)
private

Check whether set() is rate-limited to avoid concurrent I/O spikes.

This mitigates problems caused by popular keys suddenly becoming unavailable due to unexpected evictions or cache server outages. These cases are not handled by the usual preemptive refresh logic.

With a typical scale-out infrastructure, CPU and query load from getWithSetCallback() invocations is distributed among appservers and replica DBs, but cache operations for a given key route to a single cache server (e.g. striped consistent hashing). A set() stampede to a key can saturate the network link to its cache server. The intensity of the problem is proportionate to the value size and access rate. The duration of the problem is proportionate to value regeneration time.

Parameters
string$keyCache key made with makeKey()/makeGlobalKey()
string$kClass
mixed$valueThe regenerated value
float$elapsedSeconds spent fetching, validating, and regenerating the value
bool$hasLockWhether this thread has an exclusive regeneration lock
Returns
bool Whether it is OK to proceed with a key set operation

Definition at line 1901 of file WANObjectCache.php.

References $keyHighQps, $keyHighUplinkBps, and makeSisterKey().

Referenced by fetchOrRegenerate().

◆ claimStampedeLock()

WANObjectCache::claimStampedeLock (   $key)
private
Parameters
string$keyCache key made with makeKey()/makeGlobalKey()
Returns
bool Success

Definition at line 1787 of file WANObjectCache.php.

References makeSisterKey().

Referenced by fetchOrRegenerate().

◆ clearLastError()

WANObjectCache::clearLastError ( )
final

Clear the "last error" registry.

Definition at line 2526 of file WANObjectCache.php.

◆ clearProcessCache()

WANObjectCache::clearProcessCache ( )

Clear the in-process caches; useful for testing.

Since
1.27

Definition at line 2535 of file WANObjectCache.php.

◆ delete()

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.

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:

  • 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->startAtomic( __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 ) {
$cache->delete( $key );
} );
... <execute some stuff> ...
$dbw->endAtomic( __METHOD__ ); // end of request

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.

Parameters
string$keyCache key made with makeKey()/makeGlobalKey()
int$ttlTombstone TTL; Default: WANObjectCache::HOLDOFF_TTL
Returns
bool True if the item was purged or not found, false on failure

Definition at line 997 of file WANObjectCache.php.

References determineKeyClassForStats(), getCurrentTime(), makeSisterKey(), makeTombstonePurgeValue(), relayNonVolatilePurge(), and relayVolatilePurges().

◆ determineKeyClassForStats()

WANObjectCache::determineKeyClassForStats (   $key)
private
Parameters
string$keyString of the format <scope>:<collection>[:<constant or variable>]...
Returns
string A collection name to describe this class of key

Definition at line 2983 of file WANObjectCache.php.

Referenced by delete(), fetchOrRegenerate(), resetCheckKey(), and touchCheckKey().

◆ fetchKeys()

WANObjectCache::fetchKeys ( array  $keys,
array  $checkKeys 
)
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.

This returns a map of (key => result map), with entries for each key in $key. Result maps include the following fields:

  • WANObjectCache::RESULT_VALUE: the value; false if tombstoned/nonexistent
  • WANObjectCache::RESULT_ATTRIBUTES: the WANObjectCache::KEY_* metadata map
Parameters
string[]$keysList/map with makeKey()/makeGlobalKey() cache keys as values
string[] | string[][]$checkKeysMap of (integer or cache key => "check" key(s)); "check" keys must also be made with makeKey()/makeGlobalKey()
Returns
array<string,array{0:mixed,1:array}> Map of (key => result map) in order of $keys

Definition at line 544 of file WANObjectCache.php.

References $keys, $warmupCache, getCurrentTime(), KEY_CHECK_AS_OF, KEY_CUR_TTL, makeSisterKey(), processCheckKeys(), processFluxKeys(), PURGE_HOLDOFF, PURGE_TIME, and unwrap().

Referenced by fetchOrRegenerate(), get(), getMulti(), and getMultiWithUnionSetCallback().

◆ fetchOrRegenerate()

WANObjectCache::fetchOrRegenerate (   $key,
  $ttl,
  $callback,
array  $opts,
array  $cbParams 
)
private

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

See also
WANObjectCache::getWithSetCallback()
Parameters
string$keyCache key made with makeKey()/makeGlobalKey()
int$ttl
callable$callback
array$opts
array$cbParams
Returns
array Ordered list of the following:
  • Cached or regenerated value
  • Cached or regenerated value version number or null if not versioned
  • Timestamp of the current cached value at the key or null if there is no value
Note
Callable type hints are not used to avoid class-autoloading

Definition at line 1599 of file WANObjectCache.php.

References $callbackDepth, $res, AGE_NEW, checkAndSetCooloff(), claimStampedeLock(), determineKeyClassForStats(), fetchKeys(), getCurrentTime(), getInterimValue(), GRACE_TTL_NONE, HOT_TTR, isAliveOrInGracePeriod(), isValid(), isVolatileValueAgeNegligible(), KEY_AS_OF, KEY_CUR_TTL, KEY_TOMB_AS_OF, KEY_VERSION, RES_METADATA, RES_VALUE, resolveBusyValue(), resolveCTL(), resolveTouched(), scheduleAsyncRefresh(), setInterimValue(), STALE_TTL_NONE, TSE_NONE, worthRefreshExpiring(), worthRefreshPopular(), and yieldStampedeLock().

Referenced by getWithSetCallback(), and scheduleAsyncRefresh().

◆ fetchWrappedValuesForWarmupCache()

WANObjectCache::fetchWrappedValuesForWarmupCache ( array  $keys,
array  $checkKeys 
)
private
Parameters
string[]$keysCache keys made with makeKey()/makeGlobalKey()
string[] | string[][]$checkKeysMap of (integer or cache key => "check" key(s)); "check" keys must also be made with makeKey()/makeGlobalKey()
Returns
array<string,mixed> Map of (sister key => value, or, false if not found)

Definition at line 3087 of file WANObjectCache.php.

References $keys, makeSisterKey(), and makeSisterKeys().

Referenced by getMultiWithSetCallback(), and getMultiWithUnionSetCallback().

◆ get()

WANObjectCache::get (   $key,
$curTTL = null,
array  $checkKeys = [],
$info = [] 
)
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 invalidated by $checkKeys
  • b) float (>=0); if $key exists, has a TTL, and is not invalidated by $checkKeys
  • c) float (<0); if $key is tombstoned, stale, or existing but invalidated 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:

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:

Parameters
string$keyCache key made with makeKey()/makeGlobalKey()
float | null&$curTTLSeconds of TTL left [returned]
string[]$checkKeysMap of (integer or cache key => "check" key(s)); "check" keys must also be made with makeKey()/makeGlobalKey()
array&$infoMetadata map [returned]
Returns
mixed Value of cache key; false on failure

Definition at line 448 of file WANObjectCache.php.

References $res, fetchKeys(), getCurrentTime(), KEY_AS_OF, KEY_CUR_TTL, PASS_BY_REF, RES_METADATA, and RES_VALUE.

◆ getCheckKeyTime()

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$keyCache key made with makeKey()/makeGlobalKey()
Returns
float UNIX timestamp

Definition at line 1063 of file WANObjectCache.php.

References getMultiCheckKeyTime().

◆ getCollectionFromSisterKey()

static WANObjectCache::getCollectionFromSisterKey ( string  $sisterKey)
static
Parameters
string$sisterKeySister key from makeSisterKey()
Returns
string Key collection name
Access: internal
For use by WANObjectCache/BagOStuff only
Since
1.36

Definition at line 1858 of file WANObjectCache.php.

◆ getCurrentTime()

WANObjectCache::getCurrentTime ( )
protected
Returns
float UNIX timestamp

Definition at line 3139 of file WANObjectCache.php.

References $wallClockOverride.

Referenced by adaptiveTTL(), delete(), fetchKeys(), fetchOrRegenerate(), get(), getMultiCheckKeyTime(), set(), touchCheckKey(), and yieldStampedeLock().

◆ getInterimValue()

WANObjectCache::getInterimValue (   $key,
  $minAsOf,
  $now 
)
private
Parameters
string$keyCache key made with makeKey()/makeGlobalKey()
float$minAsOfMinimum acceptable "as of" timestamp
float$nowFetch time to determine "age" metadata
Returns
array (cached value or false, cache key metadata map)

Definition at line 2000 of file WANObjectCache.php.

References isValid(), makeSisterKey(), unwrap(), and useInterimHoldOffCaching().

Referenced by fetchOrRegenerate().

◆ getLastError()

WANObjectCache::getLastError ( )
final

◆ getMulti()

WANObjectCache::getMulti ( array  $keys,
$curTTLs = [],
array  $checkKeys = [],
$info = [] 
)
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.

See also
WANObjectCache::get()
Parameters
string[]$keysList/map with makeKey()/makeGlobalKey() cache keys as values
array<string,float>&$curTTLs Map of (key => seconds of TTL left) [returned]
string[] | string[][]$checkKeysMap 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]
Returns
array<string,mixed> Map of (key => value) for existing values in order of $keys

Definition at line 494 of file WANObjectCache.php.

References $res, fetchKeys(), KEY_AS_OF, KEY_CUR_TTL, PASS_BY_REF, RES_METADATA, and RES_VALUE.

◆ getMultiCheckKeyTime()

WANObjectCache::getMultiCheckKeyTime ( array  $keys)
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:

  • a) a class of entities each depend on hundreds of other entities
  • b) these other entities are depended upon by millions of entities

The later entities can each use a "check" key to invalidate 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:

$cache->makeGlobalKey( 'wikibase-item', $id ),
self::INITIAL_TTV, // initial time-till-verify
function ( $oldValue, &$ttv, &$setOpts, $oldAsOf ) use ( $checkKeys, $cache ) {
$now = microtime( true );
// Use $oldValue if it passes max ultimate age and "check" key comparisons
if ( $oldValue &&
$oldAsOf > max( $cache->getMultiCheckKeyTime( $checkKeys ) ) &&
( $now - $oldValue['ctime'] ) <= self::MAX_CACHE_AGE
) {
// Increase time-till-verify by 50% of last time to reduce overhead
$ttv = $cache->adaptiveTTL( $oldAsOf, self::MAX_TTV, self::MIN_TTV, 1.5 );
// Unlike $oldAsOf, "ctime" is the ultimate age of the cached data
return $oldValue;
}
$mtimes = []; // dependency last-modified times; passed by reference
$value = [ 'data' => $this->fetchEntityData( $mtimes ), 'ctime' => $now ];
// Guess time-till-change among the dependencies, e.g. 1/(total change rate)
$ttc = 1 / array_sum( array_map(
function ( $mtime ) use ( $now ) {
return 1 / ( $mtime ? ( $now - $mtime ) : 900 );
},
$mtimes
) );
// The time-to-verify should not be overly pessimistic nor optimistic
$ttv = min( max( $ttc, self::MIN_TTV ), self::MAX_TTV );
return $value;
},
[ 'staleTTL' => $cache::TTL_DAY ] // keep around to verify and re-save
);
See also
WANObjectCache::getCheckKeyTime()
WANObjectCache::getWithSetCallback()
Parameters
string[]$keysCache keys made with makeKey()/makeGlobalKey()
Returns
float[] Map of (key => UNIX timestamp)
Since
1.31

Definition at line 1128 of file WANObjectCache.php.

References $keys, getCurrentTime(), makeCheckPurgeValue(), makeSisterKey(), parsePurgeValue(), and PURGE_TIME.

Referenced by getCheckKeyTime().

◆ getMultiWithSetCallback()

WANObjectCache::getMultiWithSetCallback ( ArrayIterator  $keyedIds,
  $ttl,
callable  $callback,
array  $opts = [] 
)
final

Method to fetch multiple cache keys at once with regeneration.

This works the same as getWithSetCallback() except:

  • a) The $keys argument must be the result of WANObjectCache::makeMultiKeys()
  • b) The $callback argument must be a callback that takes the following arguments:
    • $id: ID of the entity to query
    • $oldValue: prior cache value or false if none was present
    • &$ttl: reference to the TTL to be assigned to the new value (alterable)
    • &$setOpts: reference to the new value set() options (alterable)
    • oldAsOf
      generation UNIX timestamp of
      oldValue or null if not present
  • c) The return value is a map of (cache key => value) in the order of $keyedIds
See also
WANObjectCache::getWithSetCallback()
WANObjectCache::getMultiWithUnionSetCallback()

Example usage:

$rows = $cache->getMultiWithSetCallback(
// Map of cache keys to entity IDs
$cache->makeMultiKeys(
$this->fileVersionIds(),
function ( $id ) use ( $cache ) {
return $cache->makeKey( 'file-version', $id );
}
),
// Time-to-live (in seconds)
$cache::TTL_DAY,
// Function that derives the new key value
function ( $id, $oldValue, &$ttl, array &$setOpts ) {
// Account for any snapshot/replica DB lag
$setOpts += Database::getCacheSetOptions( $dbr );
// Load the row for this file
$queryInfo = File::getQueryInfo();
$row = $dbr->selectRow(
$queryInfo['tables'],
$queryInfo['fields'],
[ 'id' => $id ],
__METHOD__,
[],
$queryInfo['joins']
);
return $row ? (array)$row : false;
},
[
// Process cache for 30 seconds
'pcTTL' => 30,
// Use a dedicated 500 item cache (initialized on-the-fly)
'pcGroup' => 'file-versions:500'
]
);
$files = array_map( [ __CLASS__, 'newFromRow' ], $rows );
Parameters
ArrayIterator$keyedIdsResult of WANObjectCache::makeMultiKeys()
int$ttlSeconds to live for key updates
callable$callbackCallback the yields entity generation callbacks
array$optsOptions map
Returns
mixed[] Map of (cache key => value) in the same order as $keyedIds
Since
1.28

Definition at line 2109 of file WANObjectCache.php.

References fetchWrappedValuesForWarmupCache(), getNonProcessCachedMultiKeys(), and getWithSetCallback().

◆ getMultiWithUnionSetCallback()

WANObjectCache::getMultiWithUnionSetCallback ( ArrayIterator  $keyedIds,
  $ttl,
callable  $callback,
array  $opts = [] 
)
final

Method to fetch/regenerate multiple cache keys at once.

This works the same as getWithSetCallback() except:

  • a) The $keys argument expects the result of WANObjectCache::makeMultiKeys()
  • b) The $callback argument expects a callback returning a map of (ID => new value) for all entity IDs in $ids and it takes the following arguments:
    • $ids: list of entity IDs that require value generation
    • &$ttls: reference to the (entity ID => new TTL) map (alterable)
    • &$setOpts: reference to the new value set() options (alterable)
  • c) The return value is a map of (cache key => value) in the order of $keyedIds
  • d) The "lockTSE" and "busyValue" options are ignored
See also
WANObjectCache::getWithSetCallback()
WANObjectCache::getMultiWithSetCallback()

Example usage:

$rows = $cache->getMultiWithUnionSetCallback(
// Map of cache keys to entity IDs
$cache->makeMultiKeys(
$this->fileVersionIds(),
function ( $id ) use ( $cache ) {
return $cache->makeKey( 'file-version', $id );
}
),
// Time-to-live (in seconds)
$cache::TTL_DAY,
// Function that derives the new key value
function ( array $ids, array &$ttls, array &$setOpts ) {
// Account for any snapshot/replica DB lag
$setOpts += Database::getCacheSetOptions( $dbr );
// Load the rows for these files
$rows = [];
$queryInfo = File::getQueryInfo();
$res = $dbr->select(
$queryInfo['tables'],
$queryInfo['fields'],
[ 'id' => $ids ],
__METHOD__,
[],
$queryInfo['joins']
);
foreach ( $res as $row ) {
$rows[$row->id] = $row;
$mtime = wfTimestamp( TS_UNIX, $row->timestamp );
$ttls[$row->id] = $this->adaptiveTTL( $mtime, $ttls[$row->id] );
}
return $rows;
},
]
);
$files = array_map( [ __CLASS__, 'newFromRow' ], $rows );
Parameters
ArrayIterator$keyedIdsResult of WANObjectCache::makeMultiKeys()
int$ttlSeconds to live for key updates
callable$callbackCallback the yields entity generation callbacks
array$optsOptions map
Returns
mixed[] Map of (cache key => value) in the same order as $keyedIds
Since
1.30

Definition at line 2210 of file WANObjectCache.php.

References $res, fetchKeys(), fetchWrappedValuesForWarmupCache(), getNonProcessCachedMultiKeys(), getWithSetCallback(), RES_METADATA, and RES_VALUE.

◆ getNonProcessCachedMultiKeys()

WANObjectCache::getNonProcessCachedMultiKeys ( ArrayIterator  $keys,
array  $opts 
)
private
Parameters
ArrayIterator$keys
array$opts
Returns
string[] Map of (ID => cache key)

Definition at line 3065 of file WANObjectCache.php.

References $keys, and getProcessCache().

Referenced by getMultiWithSetCallback(), and getMultiWithUnionSetCallback().

◆ getProcessCache()

WANObjectCache::getProcessCache (   $group)
private
Parameters
string$group
Returns
MapCacheLRU

Definition at line 3048 of file WANObjectCache.php.

Referenced by getNonProcessCachedMultiKeys(), and getWithSetCallback().

◆ getQoS()

WANObjectCache::getQoS (   $flag)
Parameters
int$flagATTR_* class constant
Returns
int QOS_* class constant
Since
1.28

Definition at line 2568 of file WANObjectCache.php.

Referenced by MediaWiki\Storage\SqlBlobStore\getCacheTTL().

◆ getWarmupKeyMisses()

WANObjectCache::getWarmupKeyMisses ( )
final
Returns
int Number of warmup key cache misses last round
Since
1.30

Definition at line 2653 of file WANObjectCache.php.

References $warmupKeyMisses.

◆ getWithSetCallback()

WANObjectCache::getWithSetCallback (   $key,
  $ttl,
  $callback,
array  $opts = [],
array  $cbParams = [] 
)
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:

  • $oldValue: prior cache value or false if none was present
  • &$ttl: alterable reference to the TTL to be assigned to the new value
  • &$setOpts: alterable reference to the set() options to be used with the new value
  • oldAsOf
    generation UNIX timestamp of
    oldValue or null if not present (since 1.28)
  • params
    custom field/value map as defined by
    cbParams (since 1.35)

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:

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

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):

// 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/replica DB lag
$setOpts += Database::getCacheSetOptions( $dbr );
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/replica DB lag
$setOpts += Database::getCacheSetOptions( $dbr );
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,
// Avoid querying cache servers multiple times in a web request
'pcTTL' => $cache::TTL_PROC_LONG
]
);

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/replica DB lag
$setOpts += Database::getCacheSetOptions( $dbr );
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 (key that is expensive with too many DB dependencies for "check" keys):

// Key to store the cached value under
$cache->makeKey( 'cat-toys', $catId ),
// 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/replica DB lag
$setOpts += Database::getCacheSetOptions( $dbr );
return CatToys::newFromResults( $dbr->select( ... ) );
},
[
// Get the highest timestamp of any of the cat's toys
'touchedCallback' => function ( $value ) use ( $catId ) {
$ts = $dbr->selectField( 'cat_toys', 'MAX(ct_touched)', ... );
return wfTimestampOrNull( TS_UNIX, $ts );
},
// Avoid DB queries for repeated access
'pcTTL' => $cache::TTL_PROC_SHORT
]
);

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/replica DB lag
$setOpts += Database::getCacheSetOptions( $dbr );
// 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,
// Use a magic value when no cache value is ready rather than stampeding
'busyValue' => 'computing'
]
);

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):

$catSituationTolerabilityCache = $this->cache->getWithSetCallback(
// Group by constraint ID/hash, cat family ID/hash, or something else useful
$this->cache->makeKey( 'cat-situation-tolerability-checks', $groupKey ),
WANObjectCache::TTL_DAY, // rarely used groups should fade away
// The $scenarioKey format is $constraintId:<ID/hash of $situation>
function ( $cacheMap ) use ( $scenarioKey, $constraintId, $situation ) {
$lruCache = MapCacheLRU::newFromArray( $cacheMap ?: [], self::CACHE_SIZE );
$result = $lruCache->get( $scenarioKey ); // triggers LRU bump if present
if ( $result === null || $this->isScenarioResultExpired( $result ) ) {
$result = $this->checkScenarioTolerability( $constraintId, $situation );
$lruCache->set( $scenarioKey, $result, 3 / 8 );
}
// Save the new LRU cache map and reset the map's TTL
return $lruCache->toArray();
},
[
// Once map is > 1 sec old, consider refreshing
'ageNew' => 1,
// Update within 5 seconds after "ageNew" given a 1hz cache check rate
'hotTTR' => 5,
// Avoid querying cache servers multiple times in a request; this also means
// that a request can only alter the value of any given constraint key once
'pcTTL' => WANObjectCache::TTL_PROC_LONG
]
);
$tolerability = isset( $catSituationTolerabilityCache[$scenarioKey] )
? $catSituationTolerabilityCache[$scenarioKey]
: $this->checkScenarioTolerability( $constraintId, $situation );
See also
WANObjectCache::get()
WANObjectCache::set()
Parameters
string$keyCache key made with makeKey()/makeGlobalKey()
int$ttlNominal seconds-to-live for newly computed values. Special values are:
  • WANObjectCache::TTL_INDEFINITE: Cache forever (subject to LRU-style evictions)
  • WANObjectCache::TTL_UNCACHEABLE: Do not cache (if the key exists, it is not deleted)
callable$callbackValue generation function
array$optsOptions map:
  • checkKeys: List of "check" keys. The key at $key will be seen as stale when either touchCheckKey() or resetCheckKey() is called on any of the keys in this list. This is useful if thousands or millions of keys depend on the same entity. The entity can simply have its "check" key updated whenever the entity is modified. Default: [].
  • graceTTL: If the key is invalidated (by "checkKeys" or "touchedCallback") less than this many seconds ago, consider reusing the stale value. The odds of a refresh become more likely over time, becoming certain once the grace period is reached. This can reduce traffic spikes when millions of keys are compared to the same "check" key and touchCheckKey() or resetCheckKey() is called on that "check" key. This option is not useful for avoiding traffic spikes in the case of the key simply expiring on account of its TTL (use "lowTTL" instead). Default: WANObjectCache::GRACE_TTL_NONE.
  • lockTSE: Prefer the use of a mutex during value regeneration of the key if its TSE ("time since expiry") is less than the given number of seconds ago. The TSE is influenced by deletion, invalidation (e.g. by "checkKeys" or "touchedCallback"), and various other options (e.g. "staleTTL"). A low enough TSE is assumed to indicate a high enough key access rate to justify stampede avoidance. A thread that tries and fails to acquire the mutex will use a stale value for the key, if there is one, and, if not, it will execute the callback. Note that no cache value exists after deletion or storage-layer expiration/eviction; to prevent stampedes during these cases, avoid using delete(), keep "lowTTL" enabled, and consider using "busyValue". Default: WANObjectCache::TSE_NONE.
  • busyValue: Specify a placeholder value to use when no value exists and another thread is currently regenerating it. This assures that cache stampedes cannot happen if the value falls out of cache. This also mitigates stampedes when value regeneration becomes very slow (greater than $ttl/"lowTTL"). If this is a closure, then it will be invoked to get the placeholder when needed. Default: null.
  • pcTTL: Process cache the value in this PHP instance for this many seconds. This avoids network I/O when a key is read several times. This will not cache when the callback returns false, however. Note that any purges will not be seen while process cached; since the callback should use replica DBs and they may be lagged or have snapshot isolation anyway, this should not typically matter. Default: WANObjectCache::TTL_UNCACHEABLE.
  • pcGroup: Process cache group to use instead of the primary one. If set, this must be of the format ALPHANUMERIC_NAME:MAX_KEY_SIZE, e.g. "mydata:10". Use this for storing large values, small yet numerous values, or some values with a high cost of eviction. It is generally preferable to use a class constant when setting this value. This has no effect unless pcTTL is used. Default: WANObjectCache::PC_PRIMARY.
  • version: Integer version number. This lets callers make breaking changes to the format of cached values without causing problems for sites that use non-instantaneous code deployments. Old and new code will recognize incompatible versions and purges from both old and new code will been seen by each other. When this method encounters an incompatibly versioned value at the provided key, a "variant key" will be used for reading from and saving to cache. The variant key is specific to the key and version number provided to this method. If the variant key value is older than that of the provided key, or the provided key is non-existant, then the variant key will be seen as non-existant. Therefore, delete() calls invalidate the provided key's variant keys. The "checkKeys" and "touchedCallback" options still apply to variant keys as usual. Avoid storing class objects, as this reduces compatibility (due to serialization). Default: null.
  • minAsOf: Reject values if they were generated before this UNIX timestamp. This is useful if the source of a key is suspected of having possibly changed recently, and the caller wants any such changes to be reflected. Default: WANObjectCache::MIN_TIMESTAMP_NONE.
  • hotTTR: Expected time-till-refresh (TTR) in seconds for keys that average ~1 hit per second (e.g. 1Hz). Keys with a hit rate higher than 1Hz will refresh sooner than this TTR and vise versa. Such refreshes won't happen until keys are "ageNew" seconds old. This uses randomization to avoid triggering cache stampedes. The TTR is useful at reducing the impact of missed cache purges, since the effect of a heavily referenced key being stale is worse than that of a rarely referenced key. Unlike simply lowering $ttl, seldomly used keys are largely unaffected by this option, which makes it possible to have a high hit rate for the "long-tail" of less-used keys. Default: WANObjectCache::HOT_TTR.
  • lowTTL: Consider pre-emptive updates when the current TTL (seconds) of the key is less than this. It becomes more likely over time, becoming certain once the key is expired. This helps avoid cache stampedes that might be triggered due to the key expiring. Default: WANObjectCache::LOW_TTL.
  • ageNew: Consider popularity refreshes only once a key reaches this age in seconds. Default: WANObjectCache::AGE_NEW.
  • staleTTL: Seconds to keep the key around if it is stale. This means that on cache miss the callback may get $oldValue/$oldAsOf values for keys that have already been expired for this specified time. This is useful if adaptiveTTL() is used on the old value's as-of time when it is verified as still being correct. Default: WANObjectCache::STALE_TTL_NONE
  • touchedCallback: A callback that takes the current value and returns a UNIX timestamp indicating the last time a dynamic dependency changed. Null can be returned if there are no relevant dependency changes to check. This can be used to check against things like last-modified times of files or DB timestamp fields. This should generally not be used for small and easily queried values in a DB if the callback itself ends up doing a similarly expensive DB query to check a timestamp. Usages of this option makes the most sense for values that are moderately to highly expensive to regenerate and easy to query for dependency timestamps. The use of "pcTTL" reduces timestamp queries. Default: null.
array$cbParamsCustom field/value map to pass to the callback (since 1.35) @phpcs:ignore Generic.Files.LineLength
Returns
mixed Value found or written to the key
Note
Options added in 1.28: version, busyValue, hotTTR, ageNew, pcGroup, minAsOf
Options added in 1.31: staleTTL, graceTTL
Options added in 1.33: touchedCallback
Callable type hints are not used to avoid class-autoloading

Definition at line 1539 of file WANObjectCache.php.

References $res, fetchOrRegenerate(), getProcessCache(), and makeGlobalKey().

Referenced by getMultiWithSetCallback(), and getMultiWithUnionSetCallback().

◆ hash256()

WANObjectCache::hash256 (   $component)

Hash a possibly long string into a suitable component for makeKey()/makeGlobalKey()

Parameters
string$componentA raw component used in building a cache key
Returns
string 64 character HMAC using a stable secret for public collision resistance
Since
1.34

Definition at line 2382 of file WANObjectCache.php.

◆ isAliveOrInGracePeriod()

WANObjectCache::isAliveOrInGracePeriod (   $curTTL,
  $graceTTL 
)
private

Check if a key is fresh or in the grace window and thus due for randomized reuse.

If $curTTL > 0 (e.g. value not expired) then this returns true. If $curTTL <= -$graceTTL (e.g. value out of grace) then this returns false. Otherwise, the chance of this returning true decreases steadily from 100% to 0% as the |$curTTL| moves from 0 to $graceTTL seconds.

This approach handles widely varying levels of cache access traffic.

Parameters
float$curTTLApproximate TTL left on the key
int$graceTTLConsider using stale values if $curTTL is greater than this
Returns
bool

Definition at line 2775 of file WANObjectCache.php.

References worthRefreshExpiring().

Referenced by fetchOrRegenerate().

◆ isValid()

WANObjectCache::isValid (   $value,
  $asOf,
  $minAsOf,
  $purgeTime = null 
)
protected

Check if $value is not false, versioned (if needed), and not older than $minTime (if set)

Parameters
array | bool$value
float$asOfThe time $value was generated
float$minAsOfMinimum acceptable "as of" timestamp
float | null$purgeTimeThe last time the value was invalidated
Returns
bool

Definition at line 2883 of file WANObjectCache.php.

Referenced by fetchOrRegenerate(), and getInterimValue().

◆ isVolatileValueAgeNegligible()

WANObjectCache::isVolatileValueAgeNegligible (   $age)
private
Parameters
float$ageAge of volatile/interim key in seconds
Returns
bool Whether the age of a volatile value is negligible

Definition at line 1876 of file WANObjectCache.php.

Referenced by fetchOrRegenerate().

◆ makeCheckPurgeValue()

WANObjectCache::makeCheckPurgeValue ( float  $timestamp,
int  $holdoff,
array &  $purge = null 
)
private
Parameters
float$timestampUNIX timestamp
int$holdoffIn seconds
array | null&$purgeUnwrapped purge value array [returned]
Returns
string Wrapped purge value; format is "PURGED:<timestamp>:<holdoff>"

Definition at line 3036 of file WANObjectCache.php.

Referenced by getMultiCheckKeyTime(), processCheckKeys(), and touchCheckKey().

◆ makeGlobalKey()

WANObjectCache::makeGlobalKey (   $collection,
  $components 
)

Make a cache key for the global keyspace and given components.

See also
IStoreKeyEncoder::makeGlobalKey()
Parameters
string$collectionKey collection name component
string|int...$components Additional, ordered, key components for entity IDs
Returns
string Colon-separated, keyspace-prepended, ordered list of encoded components
Since
1.27

Implements IStoreKeyEncoder.

Definition at line 2357 of file WANObjectCache.php.

Referenced by getWithSetCallback().

◆ makeKey()

WANObjectCache::makeKey (   $collection,
  $components 
)

Make a cache key using the "global" keyspace for the given components.

See also
IStoreKeyEncoder::makeKey()
Parameters
string$collectionKey collection name component
string|int...$components Additional, ordered, key components for entity IDs
Returns
string Colon-separated, keyspace-prepended, ordered list of encoded components
Since
1.27

Implements IStoreKeyEncoder.

Definition at line 2371 of file WANObjectCache.php.

◆ makeMultiKeys()

WANObjectCache::makeMultiKeys ( array  $ids,
  $keyCallback 
)
final

Get an iterator of (cache key => entity ID) for a list of entity IDs.

The callback takes an ID string and returns a key 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. If hashing is needed, then use the hash256() method.

Example usage for the default keyspace:

$keyedIds = $cache->makeMultiKeys(
function ( $module ) use ( $cache ) {
return $cache->makeKey( 'module-info', $module );
}
);

Example usage for mixed default and global keyspace:

$keyedIds = $cache->makeMultiKeys(
$filters,
function ( $filter ) use ( $cache ) {
return ( strpos( $filter, 'central:' ) === 0 )
? $cache->makeGlobalKey( 'regex-filter', $filter )
: $cache->makeKey( 'regex-filter', $filter )
}
);

Example usage with hashing:

$keyedIds = $cache->makeMultiKeys(
$urls,
function ( $url ) use ( $cache ) {
return $cache->makeKey( 'url-info', $cache->hash256( $url ) );
}
);
See also
WANObjectCache::makeKey()
WANObjectCache::makeGlobalKey()
WANObjectCache::hash256()
Parameters
string[] | int[]$idsList of entity IDs
callable$keyCallbackFunction returning makeKey()/makeGlobalKey() on the input ID
Returns
ArrayIterator Iterator of (cache key => ID); order of $ids is preserved
Exceptions
UnexpectedValueException
Since
1.28

Definition at line 2436 of file WANObjectCache.php.

◆ makeSisterKey()

WANObjectCache::makeSisterKey ( string  $baseKey,
string  $typeChar,
string  $route = null 
)
private

Get a sister key that should be collocated with a base cache key.

The keys will bear the WANCache prefix and use the configured coalescing scheme

Parameters
string$baseKeyCache key made with makeKey()/makeGlobalKey()
string$typeCharConsistent hashing agnostic suffix character matching [a-zA-Z]
string | null$routeRouting prefix (optional)
Returns
string Sister key

Definition at line 1836 of file WANObjectCache.php.

References prependRoute().

Referenced by checkAndSetCooloff(), claimStampedeLock(), delete(), fetchKeys(), fetchWrappedValuesForWarmupCache(), getInterimValue(), getMultiCheckKeyTime(), makeSisterKeys(), reap(), reapCheckKey(), resetCheckKey(), set(), setInterimValue(), touchCheckKey(), and yieldStampedeLock().

◆ makeSisterKeys()

WANObjectCache::makeSisterKeys ( array  $baseKeys,
string  $type,
string  $route = null 
)
private

Get sister keys that should be collocated with their corresponding base cache keys.

The key will bear the WANCache prefix and use the configured coalescing scheme

Parameters
string[]$baseKeysCache keys made with makeKey()/makeGlobalKey()
string$typeConsistent hashing agnostic suffix character matching [a-zA-Z]
string | null$routeRouting prefix (optional)
Returns
string[] Order-corresponding list of sister keys

Definition at line 1817 of file WANObjectCache.php.

References $type, and makeSisterKey().

Referenced by fetchWrappedValuesForWarmupCache().

◆ makeTombstonePurgeValue()

WANObjectCache::makeTombstonePurgeValue ( float  $timestamp)
private
Parameters
float$timestampUNIX timestamp
Returns
string Wrapped purge value; format is "PURGED:<timestamp>"

Definition at line 3026 of file WANObjectCache.php.

Referenced by delete().

◆ multiRemap()

WANObjectCache::multiRemap ( array  $ids,
array  $res 
)
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 utitilize the full entity ID in the key (not a hash of it).

Example usage:

$poems = $cache->getMultiWithSetCallback(
$cache->makeMultiKeys(
$uuids,
function ( $uuid ) use ( $cache ) {
return $cache->makeKey( 'poem', $uuid );
}
),
$cache::TTL_DAY,
function ( $uuid ) use ( $url ) {
return $this->http->run( [ 'method' => 'GET', 'url' => "$url/$uuid" ] );
}
);
$poemsByUUID = $cache->multiRemap( $uuids, $poems );
See also
WANObjectCache::makeMultiKeys()
WANObjectCache::getMultiWithSetCallback()
WANObjectCache::getMultiWithUnionSetCallback()
Parameters
string[] | int[]$idsEntity ID list makeMultiKeys()
mixed[]$resResult of getMultiWithSetCallback()/getMultiWithUnionSetCallback()
Returns
mixed[] Map of (ID => value); order of $ids is preserved
Since
1.34

Definition at line 2492 of file WANObjectCache.php.

References $res.

◆ newEmpty()

◆ parsePurgeValue()

WANObjectCache::parsePurgeValue (   $value)
private

Extract purge metadata from cached value if it is a valid purge value.

Valid purge values come from makeTombstonePurgeValue()/makeCheckKeyPurgeValue()

Parameters
mixed$valueCached value
Returns
array|null Tuple of (UNIX timestamp, hold-off seconds); null if value is invalid

Definition at line 2998 of file WANObjectCache.php.

Referenced by getMultiCheckKeyTime(), processCheckKeys(), processFluxKeys(), reapCheckKey(), and unwrap().

◆ prependRoute()

WANObjectCache::prependRoute ( string  $sisterKey,
string  $route 
)
protected
Parameters
string$sisterKeySister key
string$routeKey routing prefix
Returns
string

Definition at line 2715 of file WANObjectCache.php.

Referenced by makeSisterKey(), relayNonVolatilePurge(), and relayVolatilePurges().

◆ processCheckKeys()

WANObjectCache::processCheckKeys ( array  $checkSisterKeys,
array  $wrappedBySisterKey,
float  $now 
)
private
Parameters
string[]$checkSisterKeysList of "check" sister keys
mixed[]$wrappedBySisterKeyPreloaded map of (sister key => wrapped value)
float$nowUNIX timestamp
Returns
array[] List of purge value arrays

Definition at line 703 of file WANObjectCache.php.

References makeCheckPurgeValue(), and parsePurgeValue().

Referenced by fetchKeys().

◆ processFluxKeys()

WANObjectCache::processFluxKeys ( array  $keys,
array  $fluxSisterKeys,
array  $wrappedBySisterKey 
)
private
Parameters
string[]$keysBase key list
string[]$fluxSisterKeysOrder-corresponding "flux" key list for base keys or []
mixed[]$wrappedBySisterKeyPreloaded map of (sister key => wrapped value)
Returns
array[] List of purge value arrays

Definition at line 672 of file WANObjectCache.php.

References $keys, and parsePurgeValue().

Referenced by fetchKeys().

◆ reap()

WANObjectCache::reap (   $key,
  $purgeTimestamp,
$isStale = false 
)
final

Set a key to soon expire in the local cluster if it pre-dates $purgeTimestamp.

This sets stale keys' time-to-live at HOLDOFF_TTL seconds, which both avoids broadcasting in mcrouter setups and also avoids races with new tombstones.

Parameters
string$keyCache key made with makeKey()/makeGlobalKey()
int$purgeTimestampUNIX timestamp of purge
bool&$isStaleWhether the key is stale
Returns
bool Success
Since
1.28

Definition at line 2295 of file WANObjectCache.php.

References HOLDOFF_TTL, and makeSisterKey().

◆ reapCheckKey()

WANObjectCache::reapCheckKey (   $key,
  $purgeTimestamp,
$isStale = false 
)
final

Set a "check" key to soon expire in the local cluster if it pre-dates $purgeTimestamp.

Parameters
string$keyCache key made with makeKey()/makeGlobalKey()
int$purgeTimestampUNIX timestamp of purge
bool&$isStaleWhether the key is stale
Returns
bool Success
Since
1.28

Definition at line 2326 of file WANObjectCache.php.

References makeSisterKey(), and parsePurgeValue().

◆ relayNonVolatilePurge()

WANObjectCache::relayNonVolatilePurge ( string  $sisterKey)
protected

Remove a sister key from all datacenters.

This method should not wait for the operation to complete on remote datacenters

Parameters
string$sisterKeyA value, "check", or flux sister key
Returns
bool Success

Definition at line 2700 of file WANObjectCache.php.

References prependRoute().

Referenced by delete(), and resetCheckKey().

◆ relayVolatilePurges()

WANObjectCache::relayVolatilePurges ( array  $purgeBySisterKey,
int  $ttl 
)
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).

Parameters
array<string,string>$purgeBySisterKey Map of (sister key => result of makeTombstonePurgeValue()/makeCheckKeyPurgeValue())
int$ttlSeconds to keep the purge value around
Returns
bool Success

Definition at line 2671 of file WANObjectCache.php.

References prependRoute().

Referenced by delete(), and touchCheckKey().

◆ resetCheckKey()

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 "check" key 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 stale, but not for how long (they are treated as "just" purged), which effects any lockTSE logic in getWithSetCallback()
  • c) Since "check" keys are initialized only on the server the key hashes to, any temporary ejection of that server will cause the value to be seen as purged as a new server will initialize the "check" key.

The advantage here is that the "check" keys, which have high TTLs, will only be created when a get*() method actually uses that key. This is better when a large number of "check" keys are invalided in a short period of time.

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

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

Definition at line 1226 of file WANObjectCache.php.

References determineKeyClassForStats(), makeSisterKey(), and relayNonVolatilePurge().

◆ resolveBusyValue()

WANObjectCache::resolveBusyValue (   $busyValue)
private
Parameters
mixed$busyValue
Returns
mixed

Definition at line 2041 of file WANObjectCache.php.

Referenced by fetchOrRegenerate().

◆ resolveCTL()

WANObjectCache::resolveCTL (   $value,
  $curTTL,
  $curInfo,
  $touchedCallback 
)
private
Parameters
mixed$value
float | null$curTTL
array$curInfo
callable | null$touchedCallback
Returns
array (current time left or null, UNIX timestamp of last purge or null)
Note
Callable type hints are not used to avoid class-autoloading

Definition at line 1958 of file WANObjectCache.php.

Referenced by fetchOrRegenerate().

◆ resolveTouched()

WANObjectCache::resolveTouched (   $value,
  $lastPurge,
  $touchedCallback 
)
private
Parameters
mixed$value
float | null$lastPurge
callable | null$touchedCallback
Returns
float|null UNIX timestamp of last purge or null
Note
Callable type hints are not used to avoid class-autoloading

Definition at line 1988 of file WANObjectCache.php.

Referenced by fetchOrRegenerate().

◆ scheduleAsyncRefresh()

WANObjectCache::scheduleAsyncRefresh (   $key,
  $ttl,
  $callback,
array  $opts,
array  $cbParams 
)
private

Schedule a deferred cache regeneration if possible.

Parameters
string$keyCache key made with makeKey()/makeGlobalKey()
int$ttlSeconds to live
callable$callback
array$opts
array$cbParams
Returns
bool Success
Note
Callable type hints are not used to avoid class-autoloading

Definition at line 2734 of file WANObjectCache.php.

References $asyncHandler, and fetchOrRegenerate().

Referenced by fetchOrRegenerate().

◆ set()

WANObjectCache::set (   $key,
  $value,
  $ttl = self::TTL_INDEFINITE,
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 data was read using "view snapshots" (e.g. innodb REPEATABLE-READ), 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.

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:

$setOpts = Database::getCacheSetOptions( $dbr );
// 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 made with makeKey()/makeGlobalKey()
mixed$valueValue to set for the cache key
int$ttlSeconds to live. Special values are:
  • WANObjectCache::TTL_INDEFINITE: Cache forever (default)
  • WANObjectCache::TTL_UNCACHEABLE: Do not cache (if the key exists, it is not deleted)
array$optsOptions map:
  • lag: Highest seconds of replication lag potentially affecting reads used to generate the value. This should not be affected by the duration of transaction "view snapshots" (e.g. innodb REPEATABLE-READ) nor the time elapsed since the first read (though both increase staleness). For reads using view snapshots, only the replication lag during snapshot initialization matters. Use false if replication is stopped/broken on a replica server involved in the reads. Default: 0 seconds
  • since: UNIX timestamp indicative of the highest possible staleness caused by the duration of transaction "view snapshots" (e.g. innodb REPEATABLE-READ) and the time elapsed since the first read. This should not be affected by replication lag. 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. Note that if "staleTTL" is set then it will still add on to this TTL in the excessive lag scenario. Default: WANObjectCache::TSE_NONE
  • staleTTL: Seconds to keep the key around if it is stale. The get()/getMulti() methods return such stale values with a $curTTL of 0, and getWithSetCallback() will call the generation callback in such cases, passing in the old value and its as-of time to the callback. This is useful if adaptiveTTL() is used on the old value's as-of time when it is verified as still being correct. Default: WANObjectCache::STALE_TTL_NONE
  • creating: Optimize for the case where the key does not already exist. Default: false
  • version: Integer version number signifiying the format of the value. Default: null
  • walltime: How long the value took to generate in seconds. Default: null @phpcs:ignore Generic.Files.LineLength
Note
Options added in 1.28: staleTTL
Options added in 1.33: creating
Options added in 1.34: version, walltime
Returns
bool Success

Definition at line 806 of file WANObjectCache.php.

References $cache, getCurrentTime(), LOW_TTL, makeSisterKey(), MAX_READ_LAG, STALE_TTL_NONE, timeSinceLoggedMiss(), TSE_NONE, TTL_LAGGED, and wrap().

◆ setInterimValue()

WANObjectCache::setInterimValue (   $key,
  $value,
  $ttl,
  $version,
  $now,
  $walltime 
)
private
Parameters
string$keyCache key made with makeKey()/makeGlobalKey()
mixed$value
int$ttl
int | null$versionValue version number
float$nowTime after value regen
float$walltimeHow long it took to generate the value in seconds

Definition at line 2023 of file WANObjectCache.php.

References makeSisterKey(), and wrap().

Referenced by fetchOrRegenerate().

◆ setLogger()

WANObjectCache::setLogger ( LoggerInterface  $logger)
Parameters
LoggerInterface$logger

Definition at line 380 of file WANObjectCache.php.

References $logger.

Referenced by __construct().

◆ setMockTime()

WANObjectCache::setMockTime ( $time)
Parameters
float | null&$timeMock UNIX timestamp for testing

Definition at line 3157 of file WANObjectCache.php.

◆ timeSinceLoggedMiss()

WANObjectCache::timeSinceLoggedMiss (   $key,
  $now 
)
private
Parameters
string$keyCache key made with makeKey()/makeGlobalKey()
float$nowCurrent UNIX timestamp
Returns
float|null Seconds since the last logged get() miss for this key, or, null

Definition at line 3125 of file WANObjectCache.php.

Referenced by set().

◆ touchCheckKey()

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 time of an entity. When the key is touched, the timestamp will be updated to the current time. Keys using the "check" key via get(), getMulti(), or getWithSetCallback() will be invalidated. This approach is useful if many keys depend on a single entity.

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.

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

Definition at line 1186 of file WANObjectCache.php.

References determineKeyClassForStats(), getCurrentTime(), makeCheckPurgeValue(), makeSisterKey(), and relayVolatilePurges().

◆ unwrap()

WANObjectCache::unwrap (   $wrapped,
  $now 
)
private
Parameters
array | string | false$wrappedThe entry at a cache key (false if key is nonexistant)
float$nowUnix Current timestamp (preferrably pre-query)
Returns
array<mixed,array> (value or false if absent/tombstoned/malformed, metadata map). The cache key metadata map includes the following metadata:

Definition at line 2935 of file WANObjectCache.php.

References FLD_TIME, FLD_TTL, FLD_VALUE, FLD_VALUE_VERSION, KEY_AS_OF, KEY_CUR_TTL, KEY_TOMB_AS_OF, KEY_TTL, KEY_VERSION, parsePurgeValue(), and PURGE_TIME.

Referenced by fetchKeys(), and getInterimValue().

◆ useInterimHoldOffCaching()

WANObjectCache::useInterimHoldOffCaching (   $enabled)
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:

  • a) the database used by the callback is known to be up-to-date enough for some particular purpose (e.g. replica DB has applied transaction X)
  • b) the caller needs to exploit that fact, and therefore needs to avoid the use of inherently volatile and possibly stale interim keys
See also
WANObjectCache::delete()
Parameters
bool$enabledWhether to enable interim caching
Since
1.31

Definition at line 2559 of file WANObjectCache.php.

Referenced by getInterimValue().

◆ worthRefreshExpiring()

WANObjectCache::worthRefreshExpiring (   $curTTL,
  $logicalTTL,
  $lowTTL 
)
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.

This approach handles widely varying levels of cache access traffic.

The logical TTL will be used as the "low" threshold if it is less than $lowTTL.

Parameters
float$curTTLApproximate TTL left on the key
float$logicalTTLFull logical TTL assigned to the key
float$lowTTLConsider a refresh when $curTTL is less than this; the "low" threshold
Returns
bool

Definition at line 2809 of file WANObjectCache.php.

Referenced by fetchOrRegenerate(), and isAliveOrInGracePeriod().

◆ worthRefreshPopular()

WANObjectCache::worthRefreshPopular (   $asOf,
  $ageNew,
  $timeTillRefresh,
  $now 
)
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.

Parameters
float$asOfUNIX timestamp of the value
int$ageNewAge of key when this might recommend refreshing (seconds)
int$timeTillRefreshAge of key when it should be refreshed if popular (seconds)
float$nowThe current UNIX timestamp
Returns
bool

Definition at line 2845 of file WANObjectCache.php.

References RAMPUP_TTL.

Referenced by fetchOrRegenerate().

◆ wrap()

WANObjectCache::wrap (   $value,
  $ttl,
  $version,
  $now,
  $walltime 
)
private
Parameters
mixed$value
int$ttlSeconds to live or zero for "indefinite"
int | null$versionValue version number or null if not versioned
float$nowUnix Current timestamp just before calling set()
float | null$walltimeHow long it took to generate the value in seconds
Returns
array

Definition at line 2904 of file WANObjectCache.php.

References FLD_GENERATION_TIME, FLD_VALUE_VERSION, and VERSION.

Referenced by set(), and setInterimValue().

◆ yieldStampedeLock()

WANObjectCache::yieldStampedeLock (   $key,
  $hasLock 
)
private
Parameters
string$keyCache key made with makeKey()/makeGlobalKey()
bool$hasLock

Definition at line 1797 of file WANObjectCache.php.

References getCurrentTime(), and makeSisterKey().

Referenced by fetchOrRegenerate().

Member Data Documentation

◆ $asyncHandler

callable null WANObjectCache::$asyncHandler
protected

Function that takes a WAN cache callback and runs it later.

Definition at line 138 of file WANObjectCache.php.

Referenced by scheduleAsyncRefresh().

◆ $broadcastRoute

string null WANObjectCache::$broadcastRoute
protected

Routing prefix for values that should be broadcasted to all data centers.

If null, then a proxy other than mcrouter handles broadcasting or there is only one datacenter.

Definition at line 147 of file WANObjectCache.php.

◆ $cache

BagOStuff WANObjectCache::$cache
protected

The local datacenter cache.

Definition at line 130 of file WANObjectCache.php.

Referenced by set().

◆ $callbackDepth

int WANObjectCache::$callbackDepth = 0
private

Callback stack depth for getWithSetCallback()

Definition at line 168 of file WANObjectCache.php.

Referenced by fetchOrRegenerate().

◆ $coalesceScheme

int WANObjectCache::$coalesceScheme
protected

Scheme to use for key coalescing (Hash Tags or Hash Stops)

Definition at line 157 of file WANObjectCache.php.

◆ $epoch

float WANObjectCache::$epoch
protected

Unix timestamp of the oldest possible valid values.

Definition at line 153 of file WANObjectCache.php.

◆ $keyHighQps

int WANObjectCache::$keyHighQps
private

Reads/second assumed during a hypothetical cache write stampede for a key.

Definition at line 160 of file WANObjectCache.php.

Referenced by checkAndSetCooloff().

◆ $keyHighUplinkBps

float WANObjectCache::$keyHighUplinkBps
private

Max tolerable bytes/second to spend on a cache write stampede for a key.

Definition at line 162 of file WANObjectCache.php.

Referenced by checkAndSetCooloff().

◆ $logger

LoggerInterface WANObjectCache::$logger
protected

Definition at line 134 of file WANObjectCache.php.

Referenced by setLogger().

◆ $missLog

array<int,array> WANObjectCache::$missLog
private

List of (key, UNIX timestamp) tuples for get() cache misses.

Definition at line 165 of file WANObjectCache.php.

◆ $onHostRoute

string null WANObjectCache::$onHostRoute
protected

Routing prefix for value keys that support use of an on-host tier.

Definition at line 149 of file WANObjectCache.php.

◆ $processCaches

MapCacheLRU [] WANObjectCache::$processCaches = []
protected

Map of group PHP instance caches.

Definition at line 132 of file WANObjectCache.php.

◆ $secret

string WANObjectCache::$secret
protected

Stable secret used for hasing long strings into key components.

Definition at line 155 of file WANObjectCache.php.

◆ $stats

StatsdDataFactoryInterface WANObjectCache::$stats
protected

Definition at line 136 of file WANObjectCache.php.

◆ $useInterimHoldOffCaching

bool WANObjectCache::$useInterimHoldOffCaching = true
protected

Whether to use "interim" caching while keys are tombstoned.

Definition at line 151 of file WANObjectCache.php.

◆ $wallClockOverride

float null WANObjectCache::$wallClockOverride
private

Definition at line 175 of file WANObjectCache.php.

Referenced by getCurrentTime().

◆ $warmupCache

mixed [] WANObjectCache::$warmupCache = []
private

Temporary warm-up cache.

Definition at line 170 of file WANObjectCache.php.

Referenced by fetchKeys().

◆ $warmupKeyMisses

int WANObjectCache::$warmupKeyMisses = 0
private

Key fetched.

Definition at line 172 of file WANObjectCache.php.

Referenced by getWarmupKeyMisses().

◆ AGE_NEW

const WANObjectCache::AGE_NEW = 60
private

Minimum key age, in seconds, for expected time-till-refresh to be considered.

Definition at line 192 of file WANObjectCache.php.

Referenced by fetchOrRegenerate().

◆ CHECK_KEY_TTL

const WANObjectCache::CHECK_KEY_TTL = self::TTL_YEAR
private

Seconds to keep dependency purge keys around.

Definition at line 219 of file WANObjectCache.php.

◆ COOLOFF_TTL

const WANObjectCache::COOLOFF_TTL = 1
private

Seconds to no-op key set() calls to avoid large blob I/O stampedes.

Definition at line 226 of file WANObjectCache.php.

◆ FLD_FLAGS

const WANObjectCache::FLD_FLAGS = 4
private

Key to the flags bit field (reserved number)

@noinspection PhpUnusedPrivateFieldInspection

Definition at line 280 of file WANObjectCache.php.

◆ FLD_FORMAT_VERSION

const WANObjectCache::FLD_FORMAT_VERSION = 0
private

Key to WAN cache version number.

Definition at line 272 of file WANObjectCache.php.

◆ FLD_GENERATION_TIME

const WANObjectCache::FLD_GENERATION_TIME = 6
private

Key to how long it took to generate the value.

Definition at line 284 of file WANObjectCache.php.

Referenced by wrap().

◆ FLD_TIME

const WANObjectCache::FLD_TIME = 3
private

Key to the cache timestamp.

Definition at line 278 of file WANObjectCache.php.

Referenced by unwrap().

◆ FLD_TTL

const WANObjectCache::FLD_TTL = 2
private

Key to the original TTL.

Definition at line 276 of file WANObjectCache.php.

Referenced by unwrap().

◆ FLD_VALUE

const WANObjectCache::FLD_VALUE = 1
private

Key to the cached value.

Definition at line 274 of file WANObjectCache.php.

Referenced by unwrap().

◆ FLD_VALUE_VERSION

const WANObjectCache::FLD_VALUE_VERSION = 5
private

Key to collection cache version number.

Definition at line 282 of file WANObjectCache.php.

Referenced by unwrap(), and wrap().

◆ GENERATION_HIGH_SEC

const WANObjectCache::GENERATION_HIGH_SEC = 0.2
private

Consider value generation somewhat high if it takes this many seconds or more.

Definition at line 241 of file WANObjectCache.php.

◆ GENERATION_SLOW_SEC

const WANObjectCache::GENERATION_SLOW_SEC = 3.0
private

Consider value generation slow if it takes this many seconds or more.

Definition at line 243 of file WANObjectCache.php.

◆ GRACE_TTL_NONE

const WANObjectCache::GRACE_TTL_NONE = 0

Idiom for set()/getWithSetCallback() meaning "no post-expiration grace period".

Definition at line 200 of file WANObjectCache.php.

Referenced by fetchOrRegenerate().

◆ HOLDOFF_TTL

const WANObjectCache::HOLDOFF_TTL = self::MAX_COMMIT_DELAY + self::MAX_READ_LAG + 1

Seconds to tombstone keys on delete() and treat as volatile after invalidation.

Definition at line 182 of file WANObjectCache.php.

Referenced by WANObjectCacheReaper\invoke(), and reap().

◆ HOLDOFF_TTL_NONE

const WANObjectCache::HOLDOFF_TTL_NONE = 0

Idiom for delete()/touchCheckKey() meaning "no hold-off period".

Definition at line 202 of file WANObjectCache.php.

◆ HOT_TTR

const WANObjectCache::HOT_TTR = 900
private

Expected time-till-refresh, in seconds, if the key is accessed once per second.

Definition at line 190 of file WANObjectCache.php.

Referenced by fetchOrRegenerate().

◆ INTERIM_KEY_TTL

const WANObjectCache::INTERIM_KEY_TTL = 1
private

Seconds to keep interim value keys for tombstoned keys around.

Definition at line 221 of file WANObjectCache.php.

◆ KEY_AS_OF

const WANObjectCache::KEY_AS_OF = 'asOf'

Generation timestamp attribute for a key; keep value for b/c (< 1.36)

Definition at line 261 of file WANObjectCache.php.

Referenced by fetchOrRegenerate(), get(), getMulti(), and unwrap().

◆ KEY_CHECK_AS_OF

const WANObjectCache::KEY_CHECK_AS_OF = 'lastCKPurge'

Highest "check" key timestamp for a key; keep value for b/c (< 1.36)

Definition at line 269 of file WANObjectCache.php.

Referenced by fetchKeys().

◆ KEY_CUR_TTL

const WANObjectCache::KEY_CUR_TTL = 'curTTL'

Remaining TTL attribute for a key; keep value for b/c (< 1.36)

Definition at line 265 of file WANObjectCache.php.

Referenced by fetchKeys(), fetchOrRegenerate(), get(), getMulti(), and unwrap().

◆ KEY_TOMB_AS_OF

const WANObjectCache::KEY_TOMB_AS_OF = 'tombAsOf'

Tomstone timestamp attribute for a key; keep value for b/c (< 1.36)

Definition at line 267 of file WANObjectCache.php.

Referenced by fetchOrRegenerate(), and unwrap().

◆ KEY_TTL

const WANObjectCache::KEY_TTL = 'ttl'

Logical TTL attribute for a key.

Definition at line 263 of file WANObjectCache.php.

Referenced by unwrap().

◆ KEY_VERSION

const WANObjectCache::KEY_VERSION = 'version'

Version number attribute for a key; keep value for b/c (< 1.36)

Definition at line 259 of file WANObjectCache.php.

Referenced by fetchOrRegenerate(), and unwrap().

◆ LOCK_TTL

const WANObjectCache::LOCK_TTL = 10
private

Seconds to keep lock keys around.

Definition at line 224 of file WANObjectCache.php.

◆ LOW_TTL

const WANObjectCache::LOW_TTL = 30
private

Consider regeneration if the key will expire within this many seconds.

Definition at line 185 of file WANObjectCache.php.

Referenced by set().

◆ MAX_COMMIT_DELAY

const WANObjectCache::MAX_COMMIT_DELAY = 3
private

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

Definition at line 178 of file WANObjectCache.php.

◆ MAX_READ_LAG

const WANObjectCache::MAX_READ_LAG = 7
private

Max expected seconds of combined lag from replication and "view snapshots".

Definition at line 180 of file WANObjectCache.php.

Referenced by set().

◆ PASS_BY_REF

const WANObjectCache::PASS_BY_REF = []

Idiom for get()/getMulti() to return extra information by reference.

Definition at line 211 of file WANObjectCache.php.

Referenced by get(), and getMulti().

◆ PC_PRIMARY

const WANObjectCache::PC_PRIMARY = 'primary:1000'
private

Default process cache name and max key count.

Definition at line 208 of file WANObjectCache.php.

◆ PURGE_HOLDOFF

const WANObjectCache::PURGE_HOLDOFF = 1
private

Key to the tombstone entry hold-off TTL.

Definition at line 248 of file WANObjectCache.php.

Referenced by fetchKeys().

◆ PURGE_TIME

const WANObjectCache::PURGE_TIME = 0
private

Key to the tombstone entry timestamp.

Definition at line 246 of file WANObjectCache.php.

Referenced by fetchKeys(), getMultiCheckKeyTime(), and unwrap().

◆ PURGE_VAL_PREFIX

const WANObjectCache::PURGE_VAL_PREFIX = 'PURGED'
private

Value prefix of purge values.

Definition at line 300 of file WANObjectCache.php.

◆ RAMPUP_TTL

const WANObjectCache::RAMPUP_TTL = 30
private

Seconds to ramp up the chance of regeneration due to expected time-till-refresh.

Definition at line 228 of file WANObjectCache.php.

Referenced by worthRefreshPopular().

◆ RECENT_SET_HIGH_MS

const WANObjectCache::RECENT_SET_HIGH_MS = 100
private

Max millisecond set() backoff during hold-off (far less than INTERIM_KEY_TTL)

Definition at line 238 of file WANObjectCache.php.

◆ RECENT_SET_LOW_MS

const WANObjectCache::RECENT_SET_LOW_MS = 50
private

Min millisecond set() backoff during hold-off (far less than INTERIM_KEY_TTL)

Definition at line 236 of file WANObjectCache.php.

◆ RES_METADATA

const WANObjectCache::RES_METADATA = 1
private

The key metadata component of a fetchMulti() result.

Definition at line 256 of file WANObjectCache.php.

Referenced by fetchOrRegenerate(), get(), getMulti(), and getMultiWithUnionSetCallback().

◆ RES_VALUE

const WANObjectCache::RES_VALUE = 0
private

The key value component of a fetchMulti() result.

Definition at line 254 of file WANObjectCache.php.

Referenced by fetchOrRegenerate(), get(), getMulti(), and getMultiWithUnionSetCallback().

◆ SCHEME_HASH_STOP

const WANObjectCache::SCHEME_HASH_STOP = 2
private

Use mcrouter-style Hash Stop key scheme (e.g.

"...|#|")

Definition at line 216 of file WANObjectCache.php.

Referenced by __construct().

◆ SCHEME_HASH_TAG

const WANObjectCache::SCHEME_HASH_TAG = 1
private

Use twemproxy-style Hash Tag key scheme (e.g.

"{...}")

Definition at line 214 of file WANObjectCache.php.

Referenced by __construct().

◆ STALE_TTL_NONE

const WANObjectCache::STALE_TTL_NONE = 0

Idiom for set()/getWithSetCallback() meaning "no post-expiration persistence".

Definition at line 198 of file WANObjectCache.php.

Referenced by fetchOrRegenerate(), and set().

◆ TSE_NONE

const WANObjectCache::TSE_NONE = -1
private

Idiom for getWithSetCallback() meaning "no cache stampede mutex".

Definition at line 195 of file WANObjectCache.php.

Referenced by fetchOrRegenerate(), and set().

◆ TTL_LAGGED

const WANObjectCache::TTL_LAGGED = 30

Max TTL, in seconds, to store keys when a data source has high replication lag.

Definition at line 187 of file WANObjectCache.php.

Referenced by set().

◆ TYPE_COOLOFF

const WANObjectCache::TYPE_COOLOFF = 'c'
private

Single character component for cool-off bounce keys.

Definition at line 297 of file WANObjectCache.php.

◆ TYPE_FLUX

const WANObjectCache::TYPE_FLUX = 'f'
private

Single character component for flux keys.

Definition at line 291 of file WANObjectCache.php.

◆ TYPE_INTERIM

const WANObjectCache::TYPE_INTERIM = 'i'
private

Single character component for interium value keys.

Definition at line 295 of file WANObjectCache.php.

◆ TYPE_MUTEX

const WANObjectCache::TYPE_MUTEX = 'm'
private

Single character component for mutex lock keys.

Definition at line 293 of file WANObjectCache.php.

◆ TYPE_TIMESTAMP

const WANObjectCache::TYPE_TIMESTAMP = 't'
private

Single character component for timestamp check keys.

Definition at line 289 of file WANObjectCache.php.

◆ TYPE_VALUE

const WANObjectCache::TYPE_VALUE = 'v'
private

Single character component for value keys.

Definition at line 287 of file WANObjectCache.php.

◆ VERSION

const WANObjectCache::VERSION = 1
private

Cache format version number.

Definition at line 251 of file WANObjectCache.php.

Referenced by wrap().


The documentation for this class was generated from the following file:
WANObjectCache\$cache
BagOStuff $cache
The local datacenter cache.
Definition: WANObjectCache.php:130
wfTimestamp
wfTimestamp( $outputtype=TS_UNIX, $ts=0)
Get a timestamp string in one of various formats.
Definition: GlobalFunctions.php:1668
$res
$res
Definition: testCompression.php:57
$dbr
$dbr
Definition: testCompression.php:54
MapCacheLRU\newFromArray
static newFromArray(array $values, $maxKeys)
Definition: MapCacheLRU.php:77
wfGetDB
wfGetDB( $db, $groups=[], $wiki=false)
Get a Database object.
Definition: GlobalFunctions.php:2203
$modules
$modules
Definition: HTMLFormElement.php:15
wfTimestampOrNull
wfTimestampOrNull( $outputtype=TS_UNIX, $ts=null)
Return a formatted timestamp, or null if input is null.
Definition: GlobalFunctions.php:1684
WANObjectCache\adaptiveTTL
adaptiveTTL( $mtime, $maxTTL, $minTTL=30, $factor=0.2)
Get a TTL that is higher for objects that have not changed recently.
Definition: WANObjectCache.php:2635
DB_REPLICA
const DB_REPLICA
Definition: defines.php:25
BagOStuff\getWithSetCallback
getWithSetCallback( $key, $exptime, $callback, $flags=0)
Get an item with the given key, regenerating and setting it if not found.
Definition: BagOStuff.php:204
BagOStuff\makeKey
makeKey( $collection,... $components)
Make a cache key for the global keyspace and given components.
BagOStuff\set
set( $key, $value, $exptime=0, $flags=0)
Set an item.
BagOStuff\makeGlobalKey
makeGlobalKey( $collection,... $components)
Make a cache key for the default keyspace and given components.
BagOStuff\delete
delete( $key, $flags=0)
Delete an item.