Merge "jquery.textSelection: Remove code supporting IE 6 selection APIs"

[lhc/web/wiklou.git] / includes / libs / objectcache / WANObjectCache.php

diff --git a/includes/libs/objectcache/WANObjectCache.php b/includes/libs/objectcache/WANObjectCache.php
index 8f2c72a..08424c9 100644 (file)
--- a/includes/libs/objectcache/WANObjectCache.php
+++ b/includes/libs/objectcache/WANObjectCache.php
@@ -214,6 +214,9 @@ class WANObjectCache implements IExpiringStore, LoggerAwareInterface {
                $this->asyncHandler = isset( $params['asyncHandler'] ) ? $params['asyncHandler'] : null;
        }
 
+       /**
+        * @param LoggerInterface $logger
+        */
        public function setLogger( LoggerInterface $logger ) {
                $this->logger = $logger;
        }
@@ -225,8 +228,7 @@ class WANObjectCache implements IExpiringStore, LoggerAwareInterface {
         */
        public static function newEmpty() {
                return new static( [
-                       'cache'   => new EmptyBagOStuff(),
-                       'pool'    => 'empty'
+                       'cache'   => new EmptyBagOStuff()
                ] );
        }
 
@@ -417,6 +419,12 @@ class WANObjectCache implements IExpiringStore, LoggerAwareInterface {
         *
         * 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 );
@@ -533,6 +541,10 @@ class WANObjectCache implements IExpiringStore, LoggerAwareInterface {
         *
         * 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.
@@ -901,6 +913,40 @@ class WANObjectCache implements IExpiringStore, LoggerAwareInterface {
         *     );
         * @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-tolerablity-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()
         *
@@ -1205,7 +1251,7 @@ class WANObjectCache implements IExpiringStore, LoggerAwareInterface {
         * @param string $key
         * @param bool $versioned
         * @param float $minTime
-        * @param mixed $asOf
+        * @param mixed &$asOf
         * @return mixed
         */
        protected function getInterimValue( $key, $versioned, $minTime, &$asOf ) {
@@ -1341,8 +1387,8 @@ class WANObjectCache implements IExpiringStore, LoggerAwareInterface {
         * This works the same as getWithSetCallback() except:
         *   - a) The $keys argument expects the result of WANObjectCache::makeMultiKeys()
         *   - b) The $callback argument expects a callback returning a map of (ID => new value)
-        *        for all entity IDs in $regenById and it takes the following arguments:
-        *          - $ids: a list of entity IDs to regenerate
+        *        for all entity IDs in $ids and it takes the following arguments:
+        *          - $ids: a list of entity IDs that require cache regeneration
         *          - &$ttls: a reference to the (entity ID => new TTL) map
         *          - &$setOpts: a reference to options for set() which can be altered
         *   - c) The return value is a map of (cache key => value) in the order of $keyedIds
@@ -1679,7 +1725,7 @@ class WANObjectCache implements IExpiringStore, LoggerAwareInterface {
         *                 $ttl = ( $newList === $oldValue )
         *                     // No change: cache for 150% of the age of $oldValue
         *                     ? $cache->adaptiveTTL( $oldAsOf, $maxTTL, $minTTL, 1.5 )
-        *                     // Changed: cache for %50 of the age of $oldValue
+        *                     // Changed: cache for 50% of the age of $oldValue
         *                     : $cache->adaptiveTTL( $oldAsOf, $maxTTL, $minTTL, .5 );
         *             }
         *