summaryrefslogtreecommitdiff
path: root/includes/objectcache/ObjectCache.php
diff options
context:
space:
mode:
authorPierre Schmitz <pierre@archlinux.de>2015-12-17 09:15:42 +0100
committerPierre Schmitz <pierre@archlinux.de>2015-12-17 09:44:51 +0100
commita1789ddde42033f1b05cc4929491214ee6e79383 (patch)
tree63615735c4ddffaaabf2428946bb26f90899f7bf /includes/objectcache/ObjectCache.php
parent9e06a62f265e3a2aaabecc598d4bc617e06fa32d (diff)
Update to MediaWiki 1.26.0
Diffstat (limited to 'includes/objectcache/ObjectCache.php')
-rw-r--r--includes/objectcache/ObjectCache.php189
1 files changed, 157 insertions, 32 deletions
diff --git a/includes/objectcache/ObjectCache.php b/includes/objectcache/ObjectCache.php
index 2e47e24a..60191057 100644
--- a/includes/objectcache/ObjectCache.php
+++ b/includes/objectcache/ObjectCache.php
@@ -26,44 +26,94 @@ use MediaWiki\Logger\LoggerFactory;
/**
* Functions to get cache objects
*
+ * The word "cache" has two main dictionary meanings, and both
+ * are used in this factory class. They are:
+ *
+ * - a) Cache (the computer science definition).
+ * A place to store copies or computations on existing data for
+ * higher access speeds.
+ * - b) Storage.
+ * A place to store lightweight data that is not canonically
+ * stored anywhere else (e.g. a "hoard" of objects).
+ *
+ * The former should always use strongly consistent stores, so callers don't
+ * have to deal with stale reads. The later may be eventually consistent, but
+ * callers can use BagOStuff:READ_LATEST to see the latest available data.
+ *
+ * Primary entry points:
+ *
+ * - ObjectCache::newAccelerator( $fallbackType )
+ * Purpose: Cache.
+ * Stored only on the individual web server.
+ * Not associated with other servers.
+ *
+ * - wfGetMainCache()
+ * Purpose: Cache.
+ * Stored centrally within the local data-center.
+ * Not replicated to other DCs.
+ * Also known as $wgMemc. Configured by $wgMainCacheType.
+ *
+ * - ObjectCache::getMainWANInstance()
+ * Purpose: Cache.
+ * Stored in the local data-center's main cache (uses different cache keys).
+ * Delete events are broadcasted to other DCs. See WANObjectCache for details.
+ *
+ * - ObjectCache::getMainStashInstance()
+ * Purpose: Ephemeral storage.
+ * Stored centrally within the local data-center.
+ * Changes are replicated to other DCs (eventually consistent).
+ * To retrieve the latest value (e.g. not from a slave), use BagOStuff:READ_LATEST.
+ * This store may be subject to LRU style evictions.
+ *
+ * - wfGetCache( $cacheType )
+ * Get a specific cache type by key in $wgObjectCaches.
+ *
* @ingroup Cache
*/
class ObjectCache {
+ /** @var Array Map of (id => BagOStuff) */
public static $instances = array();
+ /** @var Array Map of (id => WANObjectCache) */
+ public static $wanInstances = array();
+
/**
* Get a cached instance of the specified type of cache object.
*
- * @param string $id
- *
+ * @param string $id A key in $wgObjectCaches.
* @return BagOStuff
*/
- static function getInstance( $id ) {
- if ( isset( self::$instances[$id] ) ) {
- return self::$instances[$id];
+ public static function getInstance( $id ) {
+ if ( !isset( self::$instances[$id] ) ) {
+ self::$instances[$id] = self::newFromId( $id );
}
- $object = self::newFromId( $id );
- self::$instances[$id] = $object;
- return $object;
+ return self::$instances[$id];
}
/**
- * Clear all the cached instances.
+ * Get a cached instance of the specified type of WAN cache object.
+ *
+ * @since 1.26
+ * @param string $id A key in $wgWANObjectCaches.
+ * @return WANObjectCache
*/
- static function clear() {
- self::$instances = array();
+ public static function getWANInstance( $id ) {
+ if ( !isset( self::$wanInstances[$id] ) ) {
+ self::$wanInstances[$id] = self::newWANCacheFromId( $id );
+ }
+
+ return self::$wanInstances[$id];
}
/**
* Create a new cache object of the specified type.
*
- * @param string $id
- *
- * @throws MWException
+ * @param string $id A key in $wgObjectCaches.
* @return BagOStuff
+ * @throws MWException
*/
- static function newFromId( $id ) {
+ public static function newFromId( $id ) {
global $wgObjectCaches;
if ( !isset( $wgObjectCaches[$id] ) ) {
@@ -75,14 +125,17 @@ class ObjectCache {
}
/**
- * Create a new cache object from parameters
- *
- * @param array $params
+ * Create a new cache object from parameters.
*
- * @throws MWException
+ * @param array $params Must have 'factory' or 'class' property.
+ * - factory: Callback passed $params that returns BagOStuff.
+ * - class: BagOStuff subclass constructed with $params.
+ * - loggroup: Alias to set 'logger' key with LoggerFactory group.
+ * - .. Other parameters passed to factory or class.
* @return BagOStuff
+ * @throws MWException
*/
- static function newFromParams( $params ) {
+ public static function newFromParams( $params ) {
if ( isset( $params['loggroup'] ) ) {
$params['logger'] = LoggerFactory::getInstance( $params['loggroup'] );
} else {
@@ -103,7 +156,7 @@ class ObjectCache {
}
/**
- * Factory function referenced from DefaultSettings.php for CACHE_ANYTHING
+ * Factory function for CACHE_ANYTHING (referenced from DefaultSettings.php)
*
* CACHE_ANYTHING means that stuff has to be cached, not caching is not an option.
* If a caching method is configured for any of the main caches ($wgMainCacheType,
@@ -111,10 +164,11 @@ class ObjectCache {
* be an alias to the configured cache choice for that.
* If no cache choice is configured (by default $wgMainCacheType is CACHE_NONE),
* then CACHE_ANYTHING will forward to CACHE_DB.
+ *
* @param array $params
* @return BagOStuff
*/
- static function newAnything( $params ) {
+ public static function newAnything( $params ) {
global $wgMainCacheType, $wgMessageCacheType, $wgParserCacheType;
$candidates = array( $wgMainCacheType, $wgMessageCacheType, $wgParserCacheType );
foreach ( $candidates as $candidate ) {
@@ -126,17 +180,20 @@ class ObjectCache {
}
/**
- * Factory function referenced from DefaultSettings.php for CACHE_ACCEL.
+ * Factory function for CACHE_ACCEL (referenced from DefaultSettings.php)
*
* This will look for any APC style server-local cache.
* A fallback cache can be specified if none is found.
*
- * @param array $params
+ * @param array $params [optional]
* @param int|string $fallback Fallback cache, e.g. (CACHE_NONE, "hash") (since 1.24)
- * @throws MWException
* @return BagOStuff
+ * @throws MWException
*/
- static function newAccelerator( $params, $fallback = null ) {
+ public static function newAccelerator( $params = array(), $fallback = null ) {
+ if ( !is_array( $params ) && $fallback === null ) {
+ $fallback = $params;
+ }
if ( function_exists( 'apc_fetch' ) ) {
$id = 'apc';
} elseif ( function_exists( 'xcache_get' ) && wfIniGetBool( 'xcache.var_size' ) ) {
@@ -144,11 +201,11 @@ class ObjectCache {
} elseif ( function_exists( 'wincache_ucache_get' ) ) {
$id = 'wincache';
} else {
- if ( $fallback !== null ) {
- return self::newFromId( $fallback );
+ if ( $fallback === null ) {
+ throw new MWException( 'CACHE_ACCEL requested but no suitable object ' .
+ 'cache is present. You may want to install APC.' );
}
- throw new MWException( "CACHE_ACCEL requested but no suitable object " .
- "cache is present. You may want to install APC." );
+ $id = $fallback;
}
return self::newFromId( $id );
}
@@ -161,10 +218,78 @@ class ObjectCache {
* switching between the two clients randomly would be disastrous.
*
* @param array $params
- *
* @return MemcachedPhpBagOStuff
*/
- static function newMemcached( $params ) {
+ public static function newMemcached( $params ) {
return new MemcachedPhpBagOStuff( $params );
}
+
+ /**
+ * Create a new cache object of the specified type.
+ *
+ * @since 1.26
+ * @param string $id A key in $wgWANObjectCaches.
+ * @return WANObjectCache
+ * @throws MWException
+ */
+ public static function newWANCacheFromId( $id ) {
+ global $wgWANObjectCaches;
+
+ if ( !isset( $wgWANObjectCaches[$id] ) ) {
+ throw new MWException( "Invalid object cache type \"$id\" requested. " .
+ "It is not present in \$wgWANObjectCaches." );
+ }
+
+ $params = $wgWANObjectCaches[$id];
+ $class = $params['relayerConfig']['class'];
+ $params['relayer'] = new $class( $params['relayerConfig'] );
+ $params['cache'] = self::newFromId( $params['cacheId'] );
+ $class = $params['class'];
+
+ return new $class( $params );
+ }
+
+ /**
+ * Get the main WAN cache object.
+ *
+ * @since 1.26
+ * @return WANObjectCache
+ */
+ public static function getMainWANInstance() {
+ global $wgMainWANCache;
+
+ return self::getWANInstance( $wgMainWANCache );
+ }
+
+ /**
+ * 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
+ */
+ public static function getMainStashInstance() {
+ global $wgMainStash;
+
+ return self::getInstance( $wgMainStash );
+ }
+
+ /**
+ * Clear all the cached instances.
+ */
+ public static function clear() {
+ self::$instances = array();
+ self::$wanInstances = array();
+ }
}