X-Git-Url: https://git.heureux-cyclage.org/?p=lhc%2Fweb%2Fwiklou.git;a=blobdiff_plain;f=includes%2Flibs%2Fobjectcache%2FWANObjectCache.php;h=0531d7f7095ad117bc91b2bf0775f2318959ffcb;hp=120ae453c041cac5c3543cbe917150b20c13ed1a;hb=f73f2b320d8fe1eb03f78671584d455a2ff9f292;hpb=6b2f13b055c84d7672652f54deee096762c525cb

diff --git a/includes/libs/objectcache/WANObjectCache.php b/includes/libs/objectcache/WANObjectCache.php
index 120ae453c0..0531d7f709 100644
--- a/includes/libs/objectcache/WANObjectCache.php
+++ b/includes/libs/objectcache/WANObjectCache.php
@@ -686,8 +686,11 @@ class WANObjectCache implements IExpiringStore, LoggerAwareInterface {
 	 * having to inspect a "current time left" variable (e.g. $curTTL, $curTTLs), a cache
 	 * regeneration will automatically be triggered using the callback.
 	 *
-	 * The simplest way to avoid stampedes for hot keys is to use
-	 * the 'lockTSE' option in $opts. If cache purges are needed, also:
+	 * 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 )
 	 *
@@ -839,11 +842,13 @@ class WANObjectCache implements IExpiringStore, LoggerAwareInterface {
 	 *      This is useful if the source of a key is suspected of having possibly changed
 	 *      recently, and the caller wants any such changes to be reflected.
 	 *      Default: WANObjectCache::MIN_TIMESTAMP_NONE.
-	 *   - hotTTR: Expected time-till-refresh 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
-	 *      delayed or lost. Seldom used keys are rarely affected by this setting, unless an
-	 *      extremely low "hotTTR" value is passed in.
+	 *   - hotTTR: Expected time-till-refresh (TTR) for keys that average ~1 hit/second (1 Hz).
+	 *      Keys with a hit rate higher than 1Hz will refresh sooner than this TTR and vise versa.
+	 *      Such refreshes won't happen until keys are "ageNew" seconds old. The TTR is useful at
+	 *      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.
@@ -1538,7 +1543,7 @@ class WANObjectCache implements IExpiringStore, LoggerAwareInterface {
 	}
 
 	/**
-	 * Check if a key should be regenerated (using random probability)
+	 * Check if a key is nearing expiration and thus due for randomized regeneration
 	 *
 	 * This returns false if $curTTL >= $lowTTL. Otherwise, the chance
 	 * of returning true increases steadily from 0% to 100% as the $curTTL