22 use Liuggio\StatsdClient\Factory\StatsdDataFactoryInterface;
23 use Psr\Log\LoggerAwareInterface;
24 use Psr\Log\LoggerInterface;
25 use Psr\Log\NullLogger;
184 public const HOLDOFF_TTL = self::MAX_COMMIT_DELAY + self::MAX_READ_LAG + 1;
207 public const MIN_TIMESTAMP_NONE = 0.0;
233 private const TINY_NEGATIVE = -0.000001;
235 private const TINY_POSTIVE = 0.000001;
348 $this->cache = $params[
'cache'];
349 $this->broadcastRoute = $params[
'broadcastRoutingPrefix'] ??
null;
350 $this->epoch = $params[
'epoch'] ?? 0;
351 $this->secret = $params[
'secret'] ?? (string)$this->epoch;
352 if ( ( $params[
'coalesceScheme'] ??
'' ) ===
'hash_tag' ) {
362 $this->keyHighQps = $params[
'keyHighQps'] ?? 100;
363 $this->keyHighUplinkBps = $params[
'keyHighUplinkBps'] ?? ( 1e9 / 8 / 100 );
365 $this->
setLogger( $params[
'logger'] ??
new NullLogger() );
367 $this->asyncHandler = $params[
'asyncHandler'] ??
null;
369 $this->missLog = array_fill( 0, 10, [
'', 0.0 ] );
371 $this->cache->registerWrapperInfoForStats(
374 [ __CLASS__,
'getCollectionFromSisterKey' ]
449 final public function get( $key, &$curTTL =
null, array $checkKeys = [], &$info = [] ) {
468 if ( $curTTL ===
null || $curTTL <= 0 ) {
470 reset( $this->missLog );
471 unset( $this->missLog[key( $this->missLog )] );
505 array $checkKeys = [],
516 $resByKey = $this->
fetchKeys( $keys, $checkKeys );
517 foreach ( $resByKey as $key =>
$res ) {
518 if (
$res[self::RES_VALUE] !==
false ) {
522 if (
$res[self::RES_CUR_TTL] !==
null ) {
525 $info[$key] = $legacyInfo
554 protected function fetchKeys( array
$keys, array $checkKeys, $touchedCb =
null ) {
560 $valueSisterKeys = [];
562 $checkSisterKeysForAll = [];
564 $checkSisterKeysByKey = [];
566 foreach (
$keys as $key ) {
568 $allSisterKeys[] = $sisterKey;
569 $valueSisterKeys[] = $sisterKey;
572 foreach ( $checkKeys as $i => $checkKeyOrKeyGroup ) {
574 if ( is_int( $i ) ) {
576 $sisterKey = $this->
makeSisterKey( $checkKeyOrKeyGroup, self::TYPE_TIMESTAMP );
577 $allSisterKeys[] = $sisterKey;
578 $checkSisterKeysForAll[] = $sisterKey;
581 foreach ( (array)$checkKeyOrKeyGroup as $checkKey ) {
582 $sisterKey = $this->
makeSisterKey( $checkKey, self::TYPE_TIMESTAMP );
583 $allSisterKeys[] = $sisterKey;
584 $checkSisterKeysByKey[$i][] = $sisterKey;
589 if ( $this->warmupCache ) {
592 $sisterKeysMissing = array_diff( $allSisterKeys, array_keys( $wrappedBySisterKey ) );
593 if ( $sisterKeysMissing ) {
594 $this->warmupKeyMisses += count( $sisterKeysMissing );
595 $wrappedBySisterKey += $this->cache->getMulti( $sisterKeysMissing );
599 $wrappedBySisterKey = $this->cache->getMulti( $allSisterKeys );
607 $checkSisterKeysForAll,
613 foreach ( $checkSisterKeysByKey as $keyWithCheckKeys => $checkKeysForKey ) {
623 foreach ( $valueSisterKeys as $valueSisterKey ) {
625 $key = current(
$keys );
628 if ( array_key_exists( $valueSisterKey, $wrappedBySisterKey ) ) {
630 $wrapped = $wrappedBySisterKey[$valueSisterKey];
639 foreach ( array_merge( $ckPurgesForAll, $ckPurgesByKey[$key] ?? [] ) as $ckPurge ) {
641 $ckPurge[self::PURGE_TIME],
642 $res[self::RES_CHECK_AS_OF]
647 if ( $value !==
false && $holdoffDeadline >=
$res[self::RES_AS_OF] ) {
649 $ago = min( $ckPurge[self::PURGE_TIME] - $now, self::TINY_NEGATIVE );
655 if ( $touchedCb !==
null && $value !==
false ) {
656 $touched = $touchedCb( $value );
657 if ( $touched !==
null && $touched >=
$res[self::RES_AS_OF] ) {
659 $res[self::RES_CUR_TTL],
660 $res[self::RES_AS_OF] - $touched,
670 $resByKey[$key] =
$res;
683 array $checkSisterKeys,
684 array $wrappedBySisterKey,
689 foreach ( $checkSisterKeys as $timeKey ) {
690 $purge = isset( $wrappedBySisterKey[$timeKey] )
694 if ( $purge ===
null ) {
696 $this->cache->add( $timeKey, $wrapped, self::CHECK_KEY_TTL );
785 final public function set( $key, $value, $ttl = self::TTL_INDEFINITE, array $opts = [] ) {
787 $dataReplicaLag = $opts[
'lag'] ?? 0;
788 $dataSnapshotLag = isset( $opts[
'since'] ) ? max( 0, $now - $opts[
'since'] ) : 0;
789 $dataCombinedLag = $dataReplicaLag + $dataSnapshotLag;
790 $dataPendingCommit = $opts[
'pending'] ??
null;
793 $creating = $opts[
'creating'] ??
false;
794 $version = $opts[
'version'] ??
null;
807 if ( $dataPendingCommit ) {
809 $mitigated =
'pending writes';
811 $mitigationTTL = self::TTL_UNCACHEABLE;
812 } elseif ( $dataSnapshotLag > self::MAX_READ_LAG ) {
814 $pregenSnapshotLag = ( $walltime !== null ) ? ( $dataSnapshotLag - $walltime ) : 0;
817 $mitigated =
'snapshot lag (late generation)';
819 $mitigationTTL = self::TTL_UNCACHEABLE;
822 $mitigated =
'snapshot lag (high generation time)';
826 } elseif ( $dataReplicaLag ===
false || $dataReplicaLag > self::MAX_READ_LAG ) {
828 $mitigated =
'replication lag';
831 } elseif ( $dataCombinedLag > self::MAX_READ_LAG ) {
832 $pregenCombinedLag = ( $walltime !== null ) ? ( $dataCombinedLag - $walltime ) : 0;
836 $mitigated =
'read lag (late generation)';
838 $mitigationTTL = self::TTL_UNCACHEABLE;
841 $mitigated =
'read lag (high generation time)';
849 $mitigationTTL =
null;
852 if ( $mitigationTTL === self::TTL_UNCACHEABLE ) {
853 $this->logger->warning(
854 "Rejected set() for {cachekey} due to $mitigated.",
857 'lag' => $dataReplicaLag,
858 'age' => $dataSnapshotLag,
859 'walltime' => $walltime
870 if ( $mitigationTTL !==
null ) {
872 if ( $lockTSE >= 0 ) {
874 $logicalTTL = min( $ttl ?: INF, $mitigationTTL );
877 $ttl = min( $ttl ?: INF, $mitigationTTL );
880 $this->logger->warning(
881 "Lowered set() TTL for {cachekey} due to $mitigated.",
884 'lag' => $dataReplicaLag,
885 'age' => $dataSnapshotLag,
886 'walltime' => $walltime
892 $wrapped = $this->
wrap( $value, $logicalTTL ?: $ttl, $version, $now, $walltime );
893 $storeTTL = $ttl + $staleTTL;
896 $ok = $this->cache->add(
902 $ok = $this->cache->merge(
904 static function (
$cache, $key, $cWrapped ) use ( $wrapped ) {
906 return ( is_string( $cWrapped ) ) ?
false : $wrapped;
983 $valueSisterKey = $this->
makeSisterKey( $key, self::TYPE_VALUE );
1004 $this->stats->increment(
"wanobjectcache.$kClass.delete." . ( $ok ?
'ok' :
'error' ) );
1094 $checkSisterKeysByKey = [];
1095 foreach (
$keys as $key ) {
1096 $checkSisterKeysByKey[$key] = $this->
makeSisterKey( $key, self::TYPE_TIMESTAMP );
1099 $wrappedBySisterKey = $this->cache->getMulti( $checkSisterKeysByKey );
1100 $wrappedBySisterKey += array_fill_keys( $checkSisterKeysByKey,
false );
1104 foreach ( $checkSisterKeysByKey as $key => $checkSisterKey ) {
1105 $purge = $this->
parsePurgeValue( $wrappedBySisterKey[$checkSisterKey] );
1106 if ( $purge ===
null ) {
1108 $this->cache->add( $checkSisterKey, $wrapped, self::CHECK_KEY_TTL );
1151 $checkSisterKey = $this->
makeSisterKey( $key, self::TYPE_TIMESTAMP );
1158 $this->stats->increment(
"wanobjectcache.$kClass.ck_touch." . ( $ok ?
'ok' :
'error' ) );
1191 $checkSisterKey = $this->
makeSisterKey( $key, self::TYPE_TIMESTAMP );
1195 $this->stats->increment(
"wanobjectcache.$kClass.ck_reset." . ( $ok ?
'ok' :
'error' ) );
1504 $key, $ttl, $callback, array $opts = [], array $cbParams = []
1506 $version = $opts[
'version'] ??
null;
1507 $pcTTL = $opts[
'pcTTL'] ?? self::TTL_UNCACHEABLE;
1508 $pCache = ( $pcTTL >= 0 )
1515 if ( $pCache && $this->callbackDepth == 0 ) {
1516 $cached = $pCache->get( $key, $pcTTL,
false );
1517 if ( $cached !==
false ) {
1518 $this->logger->debug(
"getWithSetCallback($key): process cache hit" );
1523 [ $value, $valueVersion, $curAsOf ] = $this->
fetchOrRegenerate( $key, $ttl, $callback, $opts, $cbParams );
1524 if ( $valueVersion !== $version ) {
1528 $this->logger->debug(
"getWithSetCallback($key): using variant key" );
1530 $this->
makeGlobalKey(
'WANCache-key-variant', md5( $key ), (
string)$version ),
1533 [
'version' =>
null,
'minAsOf' => $curAsOf ] + $opts,
1539 if ( $pCache && $value !==
false ) {
1540 $pCache->set( $key, $value );
1563 $checkKeys = $opts[
'checkKeys'] ?? [];
1565 $minAsOf = $opts[
'minAsOf'] ?? self::MIN_TIMESTAMP_NONE;
1567 $lowTTL = $opts[
'lowTTL'] ?? min( self::LOW_TTL, $ttl );
1569 $touchedCb = $opts[
'touchedCallback'] ??
null;
1575 $curState = $this->
fetchKeys( [ $key ], $checkKeys, $touchedCb )[$key];
1580 $this->stats->timing(
1581 "wanobjectcache.$kClass.hit.good",
1587 $this->logger->debug(
"fetchOrRegenerate($key): hit with async refresh" );
1588 $this->stats->timing(
1589 "wanobjectcache.$kClass.hit.refresh",
1595 $this->logger->debug(
"fetchOrRegenerate($key): hit with sync refresh" );
1601 if ( $isKeyTombstoned ) {
1602 $volState = $this->
getInterimValue( $key, $minAsOf, $startTime, $touchedCb );
1605 $volState = $curState;
1606 $volValue = $curValue;
1614 $lastPurgeTime = max(
1616 $volState[self::RES_TOUCH_AS_OF],
1617 $curState[self::RES_TOMB_AS_OF],
1618 $curState[self::RES_CHECK_AS_OF]
1620 $safeMinAsOf = max( $minAsOf, $lastPurgeTime + self::TINY_POSTIVE );
1622 $this->logger->debug(
"fetchOrRegenerate($key): volatile hit" );
1623 $this->stats->timing(
1624 "wanobjectcache.$kClass.hit.volatile",
1632 $busyValue = $opts[
'busyValue'] ??
null;
1634 $version = $opts[
'version'] ??
null;
1637 $useRegenerationLock =
1650 abs( $curState[self::RES_CUR_TTL] ) <= $lockTSE
1654 ( $busyValue !==
null && $volValue ===
false );
1660 if ( $useRegenerationLock && !$hasLock ) {
1663 if ( $this->
isValid( $volValue, $volState[self::RES_AS_OF], $minAsOf ) ) {
1664 $this->logger->debug(
"fetchOrRegenerate($key): returning stale value" );
1665 $this->stats->timing(
1666 "wanobjectcache.$kClass.hit.stale",
1671 } elseif ( $busyValue !==
null ) {
1672 $miss = is_infinite( $minAsOf ) ?
'renew' :
'miss';
1673 $this->logger->debug(
"fetchOrRegenerate($key): busy $miss" );
1674 $this->stats->timing(
1675 "wanobjectcache.$kClass.$miss.busy",
1690 ( $curState[self::RES_VERSION] === $version ) ? $curValue :
false,
1693 ( $curState[self::RES_VERSION] === $version ) ? $curState[self::RES_AS_OF] :
null,
1702 $elapsed = max( $postCallbackTime - $startTime, 0.0 );
1705 $walltime = max( $postCallbackTime - $preCallbackTime, 0.0 );
1706 $this->stats->timing(
"wanobjectcache.$kClass.regen_walltime", 1e3 * $walltime );
1712 ( $value !==
false && $ttl >= 0 ) &&
1714 ( !$useRegenerationLock || $hasLock || $isKeyTombstoned ) &&
1720 if ( $isKeyTombstoned ) {
1722 $this->
setInterimValue( $key, $value, $lockTSE, $version, $postCallbackTime, $walltime );
1726 'since' => $setOpts[
'since'] ?? $preCallbackTime,
1727 'version' => $version,
1728 'staleTTL' => $staleTTL,
1730 'lockTSE' => $lockTSE,
1732 'creating' => ( $curValue === false ),
1733 'walltime' => $walltime
1736 $this->
set( $key, $value, $ttl, $finalSetOpts );
1742 $miss = is_infinite( $minAsOf ) ?
'renew' :
'miss';
1743 $this->logger->debug(
"fetchOrRegenerate($key): $miss, new value computed" );
1744 $this->stats->timing(
1745 "wanobjectcache.$kClass.$miss.compute",
1758 $checkSisterKey = $this->
makeSisterKey( $key, self::TYPE_MUTEX );
1760 return $this->cache->add( $checkSisterKey, 1, self::LOCK_TTL );
1769 $checkSisterKey = $this->
makeSisterKey( $key, self::TYPE_MUTEX );
1770 $this->cache->changeTTL( $checkSisterKey, (
int)$this->
getCurrentTime() - 60 );
1786 foreach ( $baseKeys as $baseKey ) {
1803 private function makeSisterKey(
string $baseKey,
string $typeChar,
string $route =
null ) {
1804 if ( $this->coalesceScheme === self::SCHEME_HASH_STOP ) {
1806 $sisterKey =
'WANCache:' . $baseKey .
'|#|' . $typeChar;
1809 $sisterKey =
'WANCache:{' . $baseKey .
'}:' . $typeChar;
1812 if ( $route !==
null ) {
1813 $sisterKey = $this->
prependRoute( $sisterKey, $route );
1826 if ( substr( $sisterKey, -4 ) ===
'|#|v' ) {
1828 $collection = substr( $sisterKey, 9, strcspn( $sisterKey,
':|', 9 ) );
1829 } elseif ( substr( $sisterKey, -3 ) ===
'}:v' ) {
1831 $collection = substr( $sisterKey, 10, strcspn( $sisterKey,
':}', 10 ) );
1833 $collection =
'internal';
1852 if (
$res[self::RES_VALUE] ===
false ||
$res[self::RES_AS_OF] < $minAsOf ) {
1858 return ( $age < mt_rand( self::RECENT_SET_LOW_MS, self::RECENT_SET_HIGH_MS ) / 1e3 );
1883 $valueSisterKey = $this->
makeSisterKey( $key, self::TYPE_VALUE );
1884 list( $estimatedSize ) = $this->cache->setNewPreparedValues( [
1885 $valueSisterKey => $value
1910 $cooloffSisterKey = $this->
makeSisterKey( $key, self::TYPE_COOLOFF );
1911 $watchPoint = $this->cache->watchErrors();
1913 !$this->cache->add( $cooloffSisterKey, 1, self::COOLOFF_TTL ) &&
1915 $this->cache->getLastError( $watchPoint ) === self::ERR_NONE
1917 $this->stats->increment(
"wanobjectcache.$kClass.cooloff_bounce" );
1925 $this->stats->timing(
"wanobjectcache.$kClass.regen_set_delay", 1e3 * $elapsed );
1926 $this->stats->updateCount(
"wanobjectcache.$kClass.regen_set_bytes", $estimatedSize );
1942 $interimSisterKey = $this->
makeSisterKey( $key, self::TYPE_INTERIM );
1943 $wrapped = $this->cache->get( $interimSisterKey );
1945 if (
$res[self::RES_VALUE] !==
false &&
$res[self::RES_AS_OF] >= $minAsOf ) {
1946 if ( $touchedCb !==
null ) {
1950 $touchedCb(
$res[self::RES_VALUE] ),
1951 $res[self::RES_TOUCH_AS_OF]
1959 return $this->
unwrap(
false, $now );
1971 $ttl = max( self::INTERIM_KEY_TTL, (
int)$ttl );
1973 $wrapped = $this->
wrap( $value, $ttl, $version, $now, $walltime );
1986 return ( $busyValue instanceof Closure ) ? $busyValue() : $busyValue;
2055 ArrayIterator $keyedIds, $ttl, callable $callback, array $opts = []
2060 $opts[
'checkKeys'] ?? []
2062 $this->warmupKeyMisses = 0;
2068 $proxyCb =
static function ( $oldValue, &$ttl, &$setOpts, $oldAsOf, $params )
2071 return $callback( $params[
'id'], $oldValue, $ttl, $setOpts, $oldAsOf );
2076 foreach ( $keyedIds as $key => $id ) {
2086 $this->warmupCache = [];
2158 ArrayIterator $keyedIds, $ttl, callable $callback, array $opts = []
2160 $checkKeys = $opts[
'checkKeys'] ?? [];
2161 $minAsOf = $opts[
'minAsOf'] ?? self::MIN_TIMESTAMP_NONE;
2164 unset( $opts[
'lockTSE'] );
2165 unset( $opts[
'busyValue'] );
2170 $this->warmupKeyMisses = 0;
2176 $resByKey = $this->
fetchKeys( $keysByIdGet, $checkKeys );
2177 foreach ( $keysByIdGet as $id => $key ) {
2178 $res = $resByKey[$key];
2180 $res[self::RES_VALUE] ===
false ||
2181 $res[self::RES_CUR_TTL] < 0 ||
2182 $res[self::RES_AS_OF] < $minAsOf
2190 $newTTLsById = array_fill_keys( $idsRegen, $ttl );
2191 $newValsById = $idsRegen ? $callback( $idsRegen, $newTTLsById, $newSetOpts ) : [];
2193 $method = __METHOD__;
2198 $proxyCb =
function ( $oldValue, &$ttl, &$setOpts, $oldAsOf, $params )
2199 use ( $callback, $newValsById, $newTTLsById, $newSetOpts, $method )
2201 $id = $params[
'id'];
2203 if ( array_key_exists( $id, $newValsById ) ) {
2205 $newValue = $newValsById[$id];
2206 $ttl = $newTTLsById[$id];
2207 $setOpts = $newSetOpts;
2211 $ttls = [ $id => $ttl ];
2212 $result = $callback( [ $id ], $ttls, $setOpts );
2213 if ( !isset( $result[$id] ) ) {
2215 $this->logger->warning(
2216 $method .
' failed due to {id} not set in result {result}', [
2218 'result' => json_encode( $result )
2221 $newValue = $result[$id];
2230 foreach ( $keyedIds as $key => $id ) {
2240 $this->warmupCache = [];
2257 final public function reap( $key, $purgeTimestamp, &$isStale =
false ) {
2258 $valueSisterKey = $this->
makeSisterKey( $key, self::TYPE_VALUE );
2261 $wrapped = $this->cache->get( $valueSisterKey );
2262 if ( is_array( $wrapped ) && $wrapped[self::FLD_TIME] < $minAsOf ) {
2264 $this->logger->warning(
"Reaping stale value key '$key'." );
2267 $ok = $this->cache->changeTTL( $valueSisterKey, $ttlReap );
2269 $this->logger->error(
"Could not complete reap of key '$key'." );
2289 final public function reapCheckKey( $key, $purgeTimestamp, &$isStale =
false ) {
2290 $checkSisterKey = $this->
makeSisterKey( $key, self::TYPE_TIMESTAMP );
2292 $wrapped = $this->cache->get( $checkSisterKey );
2294 if ( $purge !==
null && $purge[self::PURGE_TIME] < $purgeTimestamp ) {
2296 $this->logger->warning(
"Reaping stale check key '$key'." );
2297 $ok = $this->cache->changeTTL( $checkSisterKey, self::TTL_SECOND );
2299 $this->logger->error(
"Could not complete reap of check key '$key'." );
2321 return $this->cache->makeGlobalKey( ...func_get_args() );
2334 public function makeKey( $collection, ...$components ) {
2335 return $this->cache->makeKey( ...func_get_args() );
2346 return hash_hmac(
'sha256', $component, $this->secret );
2400 foreach ( $ids as $id ) {
2402 if ( strlen( $id ) > 64 ) {
2403 $this->logger->warning( __METHOD__ .
": long ID '$id'; use hash256()" );
2405 $key = $keyCallback( $id, $this );
2407 if ( !isset( $idByKey[$key] ) ) {
2408 $idByKey[$key] = $id;
2409 } elseif ( (
string)$id !== (
string)$idByKey[$key] ) {
2410 throw new UnexpectedValueException(
2411 "Cache key collision; IDs ('$id','{$idByKey[$key]}') map to '$key'"
2416 return new ArrayIterator( $idByKey );
2455 if ( count( $ids ) !== count(
$res ) ) {
2458 $ids = array_keys( array_fill_keys( $ids,
true ) );
2459 if ( count( $ids ) !== count(
$res ) ) {
2460 throw new UnexpectedValueException(
"Multi-key result does not match ID list" );
2464 return array_combine( $ids,
$res );
2474 return $this->cache->watchErrors();
2495 $code = $this->cache->getLastError( $watchPoint );
2513 $this->cache->clearLastError();
2522 $this->processCaches = [];
2555 return $this->cache->getQoS( $flag );
2621 public function adaptiveTTL( $mtime, $maxTTL, $minTTL = 30, $factor = 0.2 ) {
2623 $mtime = (int)$mtime;
2624 if ( $mtime <= 0 ) {
2631 return (
int)min( $maxTTL, max( $minTTL, $factor * $age ) );
2659 $purgeByRouteKey = [];
2660 foreach ( $purgeBySisterKey as $sisterKey => $purge ) {
2661 if ( $this->broadcastRoute !==
null ) {
2662 $routeKey = $this->
prependRoute( $sisterKey, $this->broadcastRoute );
2664 $routeKey = $sisterKey;
2666 $purgeByRouteKey[$routeKey] = $purge;
2669 if ( count( $purgeByRouteKey ) == 1 ) {
2670 $purge = reset( $purgeByRouteKey );
2671 $ok = $this->cache->set( key( $purgeByRouteKey ), $purge, $ttl );
2673 $ok = $this->cache->setMulti( $purgeByRouteKey, $ttl );
2688 if ( $this->broadcastRoute !==
null ) {
2689 $routeKey = $this->
prependRoute( $sisterKey, $this->broadcastRoute );
2691 $routeKey = $sisterKey;
2694 return $this->cache->delete( $routeKey );
2703 if ( $sisterKey[0] ===
'/' ) {
2704 throw new RuntimeException(
"Sister key '$sisterKey' already contains a route." );
2707 return $route . $sisterKey;
2722 if ( !$this->asyncHandler ) {
2730 $func(
function () use ( $key, $ttl, $callback, $opts, $cbParams ) {
2731 $opts[
'minAsOf'] = INF;
2734 }
catch ( Exception $e ) {
2736 $this->logger->error(
'Async refresh failed for {key}', [
2757 if ( !$this->
isValid(
$res[self::RES_VALUE],
$res[self::RES_AS_OF], $minAsOf ) ) {
2763 if ( $curTTL > 0 ) {
2769 $curGraceTTL = $graceTTL + $curTTL;
2771 return ( $curGraceTTL > 0 )
2815 if ( $ageNew < 0 || $timeTillRefresh <= 0 ) {
2819 $age = $now - $asOf;
2820 $timeOld = $age - $ageNew;
2821 if ( $timeOld <= 0 ) {
2825 $popularHitsPerSec = 1;
2829 $refreshWindowSec = max( $timeTillRefresh - $ageNew - self::RAMPUP_TTL / 2, 1 );
2833 $chance = 1 / ( $popularHitsPerSec * $refreshWindowSec );
2835 $chance *= ( $timeOld <=
self::RAMPUP_TTL ) ? $timeOld / self::RAMPUP_TTL : 1;
2837 return ( mt_rand( 1, 1000000000 ) <= 1000000000 * $chance );
2859 if ( $lowTTL <= 0 ) {
2865 $effectiveLowTTL = min( $lowTTL, $logicalTTL ?: INF );
2867 if ( $curTTL >= $effectiveLowTTL || $curTTL <= 0 ) {
2871 $chance = ( 1 - $curTTL / $effectiveLowTTL );
2873 return ( mt_rand( 1, 1000000000 ) <= 1000000000 * $chance );
2884 protected function isValid( $value, $asOf, $minAsOf ) {
2885 return ( $value !==
false && $asOf >= $minAsOf );
2896 private function wrap( $value, $ttl, $version, $now, $walltime ) {
2901 self::FLD_VALUE => $value,
2902 self::FLD_TTL => $ttl,
2903 self::FLD_TIME => $now
2905 if ( $version !==
null ) {
2908 if ( $walltime >= self::GENERATION_SLOW_SEC ) {
2933 self::RES_VALUE =>
false,
2934 self::RES_VERSION =>
null,
2935 self::RES_AS_OF =>
null,
2936 self::RES_TTL =>
null,
2937 self::RES_TOMB_AS_OF =>
null,
2939 self::RES_CHECK_AS_OF =>
null,
2940 self::RES_TOUCH_AS_OF =>
null,
2941 self::RES_CUR_TTL => null
2944 if ( is_array( $wrapped ) ) {
2947 ( $wrapped[self::FLD_FORMAT_VERSION] ??
null ) === self::VERSION &&
2948 $wrapped[self::FLD_TIME] >= $this->epoch
2950 if ( $wrapped[self::FLD_TTL] > 0 ) {
2953 $curTTL = max( $wrapped[self::FLD_TTL] - $age, 0.0 );
2967 if ( $purge !==
null ) {
2969 $curTTL = min( $purge[self::PURGE_TIME] - $now, self::TINY_NEGATIVE );
2983 $parts = explode(
':', $key, 3 );
2986 return strtr( $parts[1] ?? $parts[0],
'.',
'_' );
2998 if ( !is_string( $value ) ) {
3002 $segments = explode(
':', $value, 3 );
3003 $prefix = $segments[0];
3004 if ( $prefix !== self::PURGE_VAL_PREFIX ) {
3009 $timestamp = (float)$segments[1];
3011 $holdoff = isset( $segments[2] ) ? (int)$segments[2] : self::HOLDOFF_TTL;
3013 if ( $timestamp < $this->epoch ) {
3018 return [ self::PURGE_TIME => $timestamp, self::PURGE_HOLDOFF => $holdoff ];
3026 return self::PURGE_VAL_PREFIX .
':' . (int)$timestamp;
3036 $normalizedTime = (int)$timestamp;
3038 $purge = [ self::PURGE_TIME => (float)$normalizedTime, self::PURGE_HOLDOFF => $holdoff ];
3040 return self::PURGE_VAL_PREFIX .
":$normalizedTime:$holdoff";
3048 if ( !isset( $this->processCaches[$group] ) ) {
3049 list( , $size ) = explode(
':', $group );
3050 $this->processCaches[$group] =
new MapCacheLRU( (
int)$size );
3051 if ( $this->wallClockOverride !==
null ) {
3052 $this->processCaches[$group]->setMockTime( $this->wallClockOverride );
3056 return $this->processCaches[$group];
3065 $pcTTL = $opts[
'pcTTL'] ?? self::TTL_UNCACHEABLE;
3068 if ( $pcTTL > 0 && $this->callbackDepth == 0 ) {
3069 $pCache = $this->
getProcessCache( $opts[
'pcGroup'] ?? self::PC_PRIMARY );
3070 foreach (
$keys as $key => $id ) {
3071 if ( !$pCache->has( $key, $pcTTL ) ) {
3072 $keysMissing[$id] = $key;
3077 return $keysMissing;
3094 foreach ( $checkKeys as $i => $checkKeyOrKeyGroup ) {
3096 if ( is_int( $i ) ) {
3098 $sisterKeys[] = $this->
makeSisterKey( $checkKeyOrKeyGroup, self::TYPE_TIMESTAMP );
3101 foreach ( (array)$checkKeyOrKeyGroup as $checkKey ) {
3102 $sisterKeys[] = $this->
makeSisterKey( $checkKey, self::TYPE_TIMESTAMP );
3107 $wrappedBySisterKey = $this->cache->getMulti( $sisterKeys );
3108 $wrappedBySisterKey += array_fill_keys( $sisterKeys,
false );
3110 return $wrappedBySisterKey;
3119 for ( end( $this->missLog ); $miss = current( $this->missLog ); prev( $this->missLog ) ) {
3120 if ( $miss[0] === $key ) {
3121 return ( $now - $miss[1] );
3133 if ( $this->wallClockOverride ) {
3138 $clockTime = (float)time();
3144 return max( microtime(
true ), $clockTime );
3152 $this->wallClockOverride =& $time;
3153 $this->cache->setMockTime( $time );
3154 foreach ( $this->processCaches as $pCache ) {
3155 $pCache->setMockTime( $time );
A BagOStuff object with no objects in it.
Handles a simple LRU key/value map with a maximum number of entries.
Multi-datacenter aware caching interface.
makeGlobalKey( $collection,... $components)
Make a cache key for the global keyspace and given components.
int $callbackDepth
Callback stack depth for getWithSetCallback()
const PURGE_TIME
Key to the tombstone entry timestamp.
const RES_TOUCH_AS_OF
Highest "touched" timestamp for a key.
const HOLDOFF_TTL
Seconds to tombstone keys on delete() and to treat keys as volatile after purges.
const HOT_TTR
Expected time-till-refresh, in seconds, if the key is accessed once per second.
const KEY_VERSION
Version number attribute for a key; keep value for b/c (< 1.36)
__construct(array $params)
isValid( $value, $asOf, $minAsOf)
Check that a wrapper value exists and has an acceptable age.
const TYPE_TIMESTAMP
Single character component for timestamp check keys.
const RES_AS_OF
Generation completion timestamp attribute for a key.
worthRefreshPopular( $asOf, $ageNew, $timeTillRefresh, $now)
Check if a key is due for randomized regeneration due to its popularity.
fetchOrRegenerate( $key, $ttl, $callback, array $opts, array $cbParams)
Do the actual I/O for getWithSetCallback() when needed.
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...
const FLD_FORMAT_VERSION
Key to WAN cache version number; stored in blobs.
determineKeyClassForStats( $key)
const SCHEME_HASH_STOP
Use mcrouter-style Hash Stop key scheme (e.g.
const RES_VALUE
Value for a key.
const RES_VERSION
Version number attribute for a key.
prependRoute(string $sisterKey, string $route)
touchCheckKey( $key, $holdoff=self::HOLDOFF_TTL)
Increase the last-purge timestamp of a "check" key in all datacenters.
const FLD_VALUE
Key to the cached value; stored in blobs.
const PURGE_HOLDOFF
Key to the tombstone entry hold-off TTL.
adaptiveTTL( $mtime, $maxTTL, $minTTL=30, $factor=0.2)
Get a TTL that is higher for objects that have not changed recently.
const GRACE_TTL_NONE
Idiom for set()/getWithSetCallback() meaning "no post-expiration grace period".
int $warmupKeyMisses
Key fetched.
float null $wallClockOverride
relayVolatilePurges(array $purgeBySisterKey, int $ttl)
Set a sister key to a purge value in all datacenters.
mixed[] $warmupCache
Temporary warm-up cache.
const VERSION
Cache format version number.
const LOW_TTL
Consider regeneration if the key will expire within this many seconds.
BagOStuff $cache
The local datacenter cache.
fetchKeys(array $keys, array $checkKeys, $touchedCb=null)
Fetch the value and key metadata of several keys from cache.
parsePurgeValue( $value)
Extract purge metadata from cached value if it is a valid purge value.
const RES_TOMB_AS_OF
Tomstone timestamp attribute for a key.
scheduleAsyncRefresh( $key, $ttl, $callback, array $opts, array $cbParams)
Schedule a deferred cache regeneration if possible.
const RES_TTL
Logical TTL attribute for a key.
const GENERATION_HIGH_SEC
Consider value generation somewhat high if it takes this many seconds or more.
const GENERATION_SLOW_SEC
Consider value generation slow if it takes this many seconds or more.
const COOLOFF_TTL
Seconds to no-op key set() calls to avoid large blob I/O stampedes.
getWithSetCallback( $key, $ttl, $callback, array $opts=[], array $cbParams=[])
Method to fetch/regenerate a cache key.
getCheckKeyTime( $key)
Fetch the value of a timestamp "check" key.
getNonProcessCachedMultiKeys(ArrayIterator $keys, array $opts)
const SCHEME_HASH_TAG
Use twemproxy-style Hash Tag key scheme (e.g.
const RECENT_SET_HIGH_MS
Max millisecond set() backoff during hold-off (far less than INTERIM_KEY_TTL)
const LOCK_TTL
Seconds to keep lock keys around.
getMulti(array $keys, &$curTTLs=[], array $checkKeys=[], &$info=[])
Fetch the value of several keys from cache.
const PC_PRIMARY
Default process cache name and max key count.
getMultiWithUnionSetCallback(ArrayIterator $keyedIds, $ttl, callable $callback, array $opts=[])
Method to fetch/regenerate multiple cache keys at once.
const TYPE_MUTEX
Single character component for mutex lock keys.
relayNonVolatilePurge(string $sisterKey)
Remove a sister key from all datacenters.
getMultiWithSetCallback(ArrayIterator $keyedIds, $ttl, callable $callback, array $opts=[])
Method to fetch multiple cache keys at once with regeneration.
timeSinceLoggedMiss( $key, $now)
isExtremelyNewValue( $res, $minAsOf, $now)
Check if a key value is non-false, new enough, and has an "as of" time almost equal to now.
wrap( $value, $ttl, $version, $now, $walltime)
const PURGE_VAL_PREFIX
Value prefix of purge values.
const INTERIM_KEY_TTL
Seconds to keep interim value keys for tombstoned keys around.
makeMultiKeys(array $ids, $keyCallback)
Get an iterator of (cache key => entity ID) for a list of entity IDs.
makeTombstonePurgeValue(float $timestamp)
array< int, array > $missLog
List of (key, UNIX timestamp) tuples for get() cache misses.
static newEmpty()
Get an instance that wraps EmptyBagOStuff.
int $coalesceScheme
Scheme to use for key coalescing (Hash Tags or Hash Stops)
const FLD_TTL
Key to the original TTL; stored in blobs.
isLotteryRefreshDue( $res, $lowTTL, $ageNew, $hotTTR, $now)
Check if a key is due for randomized regeneration due to near-expiration/popularity.
watchErrors()
Get a "watch point" token that can be used to get the "last error" to occur after now.
bool $useInterimHoldOffCaching
Whether to use "interim" caching while keys are tombstoned.
worthRefreshExpiring( $curTTL, $logicalTTL, $lowTTL)
Check if a key is nearing expiration and thus due for randomized regeneration.
const FLD_FLAGS
Key to the flags bit field (reserved number)
const HOLDOFF_TTL_NONE
Idiom for delete()/touchCheckKey() meaning "no hold-off period".
const MAX_READ_LAG
Max expected seconds of combined lag from replication and "view snapshots".
const RES_CUR_TTL
Remaining TTL attribute for a key.
const FLD_TIME
Key to the cache timestamp; stored in blobs.
const CHECK_KEY_TTL
Seconds to keep dependency purge keys around.
useInterimHoldOffCaching( $enabled)
Enable or disable the use of brief caching for tombstoned keys.
StatsdDataFactoryInterface $stats
makeSisterKeys(array $baseKeys, string $type, string $route=null)
Get sister keys that should be collocated with their corresponding base cache keys.
clearProcessCache()
Clear the in-process caches; useful for testing.
const KEY_AS_OF
Generation completion timestamp attribute for a key; keep value for b/c (< 1.36)
const TYPE_COOLOFF
Single character component for cool-off bounce keys.
const FLD_GENERATION_TIME
Key to how long it took to generate the value; stored in blobs.
getLastError( $watchPoint=0)
Get the "last error" registry.
makeSisterKey(string $baseKey, string $typeChar, string $route=null)
Get a sister key that should be collocated with a base cache key.
makeKey( $collection,... $components)
Make a cache key using the "global" keyspace for the given components.
float $epoch
Unix timestamp of the oldest possible valid values.
fetchWrappedValuesForWarmupCache(array $keys, array $checkKeys)
callable null $asyncHandler
Function that takes a WAN cache callback and runs it later.
string null $broadcastRoute
Routing prefix for operations that should be broadcasted to all data centers.
resolveBusyValue( $busyValue)
reap( $key, $purgeTimestamp, &$isStale=false)
Set a key to soon expire in the local cluster if it pre-dates $purgeTimestamp.
const RECENT_SET_LOW_MS
Min millisecond set() backoff during hold-off (far less than INTERIM_KEY_TTL)
setLogger(LoggerInterface $logger)
static getCollectionFromSisterKey(string $sisterKey)
reapCheckKey( $key, $purgeTimestamp, &$isStale=false)
Set a "check" key to soon expire in the local cluster if it pre-dates $purgeTimestamp.
const TYPE_INTERIM
Single character component for interium value keys.
const PASS_BY_REF
Idiom for get()/getMulti() to return extra information by reference.
checkAndSetCooloff( $key, $kClass, $value, $elapsed, $hasLock)
Check whether set() is rate-limited to avoid concurrent I/O spikes.
float $keyHighUplinkBps
Max tolerable bytes/second to spend on a cache write stampede for a key.
getInterimValue( $key, $minAsOf, $now, $touchedCb)
const KEY_CHECK_AS_OF
Highest "check" key timestamp for a key; keep value for b/c (< 1.36)
processCheckKeys(array $checkSisterKeys, array $wrappedBySisterKey, float $now)
setInterimValue( $key, $value, $ttl, $version, $now, $walltime)
isAcceptablyFreshValue( $res, $graceTTL, $minAsOf)
Check if a key value is non-false, new enough, and either fresh or "gracefully" stale.
clearLastError()
Clear the "last error" registry.
const STALE_TTL_NONE
Idiom for set()/getWithSetCallback() meaning "no post-expiration persistence".
MapCacheLRU[] $processCaches
Map of group PHP instance caches.
const TSE_NONE
Idiom for getWithSetCallback() meaning "no cache stampede mutex".
string $secret
Stable secret used for hashing long strings into key components.
const RES_CHECK_AS_OF
Highest "check" key timestamp for a key.
const TYPE_VALUE
Single character component for value keys.
resetCheckKey( $key)
Clear the last-purge timestamp of a "check" key in all datacenters.
const KEY_TOMB_AS_OF
Tomstone timestamp attribute for a key; keep value for b/c (< 1.36)
int $keyHighQps
Reads/second assumed during a hypothetical cache write stampede for a key.
const MAX_COMMIT_DELAY
Max expected seconds to pass between delete() and DB commit finishing.
const KEY_CUR_TTL
Remaining TTL attribute for a key; keep value for b/c (< 1.36)
const AGE_NEW
Minimum key age, in seconds, for expected time-till-refresh to be considered.
yieldStampedeLock( $key, $hasLock)
const RAMPUP_TTL
Seconds to ramp up the chance of regeneration due to expected time-till-refresh.
const TTL_LAGGED
Max TTL, in seconds, to store keys when a data source has high replication lag.
const FLD_VALUE_VERSION
Key to collection cache version number; stored in blobs.
hash256( $component)
Hash a possibly long string into a suitable component for makeKey()/makeGlobalKey()
getMultiCheckKeyTime(array $keys)
Fetch the values of each timestamp "check" key.
makeCheckPurgeValue(float $timestamp, int $holdoff, array &$purge=null)
const KEY_TTL
Logical TTL attribute for a key.
Generic interface for object stores with key encoding methods.