X-Git-Url: https://git.heureux-cyclage.org/?p=lhc%2Fweb%2Fwiklou.git;a=blobdiff_plain;f=includes%2Flibs%2Fobjectcache%2FWANObjectCache.php;h=db27e42e1e381843cf1a3cb20e9fa2f5041a1635;hp=a3c9d71a81a207598f3ad7db998e775b71862440;hb=ee14393358109fff6023855f6d194016b6332bb0;hpb=3cc7f15766b65b9b3cba865760e590e948b5ba2a diff --git a/includes/libs/objectcache/WANObjectCache.php b/includes/libs/objectcache/WANObjectCache.php index a3c9d71a81..db27e42e1e 100644 --- a/includes/libs/objectcache/WANObjectCache.php +++ b/includes/libs/objectcache/WANObjectCache.php @@ -111,6 +111,9 @@ class WANObjectCache implements IExpiringStore, LoggerAwareInterface { /** Seconds to keep dependency purge keys around */ const CHECK_KEY_TTL = self::TTL_YEAR; + /** Seconds to keep interim value keys for tombstoned keys around */ + const INTERIM_KEY_TTL = 1; + /** Seconds to keep lock keys around */ const LOCK_TTL = 10; /** Default remaining TTL at which to consider pre-emptive regeneration */ @@ -135,8 +138,10 @@ class WANObjectCache implements IExpiringStore, LoggerAwareInterface { const TTL_LAGGED = 30; /** Idiom for delete() for "no hold-off" */ const HOLDOFF_NONE = 0; - /** Idiom for set() for "do not augment the storage medium TTL" */ + /** Idiom for set()/getWithSetCallback() for "do not augment the storage medium TTL" */ const STALE_TTL_NONE = 0; + /** Idiom for set()/getWithSetCallback() for "no post-expired grace period" */ + const GRACE_TTL_NONE = 0; /** Idiom for getWithSetCallback() for "no minimum required as-of timestamp" */ const MIN_TIMESTAMP_NONE = 0.0; @@ -207,7 +212,7 @@ class WANObjectCache implements IExpiringStore, LoggerAwareInterface { * @return WANObjectCache */ public static function newEmpty() { - return new self( [ + return new static( [ 'cache' => new EmptyBagOStuff(), 'pool' => 'empty' ] ); @@ -314,7 +319,7 @@ class WANObjectCache implements IExpiringStore, LoggerAwareInterface { $wrappedValues += $this->cache->getMulti( $keysGet ); } // Time used to compare/init "check" keys (derived after getMulti() to be pessimistic) - $now = microtime( true ); + $now = $this->getCurrentTime(); // Collect timestamps from all "check" keys $purgeValuesForAll = $this->processCheckKeys( $checkKeysForAll, $wrappedValues, $now ); @@ -443,7 +448,7 @@ class WANObjectCache implements IExpiringStore, LoggerAwareInterface { * @return bool Success */ final public function set( $key, $value, $ttl = 0, array $opts = [] ) { - $now = microtime( true ); + $now = $this->getCurrentTime(); $lockTSE = isset( $opts['lockTSE'] ) ? $opts['lockTSE'] : self::TSE_NONE; $staleTTL = isset( $opts['staleTTL'] ) ? $opts['staleTTL'] : self::STALE_TTL_NONE; $age = isset( $opts['since'] ) ? max( 0, $now - $opts['since'] ) : 0; @@ -594,7 +599,7 @@ class WANObjectCache implements IExpiringStore, LoggerAwareInterface { $time = $purge[self::FLD_TIME]; } else { // Casting assures identical floats for the next getCheckKeyTime() calls - $now = (string)microtime( true ); + $now = (string)$this->getCurrentTime(); $this->cache->add( $key, $this->makePurgeValue( $now, self::HOLDOFF_TTL ), self::CHECK_KEY_TTL @@ -613,20 +618,21 @@ class WANObjectCache implements IExpiringStore, LoggerAwareInterface { * on all keys that should be changed. When get() is called on those * keys, the relevant "check" keys must be supplied for this to work. * - * The "check" key essentially represents a last-modified field. - * When touched, the field will be updated on all cache servers. - * Keys using it via get(), getMulti(), or getWithSetCallback() will - * be invalidated. It is treated as being HOLDOFF_TTL seconds in the future - * by those methods to avoid race conditions where dependent keys get updated - * with stale values (e.g. from a DB replica DB). - * - * This is typically useful for keys with hardcoded names or in some cases - * dynamically generated names where a low number of combinations exist. - * When a few important keys get a large number of hits, a high cache - * time is usually desired as well as "lockTSE" logic. The resetCheckKey() - * method is less appropriate in such cases since the "time since expiry" - * cannot be inferred, causing any get() after the reset to treat the key - * as being "hot", resulting in more stale value usage. + * 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. * @@ -657,12 +663,9 @@ class WANObjectCache implements IExpiringStore, LoggerAwareInterface { * 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 is that this does not place high TTL keys on every cache - * server, making it better for code that will cache many different keys - * and either does not use lockTSE or uses a low enough TTL anyway. - * - * This is typically useful for keys with dynamically generated names - * where a high number of combinations exist. + * 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. * @@ -814,13 +817,21 @@ class WANObjectCache implements IExpiringStore, LoggerAwareInterface { * * @param string $key Cache key made from makeKey() or makeGlobalKey() * @param int $ttl Seconds to live for key updates. Special values are: - * - WANObjectCache::TTL_INDEFINITE: Cache forever - * - WANObjectCache::TTL_UNCACHEABLE: Do not cache at all + * - WANObjectCache::TTL_INDEFINITE: Cache forever (subject to LRU-style evictions) + * - WANObjectCache::TTL_UNCACHEABLE: Do not cache (if the key exists, it is not deleted) * @param callable $callback Value generation function * @param array $opts Options map: * - checkKeys: List of "check" keys. The key at $key will be seen as invalid when either - * touchCheckKey() or resetCheckKey() is called on any of these keys. + * 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: Consider reusing expired values instead of refreshing them if they expired + * less than this many seconds ago. The odds of a refresh becomes 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. + * Default: WANObjectCache::GRACE_TTL_NONE. * - lockTSE: If the key is tombstoned or expired (by checkKeys) less than this many seconds * ago, then try to have a single thread handle cache regeneration at any given time. * Other threads will try to use stale values if possible. If, on miss, the time since @@ -855,19 +866,26 @@ class WANObjectCache implements IExpiringStore, LoggerAwareInterface { * 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) for keys that average ~1 hit/second (1 Hz). - * 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. The TTR is useful at + * - 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. + * $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 * @return mixed Value found or written to the key * @note Options added in 1.28: version, busyValue, hotTTR, ageNew, pcGroup, minAsOf * @note Callable type hints are not used to avoid class-autoloading @@ -899,11 +917,14 @@ class WANObjectCache implements IExpiringStore, LoggerAwareInterface { use ( $callback, $version ) { if ( is_array( $oldValue ) && array_key_exists( self::VFLD_DATA, $oldValue ) + && array_key_exists( self::VFLD_VERSION, $oldValue ) + && $oldValue[self::VFLD_VERSION] === $version ) { $oldData = $oldValue[self::VFLD_DATA]; } else { // VFLD_DATA is not set if an old, unversioned, key is present $oldData = false; + $oldAsOf = null; } return [ @@ -957,6 +978,8 @@ class WANObjectCache implements IExpiringStore, LoggerAwareInterface { protected function doGetWithSetCallback( $key, $ttl, $callback, array $opts, &$asOf = null ) { $lowTTL = isset( $opts['lowTTL'] ) ? $opts['lowTTL'] : min( self::LOW_TTL, $ttl ); $lockTSE = isset( $opts['lockTSE'] ) ? $opts['lockTSE'] : self::TSE_NONE; + $staleTTL = isset( $opts['staleTTL'] ) ? $opts['staleTTL'] : self::STALE_TTL_NONE; + $graceTTL = isset( $opts['graceTTL'] ) ? $opts['graceTTL'] : self::GRACE_TTL_NONE; $checkKeys = isset( $opts['checkKeys'] ) ? $opts['checkKeys'] : []; $busyValue = isset( $opts['busyValue'] ) ? $opts['busyValue'] : null; $popWindow = isset( $opts['hotTTR'] ) ? $opts['hotTTR'] : self::HOT_TTR; @@ -972,10 +995,10 @@ class WANObjectCache implements IExpiringStore, LoggerAwareInterface { $cValue = $this->get( $key, $curTTL, $checkKeys, $asOf ); // current value $value = $cValue; // return value - $preCallbackTime = microtime( true ); + $preCallbackTime = $this->getCurrentTime(); // Determine if a cached value regeneration is needed or desired if ( $value !== false - && $curTTL > 0 + && $this->isAliveOrInGracePeriod( $curTTL, $graceTTL ) && $this->isValid( $value, $versioned, $asOf, $minTime ) && !$this->worthRefreshExpiring( $curTTL, $lowTTL ) && !$this->worthRefreshPopular( $asOf, $ageNew, $popWindow, $preCallbackTime ) @@ -989,7 +1012,7 @@ class WANObjectCache implements IExpiringStore, LoggerAwareInterface { $isTombstone = ( $curTTL !== null && $value === false ); if ( $isTombstone && $lockTSE <= 0 ) { // Use the INTERIM value for tombstoned keys to reduce regeneration load - $lockTSE = 1; + $lockTSE = self::INTERIM_KEY_TTL; } // Assume a key is hot if requested soon after invalidation $isHot = ( $curTTL !== null && $curTTL <= 0 && abs( $curTTL ) <= $lockTSE ); @@ -1048,7 +1071,7 @@ class WANObjectCache implements IExpiringStore, LoggerAwareInterface { // so use a special INTERIM key to pass the new value around threads. if ( ( $isTombstone && $lockTSE > 0 ) && $valueIsCacheable ) { $tempTTL = max( 1, (int)$lockTSE ); // set() expects seconds - $newAsOf = microtime( true ); + $newAsOf = $this->getCurrentTime(); $wrapped = $this->wrap( $value, $tempTTL, $newAsOf ); // Avoid using set() to avoid pointless mcrouter broadcasting $this->setInterimValue( $key, $wrapped, $tempTTL ); @@ -1056,6 +1079,7 @@ class WANObjectCache implements IExpiringStore, LoggerAwareInterface { if ( $valueIsCacheable ) { $setOpts['lockTSE'] = $lockTSE; + $setOpts['staleTTL'] = $staleTTL; // Use best known "since" timestamp if not provided $setOpts += [ 'since' => $preCallbackTime ]; // Update the cache; this will fail if the key is tombstoned @@ -1081,7 +1105,7 @@ class WANObjectCache implements IExpiringStore, LoggerAwareInterface { */ protected function getInterimValue( $key, $versioned, $minTime, &$asOf ) { $wrapped = $this->cache->get( self::INTERIM_KEY_PREFIX . $key ); - list( $value ) = $this->unwrap( $wrapped, microtime( true ) ); + list( $value ) = $this->unwrap( $wrapped, $this->getCurrentTime() ); if ( $value !== false && $this->isValid( $value, $versioned, $asOf, $minTime ) ) { $asOf = $wrapped[self::FLD_TIME]; @@ -1496,6 +1520,46 @@ class WANObjectCache implements IExpiringStore, LoggerAwareInterface { * $ttl = $cache->adaptiveTTL( $mtime, $cache::TTL_DAY ); * @endcode * + * 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: + * @code + * $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 + * ] + * ); + * @endcode + * * @param int|float $mtime UNIX timestamp * @param int $maxTTL Maximum TTL (seconds) * @param int $minTTL Minimum TTL (seconds); Default: 30 @@ -1512,7 +1576,7 @@ class WANObjectCache implements IExpiringStore, LoggerAwareInterface { return $minTTL; // no last-modified time provided } - $age = time() - $mtime; + $age = $this->getCurrentTime() - $mtime; return (int)min( $maxTTL, max( $minTTL, $factor * $age ) ); } @@ -1539,7 +1603,7 @@ class WANObjectCache implements IExpiringStore, LoggerAwareInterface { if ( $this->purgeRelayer instanceof EventRelayerNull ) { // This handles the mcrouter and the single-DC case $ok = $this->cache->set( $key, - $this->makePurgeValue( microtime( true ), self::HOLDOFF_NONE ), + $this->makePurgeValue( $this->getCurrentTime(), self::HOLDOFF_NONE ), $ttl ); } else { @@ -1585,23 +1649,56 @@ class WANObjectCache implements IExpiringStore, LoggerAwareInterface { return $ok; } + /** + * Check if a key is fresh or in the grace window and thus due for randomized reuse + * + * If $curTTL > 0 (e.g. not expired) this returns true. Otherwise, the chance of returning + * true decrease steadily from 100% to 0% as the |$curTTL| moves from 0 to $graceTTL seconds. + * This handles widely varying levels of cache access traffic. + * + * If $curTTL <= -$graceTTL (e.g. already expired), then this returns false. + * + * @param float $curTTL Approximate TTL left on the key if present + * @param int $graceTTL Consider using stale values if $curTTL is greater than this + * @return bool + */ + protected function isAliveOrInGracePeriod( $curTTL, $graceTTL ) { + if ( $curTTL > 0 ) { + return true; + } elseif ( $graceTTL <= 0 ) { + return false; + } + + $ageStale = abs( $curTTL ); // seconds of staleness + $curGTTL = ( $graceTTL - $ageStale ); // current grace-time-to-live + if ( $curGTTL <= 0 ) { + return false; // already out of grace period + } + + // Chance of using a stale value is the complement of the chance of refreshing it + return !$this->worthRefreshExpiring( $curGTTL, $graceTTL ); + } + /** * Check if a key is nearing expiration and thus due for randomized regeneration * - * This returns false if $curTTL >= $lowTTL. Otherwise, the chance - * of returning true increases steadily from 0% to 100% as the $curTTL - * moves from $lowTTL to 0 seconds. This handles widely varying - * levels of cache access traffic. + * This returns false if $curTTL >= $lowTTL. Otherwise, the chance of returning true + * increases steadily from 0% to 100% as the $curTTL moves from $lowTTL to 0 seconds. + * This handles widely varying levels of cache access traffic. + * + * If $curTTL <= 0 (e.g. already expired), then this returns false. * * @param float $curTTL Approximate TTL left on the key if present * @param float $lowTTL Consider a refresh when $curTTL is less than this * @return bool */ protected function worthRefreshExpiring( $curTTL, $lowTTL ) { - if ( $curTTL >= $lowTTL ) { + if ( $lowTTL <= 0 ) { + return false; + } elseif ( $curTTL >= $lowTTL ) { return false; } elseif ( $curTTL <= 0 ) { - return true; + return false; } $chance = ( 1 - $curTTL / $lowTTL ); @@ -1625,6 +1722,10 @@ class WANObjectCache implements IExpiringStore, LoggerAwareInterface { * @return bool */ protected function worthRefreshPopular( $asOf, $ageNew, $timeTillRefresh, $now ) { + if ( $ageNew < 0 || $timeTillRefresh <= 0 ) { + return false; + } + $age = $now - $asOf; $timeOld = $age - $ageNew; if ( $timeOld <= 0 ) { @@ -1746,6 +1847,14 @@ class WANObjectCache implements IExpiringStore, LoggerAwareInterface { return isset( $parts[1] ) ? $parts[1] : $parts[0]; // sanity } + /** + * @return float UNIX timestamp + * @codeCoverageIgnore + */ + protected function getCurrentTime() { + return microtime( true ); + } + /** * @param string $value Wrapped value like "PURGED::" * @return array|bool Array containing a UNIX timestamp (float) and holdoff period (integer),