From: Aaron Schulz Date: Mon, 27 Nov 2017 02:09:34 +0000 (-0800) Subject: objectcache: add more comments to WANObjectCache X-Git-Tag: 1.31.0-rc.0~1379 X-Git-Url: https://git.heureux-cyclage.org/?p=lhc%2Fweb%2Fwiklou.git;a=commitdiff_plain;h=2ad99704345ec0e6609743bbf02e8b474fac432a objectcache: add more comments to WANObjectCache Change-Id: I567f45fa7b33226b0ccf7d80440802eab71ff753 --- diff --git a/includes/libs/objectcache/WANObjectCache.php b/includes/libs/objectcache/WANObjectCache.php index fc3a727d31..830200acaa 100644 --- a/includes/libs/objectcache/WANObjectCache.php +++ b/includes/libs/objectcache/WANObjectCache.php @@ -618,14 +618,13 @@ class WANObjectCache implements IExpiringStore, LoggerAwareInterface { * 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. The timestamp of "check" 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 DB replica DB). + * be invalidated. This approach is useful if many keys depend on a single entity. * - * This method is typically useful for keys with hardcoded names or in some cases - * dynamically generated names, provided the number of such keys is modest. It sets a - * high TTL on the "check" key, making it possible to know the timestamp of the last - * change to the corresponding entities in most cases. + * 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 @@ -815,12 +814,14 @@ class WANObjectCache implements IExpiringStore, LoggerAwareInterface { * * @param string $key Cache key made from makeKey() or makeGlobalKey() * @param int $ttl Seconds to live for key updates. Special values are: - * - WANObjectCache::TTL_INDEFINITE: Cache forever - * - WANObjectCache::TTL_UNCACHEABLE: Do not cache at all + * - 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 invalid when either - * touchCheckKey() or resetCheckKey() is called on any of these keys. + * 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: Consider reusing expired values instead of refreshing them if they expired * less than this many seconds ago. The odds of a refresh becomes more likely over time, @@ -865,13 +866,15 @@ class WANObjectCache implements IExpiringStore, LoggerAwareInterface { * - 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. - * 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. + * 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.