Update $wgMainStash comments and merge in those from a deprecated ObjectCache method

Change-Id: I807f36d9c51476a969d7046d57bfc32cf37c2745

diff --git a/includes/DefaultSettings.php b/includes/DefaultSettings.php
index 65b23d5..1fd9f35 100644 (file)
--- a/includes/DefaultSettings.php
+++ b/includes/DefaultSettings.php
@@ -2492,11 +2492,35 @@ $wgWANObjectCaches = [
 $wgEnableWANCacheReaper = false;
 
 /**
- * Main object stash type. This should be a fast storage system for storing
- * lightweight data like hit counters and user activity. Sites with multiple
- * data-centers should have this use a store that replicates all writes. The
- * store should have enough consistency for CAS operations to be usable.
- * Reads outside of those needed for merge() may be eventually consistent.
+ * The object store type of the main stash.
+ *
+ * This store should be a very fast storage system optimized for holding lightweight data
+ * like incrementable hit counters and current user activity. The store should replicate the
+ * dataset among all data-centers. Any add(), merge(), lock(), and unlock() operations should
+ * maintain "best effort" linearizability; as long as connectivity is strong, latency is low,
+ * and there is no eviction pressure prompted by low free space, those operations should be
+ * linearizable. In terms of PACELC (https://en.wikipedia.org/wiki/PACELC_theorem), the store
+ * should act as a PA/EL distributed system for these operations. One optimization for these
+ * operations is to route them to a "primary" data-center (e.g. one that serves HTTP POST) for
+ * synchronous execution and then replicate to the others asynchronously. This means that at
+ * least calls to these operations during HTTP POST requests would quickly return.
+ *
+ * All other operations, such as get(), set(), delete(), changeTTL(), incr(), and decr(),
+ * should be synchronous in the local data-center, replicating asynchronously to the others.
+ * This behavior can be overriden by the use of the WRITE_SYNC and READ_LATEST flags.
+ *
+ * The store should *preferably* have eventual consistency to handle network partitions.
+ *
+ * Modules that rely on the stash should be prepared for:
+ *   - add(), merge(), lock(), and unlock() to be slower than other write operations,
+ *     at least in "secondary" data-centers (e.g. one that only serves HTTP GET/HEAD)
+ *   - Other write operations to have race conditions accross data-centers
+ *   - Read operations to have race conditions accross data-centers
+ *   - Consistency to be either eventual (with Last-Write-Wins) or just "best effort"
+ *
+ * In general, this means avoiding updates during idempotent HTTP requests (GET/HEAD) and
+ * avoiding assumptions of true linearizability (e.g. accepting anomalies). Modules that need
+ * these kind of guarantees should use other storage mediums.
  *
  * The options are:
  *   - db:      Store cache objects in the DB

diff --git a/includes/objectcache/ObjectCache.php b/includes/objectcache/ObjectCache.php
index e9853b1..82b760a 100644 (file)
--- a/includes/objectcache/ObjectCache.php
+++ b/includes/objectcache/ObjectCache.php
@@ -365,18 +365,6 @@ class ObjectCache {
        /**
         * Get the cache object for the main stash.
         *
-        * Stash objects are BagOStuff instances suitable for storing light
-        * weight data that is not canonically stored elsewhere (such as RDBMS).
-        * Stashes should be configured to propagate changes to all data-centers.
-        *
-        * Callers should be prepared for:
-        *   - a) Writes to be slower in non-"primary" (e.g. HTTP GET/HEAD only) DCs
-        *   - b) Reads to be eventually consistent, e.g. for get()/getMulti()
-        * In general, this means avoiding updates on idempotent HTTP requests and
-        * avoiding an assumption of perfect serializability (or accepting anomalies).
-        * Reads may be eventually consistent or data might rollback as nodes flap.
-        * Callers can use BagOStuff:READ_LATEST to see the latest available data.
-        *
         * @return BagOStuff
         * @since 1.26
         * @deprecated Since 1.28 Use MediaWikiServices::getInstance()->getMainObjectStash()