Code Coverage
 
Classes and Traits
Functions and Methods
Lines
Total
0.00% covered (danger)
0.00%
0 / 1
54.39% covered (warning)
54.39%
31 / 57
CRAP
84.54% covered (warning)
84.54%
525 / 621
WANObjectCache
0.00% covered (danger)
0.00%
0 / 1
54.39% covered (warning)
54.39%
31 / 57
417.37
84.54% covered (warning)
84.54%
525 / 621
 __construct
0.00% covered (danger)
0.00%
0 / 1
2.00
93.75% covered (success)
93.75%
15 / 16
 setLogger
100.00% covered (success)
100.00%
1 / 1
1
100.00% covered (success)
100.00%
2 / 2
 newEmpty
100.00% covered (success)
100.00%
1 / 1
1
100.00% covered (success)
100.00%
1 / 1
 get
100.00% covered (success)
100.00%
1 / 1
3
100.00% covered (success)
100.00%
11 / 11
 getMulti
0.00% covered (danger)
0.00%
0 / 1
16
98.18% covered (success)
98.18%
54 / 55
 processCheckKeys
100.00% covered (success)
100.00%
1 / 1
4
100.00% covered (success)
100.00%
11 / 11
 set
100.00% covered (success)
100.00%
1 / 1
18
100.00% covered (success)
100.00%
60 / 60
 delete
100.00% covered (success)
100.00%
1 / 1
3
100.00% covered (success)
100.00%
9 / 9
 getCheckKeyTime
100.00% covered (success)
100.00%
1 / 1
1
100.00% covered (success)
100.00%
1 / 1
 getMultiCheckKeyTime
100.00% covered (success)
100.00%
1 / 1
4
100.00% covered (success)
100.00%
18 / 18
 touchCheckKey
100.00% covered (success)
100.00%
1 / 1
2
100.00% covered (success)
100.00%
7 / 7
 resetCheckKey
100.00% covered (success)
100.00%
1 / 1
2
100.00% covered (success)
100.00%
4 / 4
 getWithSetCallback
100.00% covered (success)
100.00%
1 / 1
8
100.00% covered (success)
100.00%
23 / 23
 fetchOrRegenerate
0.00% covered (danger)
0.00%
0 / 1
30.18
94.19% covered (success)
94.19%
81 / 86
 claimStampedeLock
0.00% covered (danger)
0.00%
0 / 1
2
0.00% covered (danger)
0.00%
0 / 4
 yieldStampedeLock
0.00% covered (danger)
0.00%
0 / 1
6
0.00% covered (danger)
0.00%
0 / 5
 makeSisterKeys
100.00% covered (success)
100.00%
1 / 1
2
100.00% covered (success)
100.00%
4 / 4
 makeSisterKey
0.00% covered (danger)
0.00%
0 / 1
4.02
88.89% covered (warning)
88.89%
8 / 9
 isVolatileValueAgeNegligible
0.00% covered (danger)
0.00%
0 / 1
2
0.00% covered (danger)
0.00%
0 / 1
 checkAndSetCooloff
0.00% covered (danger)
0.00%
0 / 1
30
0.00% covered (danger)
0.00%
0 / 16
 resolveCTL
0.00% covered (danger)
0.00%
0 / 1
30
0.00% covered (danger)
0.00%
0 / 6
 resolveTouched
0.00% covered (danger)
0.00%
0 / 1
12
0.00% covered (danger)
0.00%
0 / 3
 getInterimValue
100.00% covered (success)
100.00%
1 / 1
3
100.00% covered (success)
100.00%
8 / 8
 setInterimValue
100.00% covered (success)
100.00%
1 / 1
1
100.00% covered (success)
100.00%
9 / 9
 resolveBusyValue
0.00% covered (danger)
0.00%
0 / 1
6
0.00% covered (danger)
0.00%
0 / 1
 getMultiWithSetCallback
100.00% covered (success)
100.00%
1 / 1
2
100.00% covered (success)
100.00%
16 / 16
 getMultiWithUnionSetCallback
100.00% covered (success)
100.00%
1 / 1
7
100.00% covered (success)
100.00%
36 / 36
 reap
100.00% covered (success)
100.00%
1 / 1
4
100.00% covered (success)
100.00%
14 / 14
 reapCheckKey
0.00% covered (danger)
0.00%
0 / 1
4.01
92.31% covered (success)
92.31%
12 / 13
 makeKey
100.00% covered (success)
100.00%
1 / 1
1
100.00% covered (success)
100.00%
1 / 1
 makeGlobalKey
100.00% covered (success)
100.00%
1 / 1
1
100.00% covered (success)
100.00%
1 / 1
 hash256
100.00% covered (success)
100.00%
1 / 1
1
100.00% covered (success)
100.00%
1 / 1
 makeMultiKeys
0.00% covered (danger)
0.00%
0 / 1
5.02
90.91% covered (success)
90.91%
10 / 11
 multiRemap
0.00% covered (danger)
0.00%
0 / 1
3.07
80.00% covered (warning)
80.00%
4 / 5
 getLastError
0.00% covered (danger)
0.00%
0 / 1
20
0.00% covered (danger)
0.00%
0 / 6
 clearLastError
0.00% covered (danger)
0.00%
0 / 1
2
0.00% covered (danger)
0.00%
0 / 2
 clearProcessCache
0.00% covered (danger)
0.00%
0 / 1
2
0.00% covered (danger)
0.00%
0 / 2
 useInterimHoldOffCaching
100.00% covered (success)
100.00%
1 / 1
1
100.00% covered (success)
100.00%
2 / 2
 getQoS
100.00% covered (success)
100.00%
1 / 1
1
100.00% covered (success)
100.00%
1 / 1
 adaptiveTTL
100.00% covered (success)
100.00%
1 / 1
5
100.00% covered (success)
100.00%
6 / 6
 getWarmupKeyMisses
100.00% covered (success)
100.00%
1 / 1
1
100.00% covered (success)
100.00%
1 / 1
 relayPurge
0.00% covered (danger)
0.00%
0 / 1
2.26
60.00% covered (warning)
60.00%
6 / 10
 relayDelete
0.00% covered (danger)
0.00%
0 / 1
2.06
75.00% covered (warning)
75.00%
3 / 4
 scheduleAsyncRefresh
0.00% covered (danger)
0.00%
0 / 1
6
0.00% covered (danger)
0.00%
0 / 7
 isAliveOrInGracePeriod
0.00% covered (danger)
0.00%
0 / 1
20
0.00% covered (danger)
0.00%
0 / 9
 worthRefreshExpiring
0.00% covered (danger)
0.00%
0 / 1
5.01
91.67% covered (success)
91.67%
11 / 12
 worthRefreshPopular
0.00% covered (danger)
0.00%
0 / 1
13.78
40.00% covered (danger)
40.00%
6 / 15
 isValid
100.00% covered (success)
100.00%
1 / 1
4
100.00% covered (success)
100.00%
6 / 6
 wrap
