Merge "Add Parser to MediaWikiServices"
[lhc/web/wiklou.git] / includes / libs / objectcache / WANObjectCache.php
index 5563b22..8d3c6d9 100644 (file)
@@ -76,8 +76,8 @@ use Psr\Log\NullLogger;
 class WANObjectCache implements IExpiringStore, LoggerAwareInterface {
        /** @var BagOStuff The local datacenter cache */
        protected $cache;
-       /** @var HashBagOStuff Script instance PHP cache */
-       protected $procCache;
+       /** @var HashBagOStuff[] Map of group PHP instance caches */
+       protected $processCaches = [];
        /** @var string Purge channel name */
        protected $purgeChannel;
        /** @var EventRelayer Bus that handles purge broadcasts */
@@ -88,6 +88,11 @@ class WANObjectCache implements IExpiringStore, LoggerAwareInterface {
        /** @var int ERR_* constant for the "last error" registry */
        protected $lastRelayError = self::ERR_NONE;
 
+       /** @var integer Callback stack depth for getWithSetCallback() */
+       private $callbackDepth = 0;
+       /** @var mixed[] Temporary warm-up cache */
+       private $warmupCache = [];
+
        /** Max time expected to pass between delete() and DB commit finishing */
        const MAX_COMMIT_DELAY = 3;
        /** Max replication+snapshot lag before applying TTL_LAGGED or disallowing set() */
@@ -121,6 +126,8 @@ class WANObjectCache implements IExpiringStore, LoggerAwareInterface {
        const TTL_LAGGED = 30;
        /** Idiom for delete() for "no hold-off" */
        const HOLDOFF_NONE = 0;
+       /** Idiom for getWithSetCallback() for "no minimum required as-of timestamp" */
+       const MIN_TIMESTAMP_NONE = 0.0;
 
        /** Tiny negative float to use when CTL comes up >= 0 due to clock skew */
        const TINY_NEGATIVE = -0.000001;
@@ -154,7 +161,7 @@ class WANObjectCache implements IExpiringStore, LoggerAwareInterface {
        const VFLD_DATA = 'WOC:d'; // key to the value of versioned data
        const VFLD_VERSION = 'WOC:v'; // key to the version of the value present
 
-       const MAX_PC_KEYS = 1000; // max keys to keep in process cache
+       const PC_PRIMARY = 'primary:1000'; // process cache name and max key count
 
        const DEFAULT_PURGE_CHANNEL = 'wancache-purge';
 
@@ -167,7 +174,6 @@ class WANObjectCache implements IExpiringStore, LoggerAwareInterface {
         */
        public function __construct( array $params ) {
                $this->cache = $params['cache'];
-               $this->procCache = new HashBagOStuff( [ 'maxKeys' => self::MAX_PC_KEYS ] );
                $this->purgeChannel = isset( $params['channels']['purge'] )
                        ? $params['channels']['purge']
                        : self::DEFAULT_PURGE_CHANNEL;
@@ -283,7 +289,14 @@ class WANObjectCache implements IExpiringStore, LoggerAwareInterface {
                }
 
                // Fetch all of the raw values
-               $wrappedValues = $this->cache->getMulti( array_merge( $valueKeys, $checkKeysFlat ) );
+               $keysGet = array_merge( $valueKeys, $checkKeysFlat );
+               if ( $this->warmupCache ) {
+                       $wrappedValues = array_intersect_key( $this->warmupCache, array_flip( $keysGet ) );
+                       $keysGet = array_diff( $keysGet, array_keys( $wrappedValues ) ); // keys left to fetch
+               } else {
+                       $wrappedValues = [];
+               }
+               $wrappedValues += $this->cache->getMulti( $keysGet );
                // Time used to compare/init "check" keys (derived after getMulti() to be pessimistic)
                $now = microtime( true );
 
@@ -386,22 +399,30 @@ class WANObjectCache implements IExpiringStore, LoggerAwareInterface {
         * @param integer $ttl Seconds to live. Special values are:
         *   - WANObjectCache::TTL_INDEFINITE: Cache forever
         * @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.
-        *               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
+        *   - 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
+        *      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.
-        *               Default: WANObjectCache::TSE_NONE
+        *      with this TTL and flag it as stale. This is only useful if the reads for
+        *      this key use getWithSetCallback() with "lockTSE" set.
+        *      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: 0.
+        * @note Options added in 1.28: staleTTL
         * @return bool Success
         */
        final public function set( $key, $value, $ttl = 0, array $opts = [] ) {
@@ -409,6 +430,7 @@ class WANObjectCache implements IExpiringStore, LoggerAwareInterface {
                $lockTSE = isset( $opts['lockTSE'] ) ? $opts['lockTSE'] : self::TSE_NONE;
                $age = isset( $opts['since'] ) ? max( 0, $now - $opts['since'] ) : 0;
                $lag = isset( $opts['lag'] ) ? $opts['lag'] : 0;
+               $staleTTL = isset( $opts['staleTTL'] ) ? $opts['staleTTL'] : 0;
 
                // Do not cache potentially uncommitted data as it might get rolled back
                if ( !empty( $opts['pending'] ) ) {
@@ -450,7 +472,7 @@ class WANObjectCache implements IExpiringStore, LoggerAwareInterface {
                                : $wrapped;
                };
 
-               return $this->cache->merge( self::VALUE_KEY_PREFIX . $key, $func, $ttl, 1 );
+               return $this->cache->merge( self::VALUE_KEY_PREFIX . $key, $func, $ttl + $staleTTL, 1 );
        }
 
        /**
@@ -644,6 +666,7 @@ class WANObjectCache implements IExpiringStore, LoggerAwareInterface {
         *   - $oldValue : current cache value or false if not present
         *   - &$ttl : a reference to the TTL which can be altered
         *   - &$setOpts : a reference to options for set() which can be altered
+        *   - $oldAsOf : generation UNIX timestamp of $oldValue or null if not present (since 1.28)
         *
         * 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
@@ -793,11 +816,21 @@ class WANObjectCache implements IExpiringStore, LoggerAwareInterface {
         *      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 allows for callers to make breaking changes to
         *      how values are stored while maintaining compatability and correct cache purges. New
         *      versions are stored alongside older versions concurrently. Avoid storing class objects
         *      however, 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 for keys that average ~1 hit/second.
         *      This should be greater than "ageNew". Keys with higher hit rates will regenerate
         *      more often. This is useful when a popular key is changed but the cache purge was
@@ -810,17 +843,25 @@ class WANObjectCache implements IExpiringStore, LoggerAwareInterface {
         *   - ageNew: Consider popularity refreshes only once a key reaches this age in seconds.
         *      Default: WANObjectCache::AGE_NEW.
         * @return mixed Value found or written to the key
+        * @note Options added in 1.28: version, busyValue, hotTTR, ageNew, pcGroup, minAsOf
         * @note Callable type hints are not used to avoid class-autoloading
         */
        final public function getWithSetCallback( $key, $ttl, $callback, array $opts = [] ) {
                $pcTTL = isset( $opts['pcTTL'] ) ? $opts['pcTTL'] : self::TTL_UNCACHEABLE;
 
-               // Try the process cache if enabled
-               $value = ( $pcTTL >= 0 ) ? $this->procCache->get( $key ) : false;
+               // Try the process cache if enabled and the cache callback is not within a cache callback.
+               // Process cache use in nested callbacks is not lag-safe with regard to HOLDOFF_TTL since
+               // the in-memory value is further lagged than the shared one since it uses a blind TTL.
+               if ( $pcTTL >= 0 && $this->callbackDepth == 0 ) {
+                       $group = isset( $opts['pcGroup'] ) ? $opts['pcGroup'] : self::PC_PRIMARY;
+                       $procCache = $this->getProcessCache( $group );
+                       $value = $procCache->get( $key );
+               } else {
+                       $procCache = false;
+                       $value = false;
+               }
 
                if ( $value === false ) {
-                       unset( $opts['minTime'] ); // not a public feature
-
                        // Fetch the value over the network
                        if ( isset( $opts['version'] ) ) {
                                $version = $opts['version'];
@@ -828,7 +869,8 @@ class WANObjectCache implements IExpiringStore, LoggerAwareInterface {
                                $cur = $this->doGetWithSetCallback(
                                        $key,
                                        $ttl,
-                                       function ( $oldValue, &$ttl, &$setOpts ) use ( $callback, $version ) {
+                                       function ( $oldValue, &$ttl, &$setOpts, $oldAsOf )
+                                       use ( $callback, $version ) {
                                                if ( is_array( $oldValue )
                                                        && array_key_exists( self::VFLD_DATA, $oldValue )
                                                ) {
@@ -839,7 +881,7 @@ class WANObjectCache implements IExpiringStore, LoggerAwareInterface {
                                                }
 
                                                return [
-                                                       self::VFLD_DATA => $callback( $oldData, $ttl, $setOpts ),
+                                                       self::VFLD_DATA => $callback( $oldData, $ttl, $setOpts, $oldAsOf ),
                                                        self::VFLD_VERSION => $version
                                                ];
                                        },
@@ -857,7 +899,7 @@ class WANObjectCache implements IExpiringStore, LoggerAwareInterface {
                                                $ttl,
                                                $callback,
                                                // Regenerate value if not newer than $key
-                                               [ 'version' => null, 'minTime' => $asOf ] + $opts
+                                               [ 'version' => null, 'minAsOf' => $asOf ] + $opts
                                        );
                                }
                        } else {
@@ -865,8 +907,8 @@ class WANObjectCache implements IExpiringStore, LoggerAwareInterface {
                        }
 
                        // Update the process cache if enabled
-                       if ( $pcTTL >= 0 && $value !== false ) {
-                               $this->procCache->set( $key, $value, $pcTTL );
+                       if ( $procCache && $value !== false ) {
+                               $procCache->set( $key, $value, $pcTTL );
                        }
                }
 
@@ -881,8 +923,7 @@ class WANObjectCache implements IExpiringStore, LoggerAwareInterface {
         * @param string $key
         * @param integer $ttl
         * @param callback $callback
-        * @param array $opts Options map for getWithSetCallback() which also includes:
-        *   - minTime: Treat values older than this UNIX timestamp as not existing. Default: null.
+        * @param array $opts Options map for getWithSetCallback()
         * @param float &$asOf Cache generation timestamp of returned value [returned]
         * @return mixed
         * @note Callable type hints are not used to avoid class-autoloading
@@ -894,7 +935,7 @@ class WANObjectCache implements IExpiringStore, LoggerAwareInterface {
                $busyValue = isset( $opts['busyValue'] ) ? $opts['busyValue'] : null;
                $popWindow = isset( $opts['hotTTR'] ) ? $opts['hotTTR'] : self::HOT_TTR;
                $ageNew = isset( $opts['ageNew'] ) ? $opts['ageNew'] : self::AGE_NEW;
-               $minTime = isset( $opts['minTime'] ) ? $opts['minTime'] : 0.0;
+               $minTime = isset( $opts['minAsOf'] ) ? $opts['minAsOf'] : self::MIN_TIMESTAMP_NONE;
                $versioned = isset( $opts['version'] );
 
                // Get the current key value
@@ -902,12 +943,13 @@ class WANObjectCache implements IExpiringStore, LoggerAwareInterface {
                $cValue = $this->get( $key, $curTTL, $checkKeys, $asOf ); // current value
                $value = $cValue; // return value
 
-               // Determine if a regeneration is desired
+               $preCallbackTime = microtime( true );
+               // Determine if a cached value regeneration is needed or desired
                if ( $value !== false
                        && $curTTL > 0
                        && $this->isValid( $value, $versioned, $asOf, $minTime )
                        && !$this->worthRefreshExpiring( $curTTL, $lowTTL )
-                       && !$this->worthRefreshPopular( $asOf, $ageNew, $popWindow )
+                       && !$this->worthRefreshPopular( $asOf, $ageNew, $popWindow, $preCallbackTime )
                ) {
                        return $value;
                }
@@ -957,13 +999,18 @@ class WANObjectCache implements IExpiringStore, LoggerAwareInterface {
 
                // Generate the new value from the callback...
                $setOpts = [];
-               $value = call_user_func_array( $callback, [ $cValue, &$ttl, &$setOpts ] );
-               $asOf = microtime( true );
+               ++$this->callbackDepth;
+               try {
+                       $value = call_user_func_array( $callback, [ $cValue, &$ttl, &$setOpts, $asOf ] );
+               } finally {
+                       --$this->callbackDepth;
+               }
                // When delete() is called, writes are write-holed by the tombstone,
                // so use a special INTERIM key to pass the new value around threads.
                if ( ( $isTombstone && $lockTSE > 0 ) && $value !== false && $ttl >= 0 ) {
                        $tempTTL = max( 1, (int)$lockTSE ); // set() expects seconds
-                       $wrapped = $this->wrap( $value, $tempTTL, $asOf );
+                       $newAsOf = microtime( true );
+                       $wrapped = $this->wrap( $value, $tempTTL, $newAsOf );
                        // Avoid using set() to avoid pointless mcrouter broadcasting
                        $this->cache->merge(
                                self::INTERIM_KEY_PREFIX . $key,
@@ -976,8 +1023,10 @@ class WANObjectCache implements IExpiringStore, LoggerAwareInterface {
                }
 
                if ( $value !== false && $ttl >= 0 ) {
-                       // Update the cache; this will fail if the key is tombstoned
                        $setOpts['lockTSE'] = $lockTSE;
+                       // Use best known "since" timestamp if not provided
+                       $setOpts += [ 'since' => $preCallbackTime ];
+                       // Update the cache; this will fail if the key is tombstoned
                        $this->set( $key, $value, $ttl, $setOpts );
                }
 
@@ -989,6 +1038,95 @@ class WANObjectCache implements IExpiringStore, LoggerAwareInterface {
                return $value;
        }
 
+       /**
+        * Method to fetch/regenerate multiple cache keys at once
+        *
+        * This works the same as getWithSetCallback() except:
+        *   - a) The $keys argument expects the result of WANObjectCache::makeMultiKeys()
+        *   - b) The $callback argument expects a callback taking the following arguments:
+        *         - $id: ID of an entity to query
+        *         - $oldValue : the prior cache value or false if none was present
+        *         - &$ttl : a reference to the new value TTL in seconds
+        *         - &$setOpts : a reference to options for set() which can be altered
+        *         - $oldAsOf : generation UNIX timestamp of $oldValue or null if not present
+        *        Aside from the additional $id argument, the other arguments function the same
+        *        way they do in getWithSetCallback().
+        *   - c) The return value is a map of (cache key => value) in the order of $keyedIds
+        *
+        * @see WANObjectCache::getWithSetCallback()
+        *
+        * Example usage:
+        * @code
+        *     $rows = $cache->getMultiWithSetCallback(
+        *         // Map of cache keys to entity IDs
+        *         $cache->makeMultiKeys(
+        *             $this->fileVersionIds(),
+        *             function ( $id, WANObjectCache $cache ) {
+        *                 return $cache->makeKey( 'file-version', $id );
+        *             }
+        *         ),
+        *         // Time-to-live (in seconds)
+        *         $cache::TTL_DAY,
+        *         // Function that derives the new key value
+        *         return function ( $id, $oldValue, &$ttl, array &$setOpts ) {
+        *             $dbr = wfGetDB( DB_REPLICA );
+        *             // Account for any snapshot/replica DB lag
+        *             $setOpts += Database::getCacheSetOptions( $dbr );
+        *
+        *             // Load the row for this file
+        *             $row = $dbr->selectRow( 'file', '*', [ 'id' => $id ], __METHOD__ );
+        *
+        *             return $row ? (array)$row : false;
+        *         },
+        *         [
+        *             // Process cache for 30 seconds
+        *             'pcTTL' => 30,
+        *             // Use a dedicated 500 item cache (initialized on-the-fly)
+        *             'pcGroup' => 'file-versions:500'
+        *         ]
+        *     );
+        *     $files = array_map( [ __CLASS__, 'newFromRow' ], $rows );
+        * @endcode
+        *
+        * @param ArrayIterator $keyedIds Result of WANObjectCache::makeMultiKeys()
+        * @param integer $ttl Seconds to live for key updates
+        * @param callable $callback Callback the yields entity regeneration callbacks
+        * @param array $opts Options map
+        * @return array Map of (cache key => value) in the same order as $keyedIds
+        * @since 1.28
+        */
+       final public function getMultiWithSetCallback(
+               ArrayIterator $keyedIds, $ttl, callable $callback, array $opts = []
+       ) {
+               $keysWarmUp = iterator_to_array( $keyedIds, true );
+               $checkKeys = isset( $opts['checkKeys'] ) ? $opts['checkKeys'] : [];
+               foreach ( $checkKeys as $i => $checkKeyOrKeys ) {
+                       if ( is_int( $i ) ) {
+                               $keysWarmUp[] = $checkKeyOrKeys;
+                       } else {
+                               $keysWarmUp = array_merge( $keysWarmUp, $checkKeyOrKeys );
+                       }
+               }
+
+               $this->warmupCache = $this->cache->getMulti( $keysWarmUp );
+               $this->warmupCache += array_fill_keys( $keysWarmUp, false );
+
+               // Wrap $callback to match the getWithSetCallback() format while passing $id to $callback
+               $id = null;
+               $func = function ( $oldValue, &$ttl, array $setOpts, $oldAsOf ) use ( $callback, &$id ) {
+                       return $callback( $id, $oldValue, $ttl, $setOpts, $oldAsOf );
+               };
+
+               $values = [];
+               foreach ( $keyedIds as $key => $id ) {
+                       $values[$key] = $this->getWithSetCallback( $key, $ttl, $func, $opts );
+               }
+
+               $this->warmupCache = [];
+
+               return $values;
+       }
+
        /**
         * @see BagOStuff::makeKey()
         * @param string ... Key component
@@ -1009,6 +1147,21 @@ class WANObjectCache implements IExpiringStore, LoggerAwareInterface {
                return call_user_func_array( [ $this->cache, __FUNCTION__ ], func_get_args() );
        }
 
+       /**
+        * @param array $entities List of entity IDs
+        * @param callable $keyFunc Callback yielding a key from (entity ID, this WANObjectCache)
+        * @return ArrayIterator Iterator yielding (cache key => entity ID) in $entities order
+        * @since 1.28
+        */
+       public function makeMultiKeys( array $entities, callable $keyFunc ) {
+               $map = [];
+               foreach ( $entities as $entity ) {
+                       $map[$keyFunc( $entity, $this )] = $entity;
+               }
+
+               return new ArrayIterator( $map );
+       }
+
        /**
         * Get the "last error" registered; clearLastError() should be called manually
         * @return int ERR_* class constant for the "last error" registry
@@ -1050,7 +1203,7 @@ class WANObjectCache implements IExpiringStore, LoggerAwareInterface {
         * @since 1.27
         */
        public function clearProcessCache() {
-               $this->procCache->clear();
+               $this->processCaches = [];
        }
 
        /**
@@ -1195,10 +1348,11 @@ class WANObjectCache implements IExpiringStore, LoggerAwareInterface {
         * @param float $asOf UNIX timestamp of the value
         * @param integer $ageNew Age of key when this might recommend refreshing (seconds)
         * @param integer $timeTillRefresh Age of key when it should be refreshed if popular (seconds)
+        * @param float $now The current UNIX timestamp
         * @return bool
         */
-       protected function worthRefreshPopular( $asOf, $ageNew, $timeTillRefresh ) {
-               $age = microtime( true ) - $asOf;
+       protected function worthRefreshPopular( $asOf, $ageNew, $timeTillRefresh, $now ) {
+               $age = $now - $asOf;
                $timeOld = $age - $ageNew;
                if ( $timeOld <= 0 ) {
                        return false;
@@ -1340,4 +1494,17 @@ class WANObjectCache implements IExpiringStore, LoggerAwareInterface {
        protected function makePurgeValue( $timestamp, $holdoff ) {
                return self::PURGE_VAL_PREFIX . (float)$timestamp . ':' . (int)$holdoff;
        }
+
+       /**
+        * @param string $group
+        * @return HashBagOStuff
+        */
+       protected function getProcessCache( $group ) {
+               if ( !isset( $this->processCaches[$group] ) ) {
+                       list( , $n ) = explode( ':', $group );
+                       $this->processCaches[$group] = new HashBagOStuff( [ 'maxKeys' => (int)$n ] );
+               }
+
+               return $this->processCaches[$group];
+       }
 }