100.00% covered (success)
100.00%
1 / 1
3
100.00% covered (success)
100.00%
9 / 9
 unwrap
100.00% covered (success)
100.00%
1 / 1
6
100.00% covered (success)
100.00%
18 / 18
 determineKeyClassForStats
100.00% covered (success)
100.00%
1 / 1
1
100.00% covered (success)
100.00%
2 / 2
 parsePurgeValue
0.00% covered (danger)
0.00%
0 / 1
7.60
76.92% covered (warning)
76.92%
10 / 13
 makePurgeValue
100.00% covered (success)
100.00%
1 / 1
1
100.00% covered (success)
100.00%
1 / 1
 getProcessCache
100.00% covered (success)
100.00%
1 / 1
3
100.00% covered (success)
100.00%
6 / 6
 getProcessCacheKey
0.00% covered (danger)
0.00%
0 / 1
2
0.00% covered (danger)
0.00%
0 / 1
 getNonProcessCachedMultiKeys
100.00% covered (success)
100.00%
1 / 1
5
100.00% covered (success)
100.00%
9 / 9
 getRawKeysForWarmup
0.00% covered (danger)
0.00%
0 / 1
6.20
63.64% covered (warning)
63.64%
7 / 11
 getCurrentTime
n/a
0 / 0
2
n/a
0 / 0
 setMockTime
n/a
0 / 0
2
n/a
0 / 0
<?php
/**
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License along
 * with this program; if not, write to the Free Software Foundation, Inc.,
 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
 * http://www.gnu.org/copyleft/gpl.html
 *
 * @file
 * @ingroup Cache
 */
use Liuggio\StatsdClient\Factory\StatsdDataFactoryInterface;
use Psr\Log\LoggerAwareInterface;
use Psr\Log\LoggerInterface;
use Psr\Log\NullLogger;
use Wikimedia\LightweightObjectStore\ExpirationAwareness;
use Wikimedia\LightweightObjectStore\StorageAwareness;
/**
 * 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 master 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.
 *
 * @anchor wanobjectcache-deployment
 * ### Deploying %WANObjectCache
 *
 * There are two supported ways to set up broadcasted operations:
 *
 *   - A) Set up mcrouter as the underlying cache backend, using a memcached BagOStuff class
 *        for the 'cache' parameter. The 'region' and 'cluster' parameters must be provided
 *        and 'mcrouterAware' must be set to `true`.
 *        Configure mcrouter as follows:
 *          - 1) Use Route Prefixing based on region (datacenter) and cache cluster.
 *               See https://github.com/facebook/mcrouter/wiki/Routing-Prefix and
 *               https://github.com/facebook/mcrouter/wiki/Multi-cluster-broadcast-setup.
 *          - 2) To increase the consistency of delete() and touchCheckKey() during cache
 *               server membership changes, you can use the OperationSelectorRoute to
 *               configure 'set' and 'delete' operations to go to all servers in the cache
 *               cluster, instead of just one server determined by hashing.
 *               See https://github.com/facebook/mcrouter/wiki/List-of-Route-Handles.
 *   - B) Set up dynomite as a cache middleware between the web servers and either memcached
 *        or redis and use it as the underlying cache backend, using a memcached BagOStuff
 *        class for the 'cache' parameter. This will broadcast all key setting operations,
 *        not just purges, which can be useful for cache warming. Writes are eventually
 *        consistent via the Dynamo replication model. See https://github.com/Netflix/dynomite.
 *
 * 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.
 *
 * All values are wrapped in metadata arrays. Keys use a "WANCache:" prefix to avoid
 * collisions with keys that are not wrapped as metadata arrays. For any given key that
 * a caller uses, there are several "sister" keys that might be involved under the hood.
 * Each "sister" key differs only by a single-character:
 *   - v: used for regular value keys
 *   - i: used for temporarily storing values of tombstoned keys
 *   - t: used for storing timestamp "check" keys
 *   - m: used for temporary mutex keys to avoid cache stampedes
 *
 * @ingroup Cache
 * @since 1.26
 */
class WANObjectCache implements
    ExpirationAwareness,
    StorageAwareness,
    IStoreKeyEncoder,
    LoggerAwareInterface
{
    /** @var BagOStuff The local datacenter cache */
    protected $cache;
    /** @var MapCacheLRU[] Map of group PHP instance caches */
    protected $processCaches = [];
    /** @var LoggerInterface */
    protected $logger;
    /** @var StatsdDataFactoryInterface */
    protected $stats;
    /** @var callable|null Function that takes a WAN cache callback and runs it later */
    protected $asyncHandler;
    /** @var bool Whether to use mcrouter key prefixing for routing */
    protected $mcrouterAware;
    /** @var string Physical region for mcrouter use */
    protected $region;
    /** @var string Cache cluster name for mcrouter use */
    protected $cluster;
    /** @var bool Whether to use "interim" caching while keys are tombstoned */
    protected $useInterimHoldOffCaching = true;
    /** @var float Unix timestamp of the oldest possible valid values */
    protected $epoch;
    /** @var string Stable secret used for hasing long strings into key components */
    protected $secret;
    /** @var string|bool Whether "sister" keys should be coalesced to the same cache server */
    protected $coalesceKeys;
    /** @var int Scheme to use for key coalescing (Hash Tags or Hash Stops) */
    protected $coalesceScheme;
    /** @var int Reads/second assumed during a hypothetical cache write stampede for a key */
    private $keyHighQps;
    /** @var float Max tolerable bytes/second to spend on a cache write stampede for a key */
    private $keyHighUplinkBps;
    /** @var int Callback stack depth for getWithSetCallback() */
    private $callbackDepth = 0;
    /** @var mixed[] Temporary warm-up cache */
    private $warmupCache = [];
    /** @var int Key fetched */
    private $warmupKeyMisses = 0;
    /** @var float|null */
    private $wallClockOverride;
    /** @var int Max expected seconds to pass between delete() and DB commit finishing */
    private const MAX_COMMIT_DELAY = 3;
    /** @var int Max expected seconds of combined lag from replication and view snapshots */
    private const MAX_READ_LAG = 7;
    /** @var int Seconds to tombstone keys on delete() and treat as volatile after invalidation */
    public const HOLDOFF_TTL = self::MAX_COMMIT_DELAY + self::MAX_READ_LAG + 1;
    /** @var int Consider regeneration if the key will expire within this many seconds */
    private const LOW_TTL = 30;
    /** @var int Max TTL, in seconds, to store keys when a data sourced is lagged */
    public const TTL_LAGGED = 30;
    /** @var int Expected time-till-refresh, in seconds, if the key is accessed once per second */
    private const HOT_TTR = 900;
    /** @var int Minimum key age, in seconds, for expected time-till-refresh to be considered */
    private const AGE_NEW = 60;
    /** @var int Idiom for getWithSetCallback() meaning "no cache stampede mutex required" */
    private const TSE_NONE = -1;
    /** @var int Idiom for set()/getWithSetCallback() meaning "no post-expiration persistence" */
    private const STALE_TTL_NONE = 0;
    /** @var int Idiom for set()/getWithSetCallback() meaning "no post-expiration grace period" */
    private const GRACE_TTL_NONE = 0;
    /** @var int Idiom for delete()/touchCheckKey() meaning "no hold-off period" */
    public const HOLDOFF_TTL_NONE = 0;
    /** @var int Alias for HOLDOFF_TTL_NONE (b/c) (deprecated since 1.34) */
    public const HOLDOFF_NONE = self::HOLDOFF_TTL_NONE;
    /** @var float Idiom for getWithSetCallback() meaning "no minimum required as-of timestamp" */
    public const MIN_TIMESTAMP_NONE = 0.0;
    /** @var string Default process cache name and max key count */
    private const PC_PRIMARY = 'primary:1000';
    /** @var int Idiom for get()/getMulti() to return extra information by reference */
    public const PASS_BY_REF = -1;
    /** @var int Use twemproxy-style Hash Tag key scheme (e.g. "{...}") */
    private const SCHEME_HASH_TAG = 1;
    /** @var int Use mcrouter-style Hash Stop key scheme (e.g. "...|#|") */
    private const SCHEME_HASH_STOP = 2;
    /** @var int Seconds to keep dependency purge keys around */
    private static $CHECK_KEY_TTL = self::TTL_YEAR;
    /** @var int Seconds to keep interim value keys for tombstoned keys around */
    private static $INTERIM_KEY_TTL = 1;
    /** @var int Seconds to keep lock keys around */
    private static $LOCK_TTL = 10;
    /** @var int Seconds to no-op key set() calls to avoid large blob I/O stampedes */
    private static $COOLOFF_TTL = 1;
    /** @var int Seconds to ramp up the chance of regeneration due to expected time-till-refresh */
    private static $RAMPUP_TTL = 30;
    /** @var float Tiny negative float to use when CTL comes up >= 0 due to clock skew */
    private static $TINY_NEGATIVE = -0.000001;
    /** @var float Tiny positive float to use when using "minTime" to assert an inequality */
    private static $TINY_POSTIVE = 0.000001;
    /** @var int Min millisecond set() backoff during hold-off (far less than INTERIM_KEY_TTL) */
    private static $RECENT_SET_LOW_MS = 50;
    /** @var int Max millisecond set() backoff during hold-off (far less than INTERIM_KEY_TTL) */
    private static $RECENT_SET_HIGH_MS = 100;
    /** @var int Consider value generation slow if it takes more than this many seconds */
    private static $GENERATION_SLOW_SEC = 3;
    /** @var int Key to the tombstone entry timestamp */
    private static $PURGE_TIME = 0;
    /** @var int Key to the tombstone entry hold-off TTL */
    private static $PURGE_HOLDOFF = 1;
    /** @var int Cache format version number */
    private static $VERSION = 1;
    /** @var int Key to WAN cache version number */
    private static $FLD_FORMAT_VERSION = 0;
    /** @var int Key to the cached value */
    private static $FLD_VALUE = 1;
    /** @var int Key to the original TTL */
    private static $FLD_TTL = 2;
    /** @var int Key to the cache timestamp */
    private static $FLD_TIME = 3;
    /** @var int Key to the flags bit field (reserved number) */
    private static /** @noinspection PhpUnusedPrivateFieldInspection */ $FLD_FLAGS = 4;
    /** @var int Key to collection cache version number */
    private static $FLD_VALUE_VERSION = 5;
    /** @var int Key to how long it took to generate the value */
    private static $FLD_GENERATION_TIME = 6;
    /** @var string Single character value mutex key component */
    private static $TYPE_VALUE = 'v';
    /** @var string Single character timestamp key component */
    private static $TYPE_TIMESTAMP = 't';
    /** @var string Single character mutex key component */
    private static $TYPE_MUTEX = 'm';
    /** @var string Single character interium key component */
    private static $TYPE_INTERIM = 'i';
    /** @var string Single character cool-off key component */
    private static $TYPE_COOLOFF = 'c';
    /** @var string Prefix for tombstone key values */
    private static $PURGE_VAL_PREFIX = 'PURGED:';
    /**
     * @param 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]
     *   - region: the current physical region. This is required when using mcrouter as the
     *       backing store proxy. [optional]
     *   - cluster: name of the cache cluster used by this WAN cache. The name must be the
     *       same in all datacenters; the ("region","cluster") tuple is what distinguishes
     *       the counterpart cache clusters among all the datacenter. The contents of
     *       https://github.com/facebook/mcrouter/wiki/Config-Files give background on this.
     *       This is required when using mcrouter as the backing store proxy. [optional]
     *   - mcrouterAware: set as true if mcrouter is the backing store proxy and mcrouter
     *       is configured to interpret /<region>/<cluster>/ key prefixes as routes. This
     *       requires that "region" and "cluster" are both set above. [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]
     *   - coalesceKeys: whether to use a key scheme that encourages 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.
     *       Set this to "non-global" to only apply the scheme to non-global keys. [default: false]
     *   - 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)]
     */
    public function __construct( array $params ) {
        $this->cache = $params['cache'];
        $this->region = $params['region'] ?? 'main';
        $this->cluster = $params['cluster'] ?? 'wan-main';
        $this->mcrouterAware = !empty( $params['mcrouterAware'] );
        $this->epoch = $params['epoch'] ?? 0;
        $this->secret = $params['secret'] ?? (string)$this->epoch;
        $this->coalesceKeys = $params['coalesceKeys'] ?? false;
        if ( !empty( $params['mcrouterAware'] ) ) {
            // https://github.com/facebook/mcrouter/wiki/Key-syntax
            $this->coalesceScheme = self::SCHEME_HASH_STOP;
        } else {
            // https://redis.io/topics/cluster-spec
            // https://github.com/twitter/twemproxy/blob/v0.4.1/notes/recommendation.md#hash-tags
            // https://github.com/Netflix/dynomite/blob/v0.7.0/notes/recommendation.md#hash-tags
            $this->coalesceScheme = self::SCHEME_HASH_TAG;
        }
        $this->keyHighQps = $params['keyHighQps'] ?? 100;
        $this->keyHighUplinkBps = $params['keyHighUplinkBps'] ?? ( 1e9 / 8 / 100 );
        $this->setLogger( $params['logger'] ?? new NullLogger() );
        $this->stats = $params['stats'] ?? new NullStatsdDataFactory();
        $this->asyncHandler = $params['asyncHandler'] ?? null;
    }
    /**
     * @param LoggerInterface $logger
     */
    public function setLogger( LoggerInterface $logger ) {
        $this->logger = $logger;
    }
    /**
     * Get an instance that wraps EmptyBagOStuff
     *
     * @return WANObjectCache
     */
    public static function newEmpty() {
        return new static( [ 'cache' => new EmptyBagOStuff() ] );
    }
    /**
     * 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:
     *   - a) Calling delete() on entity change *and* creation, before DB commit
     *   - b) Keeping transaction duration shorter than the delete() hold-off TTL
     *   - c) Disabling interim key caching via useInterimHoldOffCaching() before get() calls
     *
     * However, pre-snapshot values might still be seen if an update was made
     * in a remote datacenter but the purge from delete() didn't relay yet.
     *
     * Consider using getWithSetCallback() instead of get() and set() cycles.
     * That method has cache slam avoiding features for hot/expensive keys.
     *
     * Pass $info as WANObjectCache::PASS_BY_REF to transform it into a cache key metadata map.
     * This map includes the following metadata:
     *   - asOf: UNIX timestamp of the value or null if the key is nonexistant
     *   - tombAsOf: UNIX timestamp of the tombstone or null if the key is not tombstoned
     *   - lastCKPurge: UNIX timestamp of the highest check key or null if none provided
     *   - version: cached value version number or null if the key is nonexistant
     *
     * Otherwise, $info will transform into the cached value timestamp.
     *
     * @param string $key Cache key made from makeKey()/makeGlobalKey()
     * @param mixed|null &$curTTL Approximate TTL left on the key if present/tombstoned [returned]
     * @param string[] $checkKeys The "check" keys used to validate the value
     * @param mixed|null &$info Key info if WANObjectCache::PASS_BY_REF [returned]
     * @return mixed Value of cache key or false on failure
     */
    final public function get(
        $key, &$curTTL = null, array $checkKeys = [], &$info = null
    ) {
        $curTTLs = self::PASS_BY_REF;
        $infoByKey = self::PASS_BY_REF;
        $values = $this->getMulti( [ $key ], $curTTLs, $checkKeys, $infoByKey );
        $curTTL = $curTTLs[$key] ?? null;
        if ( $info === self::PASS_BY_REF ) {
            $info = [
                'asOf' => $infoByKey[$key]['asOf'] ?? null,
                'tombAsOf' => $infoByKey[$key]['tombAsOf'] ?? null,
                'lastCKPurge' => $infoByKey[$key]['lastCKPurge'] ?? null,
                'version' => $infoByKey[$key]['version'] ?? null
            ];
        } else {
            $info = $infoByKey[$key]['asOf'] ?? null; // b/c
        }
        return array_key_exists( $key, $values ) ? $values[$key] : false;
    }
    /**
     * Fetch the value of several keys from cache
     *
     * Pass $info as WANObjectCache::PASS_BY_REF to transform it into a map of cache keys
     * to cache key metadata maps, each having the same style as those of WANObjectCache::get().
     * All the cache keys listed in $keys will have an entry.
     *
     * Othwerwise, $info will transform into a map of (cache key => cached value timestamp).
     * Only the cache keys listed in $keys that exists or are tombstoned will have an entry.
     *
     * $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.
     *
     * @see WANObjectCache::get()
     *
     * @param string[] $keys List/map with cache keys made from makeKey()/makeGlobalKey() as values
     * @param mixed|null &$curTTLs Map of (key => TTL left) for existing/tombstoned keys [returned]
     * @param string[]|string[][] $checkKeys Map of (integer or cache key => "check" key(s))
     * @param mixed|null &$info Map of (key => info) if WANObjectCache::PASS_BY_REF [returned]
     * @return mixed[] Map of (key => value) for existing values; order of $keys is preserved
     */
    final public function getMulti(
        array $keys,
        &$curTTLs = [],
        array $checkKeys = [],
        &$info = null
    ) {
        $result = [];
        $curTTLs = [];
        $infoByKey = [];
        // Order-corresponding list of value keys for the provided base keys
        $valueKeys = $this->makeSisterKeys( $keys, self::$TYPE_VALUE );
        $fullKeysNeeded = $valueKeys;
        $checkKeysForAll = [];
        $checkKeysByKey = [];
        foreach ( $checkKeys as $i => $checkKeyOrKeyGroup ) {
            // Note: avoid array_merge() inside loop in case there are many keys
            if ( is_int( $i ) ) {
                // Single check key that applies to all value keys
                $fullKey = $this->makeSisterKey( $checkKeyOrKeyGroup, self::$TYPE_TIMESTAMP );
                $fullKeysNeeded[] = $fullKey;
                $checkKeysForAll[] = $fullKey;
            } else {
                // List of check keys that apply to a specific value key
                foreach ( (array)$checkKeyOrKeyGroup as $checkKey ) {
                    $fullKey = $this->makeSisterKey( $checkKey, self::$TYPE_TIMESTAMP );
                    $fullKeysNeeded[] = $fullKey;
                    $checkKeysByKey[$i][] = $fullKey;
                }
            }
        }
        if ( $this->warmupCache ) {
            // Get the raw values of the keys from the warmup cache
            $wrappedValues = $this->warmupCache;
            $fullKeysMissing = array_diff( $fullKeysNeeded, array_keys( $wrappedValues ) );
            if ( $fullKeysMissing ) { // sanity
                $this->warmupKeyMisses += count( $fullKeysMissing );
                $wrappedValues += $this->cache->getMulti( $fullKeysMissing );
            }
        } else {
            // Fetch the raw values of the keys from the backend
            $wrappedValues = $this->cache->getMulti( $fullKeysNeeded );
        }
        // Time used to compare/init "check" keys (derived after getMulti() to be pessimistic)
        $now = $this->getCurrentTime();
        // Collect timestamps from all "check" keys
        $purgeValuesForAll = $this->processCheckKeys( $checkKeysForAll, $wrappedValues, $now );
        $purgeValuesByKey = [];
        foreach ( $checkKeysByKey as $cacheKey => $checks ) {
            $purgeValuesByKey[$cacheKey] = $this->processCheckKeys( $checks, $wrappedValues, $now );
        }
        // Get the main cache value for each key and validate them
        reset( $keys );
        foreach ( $valueKeys as $i => $vKey ) {
            // Get the corresponding base key for this value key
            $key = current( $keys );
            next( $keys );
            list( $value, $keyInfo ) = $this->unwrap(
                array_key_exists( $vKey, $wrappedValues ) ? $wrappedValues[$vKey] : false,
                $now
            );
            // Force dependent keys to be seen as stale for a while after purging
            // to reduce race conditions involving stale data getting cached
            $purgeValues = $purgeValuesForAll;
            if ( isset( $purgeValuesByKey[$key] ) ) {
                $purgeValues = array_merge( $purgeValues, $purgeValuesByKey[$key] );
            }
            $lastCKPurge = null; // timestamp of the highest check key
            foreach ( $purgeValues as $purge ) {
                $lastCKPurge = max( $purge[self::$PURGE_TIME], $lastCKPurge );
                $safeTimestamp = $purge[self::$PURGE_TIME] + $purge[self::$PURGE_HOLDOFF];
                if ( $value !== false && $safeTimestamp >= $keyInfo['asOf'] ) {
                    // How long ago this value was invalidated by *this* check key
                    $ago = min( $purge[self::$PURGE_TIME] - $now, self::$TINY_NEGATIVE );
                    // How long ago this value was invalidated by *any* known check key
                    $keyInfo['curTTL'] = min( $keyInfo['curTTL'], $ago );
                }
            }
            $keyInfo[ 'lastCKPurge'] = $lastCKPurge;
            if ( $value !== false ) {
                $result[$key] = $value;
            }
            if ( $keyInfo['curTTL'] !== null ) {
                $curTTLs[$key] = $keyInfo['curTTL'];
            }
            $infoByKey[$key] = ( $info === self::PASS_BY_REF )
                ? $keyInfo
                : $keyInfo['asOf']; // b/c
        }
        $info = $infoByKey;
        return $result;
    }
    /**
     * @param string[] $timeKeys List of prefixed time check keys
     * @param mixed[] $wrappedValues Preloaded map of (key => value)
     * @param float $now
     * @return array[] List of purge value arrays
     * @since 1.27
     */
    private function processCheckKeys( array $timeKeys, array $wrappedValues, $now ) {
        $purgeValues = [];
        foreach ( $timeKeys as $timeKey ) {
            $purge = isset( $wrappedValues[$timeKey] )
                ? $this->parsePurgeValue( $wrappedValues[$timeKey] )
                : false;
            if ( $purge === false ) {
                // Key is not set or malformed; regenerate
                $newVal = $this->makePurgeValue( $now, self::HOLDOFF_TTL );
                $this->cache->add( $timeKey, $newVal, self::$CHECK_KEY_TTL );
                $purge = $this->parsePurgeValue( $newVal );
            }
            $purgeValues[] = $purge;
        }
        return $purgeValues;
    }
    /**
     * Set the value of a key in cache
     *
     * Simply calling this method when source data changes is not valid because
     * the changes do not replicate to the other WAN sites. In that case, delete()
     * should be used instead. This method is intended for use on cache misses.
     *
     * If the data was read from a snapshot-isolated transactions (e.g. the default
     * REPEATABLE-READ in innoDB), use 'since' to avoid the following race condition:
     *   - a) T1 starts
     *   - b) T2 updates a row, calls delete(), and commits
     *   - c) The HOLDOFF_TTL passes, expiring the delete() tombstone
     *   - d) T1 reads the row and calls set() due to a cache miss
     *   - e) Stale value is stuck in cache
     *
     * Setting 'lag' and 'since' help avoids keys getting stuck in stale states.
     *
     * 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.
     *
     * Do not use this method on versioned keys accessed via getWithSetCallback().
     *
     * Example usage:
     * @code
     *     $dbr = wfGetDB( DB_REPLICA );
     *     $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 );
     * @endcode
     *
     * @param string $key Cache key
     * @param mixed $value
     * @param int $ttl Seconds 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)
     * @param array $opts Options map:
     *   - lag: Seconds of replica DB lag. Typically, this is either the replica DB lag
     *      before the data was read or, if applicable, the replica DB lag before
     *      the snapshot-isolated transaction the data was read from started.
     *      Use false to indicate that replication is not running.
     *      Default: 0 seconds
     *   - since: UNIX timestamp of the data in $value. Typically, this is either
     *      the current time the data was read or (if applicable) the time when
     *      the snapshot-isolated transaction the data was read from started.
     *      Default: 0 seconds
     *   - pending: Whether this data is possibly from an uncommitted write transaction.
     *      Generally, other threads should not see values from the future and
     *      they certainly should not see ones that ended up getting rolled back.
     *      Default: false
     *   - lockTSE: If excessive replication/snapshot lag is detected, then store the value
     *      with this TTL and flag it as stale. This is only useful if the reads for this key
     *      use getWithSetCallback() with "lockTSE" set. 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 regeneration 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
     * @codingStandardsIgnoreStart
     * @phan-param array{lag?:int,since?:int,pending?:bool,lockTSE?:int,staleTTL?:int,creating?:bool,version?:?string,walltime?:int|float} $opts
     * @codingStandardsIgnoreEnd
     * @note Options added in 1.28: staleTTL
     * @note Options added in 1.33: creating
     * @note Options added in 1.34: version, walltime
     * @return bool Success
     */
    final public function set( $key, $value, $ttl = self::TTL_INDEFINITE, array $opts = [] ) {
        $now = $this->getCurrentTime();
        $lag = $opts['lag'] ?? 0;
        $age = isset( $opts['since'] ) ? max( 0, $now - $opts['since'] ) : 0;
        $pending = $opts['pending'] ?? false;
        $lockTSE = $opts['lockTSE'] ?? self::TSE_NONE;
        $staleTTL = $opts['staleTTL'] ?? self::STALE_TTL_NONE;
        $creating = $opts['creating'] ?? false;
        $version = $opts['version'] ?? null;
        $walltime = $opts['walltime'] ?? null;
        if ( $ttl < 0 ) {
            return true; // not cacheable
        }
        // Do not cache potentially uncommitted data as it might get rolled back
        if ( $pending ) {
            $this->logger->info(
                'Rejected set() for {cachekey} due to pending writes.',
                [ 'cachekey' => $key ]
            );
            return true; // no-op the write for being unsafe
        }
        // Check if there is a risk of caching (stale) data that predates the last delete()
        // tombstone due to the tombstone having expired. If so, then the behavior should depend
        // on whether the problem is specific to this regeneration attempt or systemically affects
        // attempts to regenerate this key. For systemic cases, the cache writes should set a low
        // TTL so that the value at least remains cacheable. For non-systemic cases, the cache
        // write can simply be rejected.
        if ( $age > self::MAX_READ_LAG ) {
            // Case A: high snapshot lag
            if ( $walltime === null ) {
                // Case A0: high snapshot lag without regeneration wall time info.
                // Probably systemic; use a low TTL to avoid stampedes/uncacheability.
                $mitigated = 'snapshot lag';
                $mitigationTTL = self::TTL_SECOND;
            } elseif ( ( $age - $walltime ) > self::MAX_READ_LAG ) {
                // Case A1: value regeneration during an already long-running transaction.
                // Probably non-systemic; rely on a less problematic regeneration attempt.
                $mitigated = 'snapshot lag (late regeneration)';
                $mitigationTTL = self::TTL_UNCACHEABLE;
            } else {
                // Case A2: value regeneration takes a long time.
                // Probably systemic; use a low TTL to avoid stampedes/uncacheability.
                $mitigated = 'snapshot lag (high regeneration time)';
                $mitigationTTL = self::TTL_SECOND;
            }
        } elseif ( $lag === false || $lag > self::MAX_READ_LAG ) {
            // Case B: high replication lag without high snapshot lag
            // Probably systemic; use a low TTL to avoid stampedes/uncacheability
            $mitigated = 'replication lag';
            $mitigationTTL = self::TTL_LAGGED;
        } elseif ( ( $lag + $age ) > self::MAX_READ_LAG ) {
            // Case C: medium length request with medium replication lag
            // Probably non-systemic; rely on a less problematic regeneration attempt
            $mitigated = 'read lag';
            $mitigationTTL = self::TTL_UNCACHEABLE;
        } else {
            // New value generated with recent enough data
            $mitigated = null;
            $mitigationTTL = null;
        }
        if ( $mitigationTTL === self::TTL_UNCACHEABLE ) {
            $this->logger->warning(
                "Rejected set() for {cachekey} due to $mitigated.",
                [ 'cachekey' => $key, 'lag' => $lag, 'age' => $age, 'walltime' => $walltime ]
            );
            return true; // no-op the write for being unsafe
        }
        // TTL to use in staleness checks (does not effect persistence layer TTL)
        $logicalTTL = null;
        if ( $mitigationTTL !== null ) {
            // New value generated from data that is old enough to be risky
            if ( $lockTSE >= 0 ) {
                // Value will have the normal expiry but will be seen as stale sooner
                $logicalTTL = min( $ttl ?: INF, $mitigationTTL );
            } else {
                // Value expires sooner (leaving enough TTL for preemptive refresh)
                $ttl = min( $ttl ?: INF, max( $mitigationTTL, self::LOW_TTL ) );
            }
            $this->logger->warning(
                "Lowered set() TTL for {cachekey} due to $mitigated.",
                [ 'cachekey' => $key, 'lag' => $lag, 'age' => $age, 'walltime' => $walltime ]
            );
        }
        // Wrap that value with time/TTL/version metadata
        $wrapped = $this->wrap( $value, $logicalTTL ?: $ttl, $version, $now, $walltime );
        $storeTTL = $ttl + $staleTTL;
        if ( $creating ) {
            $ok = $this->cache->add(
                $this->makeSisterKey( $key, self::$TYPE_VALUE ),
                $wrapped,
                $storeTTL
            );
        } else {
            $ok = $this->cache->merge(
                $this->makeSisterKey( $key, self::$TYPE_VALUE ),
                function ( $cache, $key, $cWrapped ) use ( $wrapped ) {
                    // A string value means that it is a tombstone; do nothing in that case
                    return ( is_string( $cWrapped ) ) ? false : $wrapped;
                },
                $storeTTL,
                1 // 1 attempt
            );
        }
        return $ok;
    }
    /**
     * 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:
     * @code
     *     $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
     * @endcode
     *
     * The $ttl parameter can be used when purging values that have not actually changed
     * recently. For example, a cleanup script to purge cache entries does not really need
     * a hold-off period, so it can use HOLDOFF_TTL_NONE. Likewise for user-requested purge.
     * Note that $ttl limits the effective range of 'lockTSE' for getWithSetCallback().
     *
     * If called twice on the same key, then the last hold-off TTL takes precedence. For
     * idempotence, the $ttl should not vary for different delete() calls on the same key.
     *
     * @param string $key Cache key
     * @param int $ttl Tombstone TTL; Default: WANObjectCache::HOLDOFF_TTL
     * @return bool True if the item was purged or not found, false on failure
     */
    final public function delete( $key, $ttl = self::HOLDOFF_TTL ) {
        if ( $ttl <= 0 ) {
            // Publish the purge to all datacenters
            $ok = $this->relayDelete( $this->makeSisterKey( $key, self::$TYPE_VALUE ) );
        } else {
            // Publish the purge to all datacenters
            $ok = $this->relayPurge(
                $this->makeSisterKey( $key, self::$TYPE_VALUE ),
                $ttl,
                self::HOLDOFF_TTL_NONE
            );
        }
        $kClass = $this->determineKeyClassForStats( $key );
        $this->stats->increment( "wanobjectcache.$kClass.delete." . ( $ok ? 'ok' : 'error' ) );
        return $ok;
    }
    /**
     * 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.
     *
     * @param string $key
     * @return float UNIX timestamp
     */
    final public function getCheckKeyTime( $key ) {
        return $this->getMultiCheckKeyTime( [ $key ] )[$key];
    }
    /**
     * 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 dependant entities (either from the DB or the "check" keys).
     *
     * Example usage:
     * @code
     *     $value = $cache->getWithSetCallback(
     *         $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
     *     );
     * @endcode
     *
     * @see WANObjectCache::getCheckKeyTime()
     * @see WANObjectCache::getWithSetCallback()
     *
     * @param string[] $keys
     * @return float[] Map of (key => UNIX timestamp)
     * @since 1.31
     */
    final public function getMultiCheckKeyTime( array $keys ) {
        $rawKeys = [];
        foreach ( $keys as $key ) {
            $rawKeys[$key] = $this->makeSisterKey( $key, self::$TYPE_TIMESTAMP );
        }
        $rawValues = $this->cache->getMulti( $rawKeys );
        $rawValues += array_fill_keys( $rawKeys, false );
        $times = [];
        foreach ( $rawKeys as $key => $rawKey ) {
            $purge = $this->parsePurgeValue( $rawValues[$rawKey] );
            if ( $purge !== false ) {
                $time = $purge[self::$PURGE_TIME];
            } else {
                // Casting assures identical floats for the next getCheckKeyTime() calls
                $now = (string)$this->getCurrentTime();
                $this->cache->add(
                    $rawKey,
                    $this->makePurgeValue( $now, self::HOLDOFF_TTL ),
                    self::$CHECK_KEY_TTL
                );
                $time = (float)$now;
            }
            $times[$key] = $time;
        }
        return $times;
    }
    /**
     * 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 WANObjectCache::get()
     * @see WANObjectCache::getWithSetCallback()
     * @see WANObjectCache::resetCheckKey()
     *
     * @param string $key Cache key
     * @param int $holdoff HOLDOFF_TTL or HOLDOFF_TTL_NONE constant
     * @return bool True if the item was purged or not found, false on failure
     */
    final public function touchCheckKey( $key, $holdoff = self::HOLDOFF_TTL ) {
        // Publish the purge to all datacenters
        $ok = $this->relayPurge(
            $this->makeSisterKey( $key, self::$TYPE_TIMESTAMP ),
            self::$CHECK_KEY_TTL,
            $holdoff
        );
        $kClass = $this->determineKeyClassForStats( $key );
        $this->stats->increment( "wanobjectcache.$kClass.ck_touch." . ( $ok ? 'ok' : 'error' ) );
        return $ok;
    }
    /**
     * 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 WANObjectCache::get()
     * @see WANObjectCache::getWithSetCallback()
     * @see WANObjectCache::touchCheckKey()
     *
     * @param string $key Cache key
     * @return bool True if the item was purged or not found, false on failure
     */
    final public function resetCheckKey( $key ) {
        // Publish the purge to all datacenters
        $ok = $this->relayDelete( $this->makeSisterKey( $key, self::$TYPE_TIMESTAMP ) );
        $kClass = $this->determineKeyClassForStats( $key );
        $this->stats->increment( "wanobjectcache.$kClass.ck_reset." . ( $ok ? 'ok' : 'error' ) );
        return $ok;
    }
    /**
     * 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-dependant 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 )
     *
     * Example usage (typical key):
     * @code
     *     $catInfo = $cache->getWithSetCallback(
     *         // 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 ) {
     *             $dbr = wfGetDB( DB_REPLICA );
     *             // Account for any snapshot/replica DB lag
     *             $setOpts += Database::getCacheSetOptions( $dbr );
     *
     *             return $dbr->selectRow( ... );
     *        }
     *     );
     * @endcode
     *
     * Example usage (key that is expensive and hot):
     * @code
     *     $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 ) {
     *             $dbr = wfGetDB( DB_REPLICA );
     *             // 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
     *         ]
     *     );
     * @endcode
     *
     * Example usage (key with dynamic dependencies):
     * @code
     *     $catState = $cache->getWithSetCallback(
     *         // 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
     *             $dbr = wfGetDB( DB_REPLICA );
     *             // 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() ),
     *             ]
     *         ]
     *     );
     * @endcode
     *
     * Example usage (key that is expensive with too many DB dependencies for "check keys"):
     * @code
     *     $catToys = $cache->getWithSetCallback(
     *         // 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
     *             $dbr = wfGetDB( DB_REPLICA );
     *             // 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 ) {
     *                 $dbr = wfGetDB( DB_REPLICA );
     *                 $ts = $dbr->selectField( 'cat_toys', 'MAX(ct_touched)', ... );
     *
     *                 return wfTimestampOrNull( TS_UNIX, $ts );
     *             },
     *             // Avoid DB queries for repeated access
     *             'pcTTL' => $cache::TTL_PROC_SHORT
     *         ]
     *     );
     * @endcode
     *
     * Example usage (hot key holding most recent 100 events):
     * @code
     *     $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 ) {
     *             $dbr = wfGetDB( DB_REPLICA );
     *             // 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'
     *        ]
     *     );
     * @endcode
     *
     * 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):
     * @code
     *     $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 );
     * @endcode
     *
     * @see WANObjectCache::get()
     * @see WANObjectCache::set()
     *
     * @param string $key Cache key made from makeKey()/makeGlobalKey()
     * @param int $ttl Nominal 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)
     * @param callable $callback Value generation function
     * @param array $opts Options 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"/"touchedCallback") less than this
     *      many seconds ago, consider reusing the stale value. 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. 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: If the key is tombstoned or invalidated (by "checkKeys"/"touchedCallback")
     *      less than this many seconds ago, try to have a single thread handle cache regeneration
     *      at any given time. Other threads will use stale values if possible. If, on miss,
     *      the time since expiration is low, the assumption is that the key is hot and that a
     *      stampede is worth avoiding. Note that if the key falls out of cache then concurrent
     *      threads will all run the callback on cache miss until the value is saved in cache.
     *      The only stampede protection in that case is from duplicate cache sets when the
     *      callback is slow and/or yields large values; consider using "busyValue" if such
     *      stampedes are a problem (e.g. high query load). Note that the higher "lockTSE" is
     *      set, the higher the worst-case staleness of returned values can be. Also note that
     *      this option does not by itself handle the case of the key simply expiring on account
     *      of its TTL, so make sure that "lowTTL" is not disabled when using this option. Avoid
     *      combining this option with delete() as it can always cause a stampede due to their
     *      being no stale value available until after a thread completes the callback.
     *      Use WANObjectCache::TSE_NONE to disable this logic.
     *      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.
     * @param array $cbParams Custom field/value map to pass to the callback (since 1.35)
     * @codingStandardsIgnoreStart
     * @phan-param array{checkKeys?:string[],graceTTL?:int,lockTSE?:int,busyValue?:mixed,pcTTL?:int,pcGroup?:string,version?:int,minAsOf?:int,hotTTR?:int,lowTTL?:int,ageNew?:int,staleTTL?:int,touchedCallback?:callable} $opts
     * @codingStandardsIgnoreEnd
     * @return mixed Value found or written to the key
     * @note Options added in 1.28: version, busyValue, hotTTR, ageNew, pcGroup, minAsOf
     * @note Options added in 1.31: staleTTL, graceTTL
     * @note Options added in 1.33: touchedCallback
     * @note Callable type hints are not used to avoid class-autoloading
     */
    final public function getWithSetCallback(
        $key, $ttl, $callback, array $opts = [], array $cbParams = []
    ) {
        $version = $opts['version'] ?? null;
        $pcTTL = $opts['pcTTL'] ?? self::TTL_UNCACHEABLE;
        $pCache = ( $pcTTL >= 0 )
            ? $this->getProcessCache( $opts['pcGroup'] ?? self::PC_PRIMARY )
            : null;
        // Use the process cache if requested as long as no outer cache callback is running.
        // Nested callback process cache use is not lag-safe with regard to HOLDOFF_TTL since
        // process cached values are more lagged than persistent ones as they are not purged.
        if ( $pCache && $this->callbackDepth == 0 ) {
            $cached = $pCache->get( $this->getProcessCacheKey( $key, $version ), $pcTTL, false );
            if ( $cached !== false ) {
                $this->logger->debug( "getWithSetCallback($key): process cache hit" );
                return $cached;
            }
        }
        $res = $this->fetchOrRegenerate( $key, $ttl, $callback, $opts, $cbParams );
        list( $value, $valueVersion, $curAsOf ) = $res;
        if ( $valueVersion !== $version ) {
            // Current value has a different version; use the variant key for this version.
            // Regenerate the variant value if it is not newer than the main value at $key
            // so that purges to the main key propagate to the variant value.
            $this->logger->debug( "getWithSetCallback($key): using variant key" );
            list( $value ) = $this->fetchOrRegenerate(
                $this->makeGlobalKey( 'WANCache-key-variant', md5( $key ), $version ),
                $ttl,
                $callback,
                [ 'version' => null, 'minAsOf' => $curAsOf ] + $opts,
                $cbParams
            );
        }
        // Update the process cache if enabled
        if ( $pCache && $value !== false ) {
            $pCache->set( $this->getProcessCacheKey( $key, $version ), $value );
        }
        return $value;
    }
    /**
     * Do the actual I/O for getWithSetCallback() when needed
     *
     * @see WANObjectCache::getWithSetCallback()
     *
     * @param string $key
     * @param int $ttl
     * @param callable $callback
     * @param array $opts
     * @param array $cbParams
     * @return 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
     */
    private function fetchOrRegenerate( $key, $ttl, $callback, array $opts, array $cbParams ) {
        $checkKeys = $opts['checkKeys'] ?? [];
        $graceTTL = $opts['graceTTL'] ?? self::GRACE_TTL_NONE;
        $minAsOf = $opts['minAsOf'] ?? self::MIN_TIMESTAMP_NONE;
        $hotTTR = $opts['hotTTR'] ?? self::HOT_TTR;
        $lowTTL = $opts['lowTTL'] ?? min( self::LOW_TTL, $ttl );
        $ageNew = $opts['ageNew'] ?? self::AGE_NEW;
        $touchedCb = $opts['touchedCallback'] ?? null;
        $initialTime = $this->getCurrentTime();
        $kClass = $this->determineKeyClassForStats( $key );
        // Get the current key value and its metadata
        $curTTL = self::PASS_BY_REF;
        $curInfo = self::PASS_BY_REF;
        $curValue = $this->get( $key, $curTTL, $checkKeys, $curInfo );
        /** @var array $curInfo */
        '@phan-var array $curInfo';
        // Apply any $touchedCb invalidation timestamp to get the "last purge timestamp"
        list( $curTTL, $LPT ) = $this->resolveCTL( $curValue, $curTTL, $curInfo, $touchedCb );
        // Use the cached value if it exists and is not due for synchronous regeneration
        if (
            $this->isValid( $curValue, $curInfo['asOf'], $minAsOf ) &&
            $this->isAliveOrInGracePeriod( $curTTL, $graceTTL )
        ) {
            $preemptiveRefresh = (
                $this->worthRefreshExpiring( $curTTL, $lowTTL ) ||
                $this->worthRefreshPopular( $curInfo['asOf'], $ageNew, $hotTTR, $initialTime )
            );
            if ( !$preemptiveRefresh ) {
                $this->stats->increment( "wanobjectcache.$kClass.hit.good" );
                return [ $curValue, $curInfo['version'], $curInfo['asOf'] ];
            } elseif ( $this->scheduleAsyncRefresh( $key, $ttl, $callback, $opts, $cbParams ) ) {
                $this->logger->debug( "fetchOrRegenerate($key): hit with async refresh" );
                $this->stats->increment( "wanobjectcache.$kClass.hit.refresh" );
                return [ $curValue, $curInfo['version'], $curInfo['asOf'] ];
            } else {
                $this->logger->debug( "fetchOrRegenerate($key): hit with sync refresh" );
            }
        }
        // Determine if there is stale or volatile cached value that is still usable
        $isKeyTombstoned = ( $curInfo['tombAsOf'] !== null );
        if ( $isKeyTombstoned ) {
            // Key is write-holed; use the (volatile) interim key as an alternative
            list( $possValue, $possInfo ) = $this->getInterimValue( $key, $minAsOf );
            // Update the "last purge time" since the $touchedCb timestamp depends on $value
            $LPT = $this->resolveTouched( $possValue, $LPT, $touchedCb );
        } else {
            $possValue = $curValue;
            $possInfo = $curInfo;
        }
        // Avoid overhead from callback runs, regeneration locks, and cache sets during
        // hold-off periods for the key by reusing very recently generated cached values
        if (
            $this->isValid( $possValue, $possInfo['asOf'], $minAsOf, $LPT ) &&
            $this->isVolatileValueAgeNegligible( $initialTime - $possInfo['asOf'] )
        ) {
            $this->logger->debug( "fetchOrRegenerate($key): volatile hit" );
            $this->stats->increment( "wanobjectcache.$kClass.hit.volatile" );
            return [ $possValue, $possInfo['version'], $curInfo['asOf'] ];
        }
        $lockTSE = $opts['lockTSE'] ?? self::TSE_NONE;
        $busyValue = $opts['busyValue'] ?? null;
        $staleTTL = $opts['staleTTL'] ?? self::STALE_TTL_NONE;
        $version = $opts['version'] ?? null;
        // Determine whether one thread per datacenter should handle regeneration at a time
        $useRegenerationLock =
            // Note that since tombstones no-op set(), $lockTSE and $curTTL cannot be used to
            // deduce the key hotness because |$curTTL| will always keep increasing until the
            // tombstone expires or is overwritten by a new tombstone. Also, even if $lockTSE
            // is not set, constant regeneration of a key for the tombstone lifetime might be
            // very expensive. Assume tombstoned keys are possibly hot in order to reduce
            // the risk of high regeneration load after the delete() method is called.
            $isKeyTombstoned ||
            // Assume a key is hot if requested soon ($lockTSE seconds) after invalidation.
            // This avoids stampedes when timestamps from $checkKeys/$touchedCb bump.
            ( $curTTL !== null && $curTTL <= 0 && abs( $curTTL ) <= $lockTSE ) ||
            // Assume a key is hot if there is no value and a busy fallback is given.
            // This avoids stampedes on eviction or preemptive regeneration taking too long.
            ( $busyValue !== null && $possValue === false );
        // If a regeneration lock is required, threads that do not get the lock will try to use
        // the stale value, the interim value, or the $busyValue placeholder, in that order. If
        // none of those are set then all threads will bypass the lock and regenerate the value.
        $hasLock = $useRegenerationLock && $this->claimStampedeLock( $key );
        if ( $useRegenerationLock && !$hasLock ) {
            if ( $this->isValid( $possValue, $possInfo['asOf'], $minAsOf ) ) {
                $this->logger->debug( "fetchOrRegenerate($key): returning stale value" );
                $this->stats->increment( "wanobjectcache.$kClass.hit.stale" );
                return [ $possValue, $possInfo['version'], $curInfo['asOf'] ];
            } elseif ( $busyValue !== null ) {
                $miss = is_infinite( $minAsOf ) ? 'renew' : 'miss';
                $this->logger->debug( "fetchOrRegenerate($key): busy $miss" );
                $this->stats->increment( "wanobjectcache.$kClass.$miss.busy" );
                return [ $this->resolveBusyValue( $busyValue ), $version, $curInfo['asOf'] ];
            }
        }
        // Generate the new value given any prior value with a matching version
        $setOpts = [];
        $preCallbackTime = $this->getCurrentTime();
        ++$this->callbackDepth;
        try {
            $value = $callback(
                ( $curInfo['version'] === $version ) ? $curValue : false,
                $ttl,
                $setOpts,
                ( $curInfo['version'] === $version ) ? $curInfo['asOf'] : null,
                $cbParams
            );
        } finally {
            --$this->callbackDepth;
        }
        $postCallbackTime = $this->getCurrentTime();
        // How long it took to fetch, validate, and generate the value
        $elapsed = max( $postCallbackTime - $initialTime, 0.0 );
        // Attempt to save the newly generated value if applicable
        if (
            // Callback yielded a cacheable value
            ( $value !== false && $ttl >= 0 ) &&
            // Current thread was not raced out of a regeneration lock or key is tombstoned
            ( !$useRegenerationLock || $hasLock || $isKeyTombstoned ) &&
            // Key does not appear to be undergoing a set() stampede
            $this->checkAndSetCooloff(