objectcache: Improve overall BagOStuff class docs
Fix file doc blocks while at it. > Remove duplicate description from file block in favour of class doc. > This reduces needless duplication and is often incorrect or outdated, > and helps make file headers more consistently (visually) ignorable. > > Add missing `ingroup` to class doc (and remove any from file doc) > as otherwise the file is indexed twice (e.g. in Doxygen) which makes > navigation on doc.wikimedia.org rather messy. > > Ref https://gerrit.wikimedia.org/r/q/message:ingroup+is:merged+owner:Krinkle+branch:master Bug: T364652 Change-Id: Icc36566da1c7190b0f4269719f34d3d6a83026c1
This commit is contained in:
Timo Tijhof
Derick Alangi
parent
d38689ae1d
commit
8268b5e72c
17 changed files with 130 additions and 82 deletions
|
|
@ -3192,7 +3192,7 @@ $wgAutoloadLocalClasses = [
|
|||
'VersionChecker' => __DIR__ . '/includes/registration/VersionChecker.php',
|
||||
'ViewAction' => __DIR__ . '/includes/actions/ViewAction.php',
|
||||
'ViewCLI' => __DIR__ . '/maintenance/view.php',
|
||||
'WANObjectCache' => __DIR__ . '/includes/libs/objectcache/wancache/WANObjectCache.php',
|
||||
'WANObjectCache' => __DIR__ . '/includes/libs/objectcache/WANObjectCache.php',
|
||||
'WantedFilesPage' => __DIR__ . '/includes/specials/SpecialWantedFiles.php',
|
||||
'WantedPagesPage' => __DIR__ . '/includes/specials/SpecialWantedPages.php',
|
||||
'WantedQueryPage' => __DIR__ . '/includes/specialpage/WantedQueryPage.php',
|
||||
|
|
|
|||
|
|
@ -1,7 +1,5 @@
|
|||
<?php
|
||||
/**
|
||||
* Object caching using PHP's APCU accelerator.
|
||||
*
|
||||
* This program is free software; you can redistribute it and/or modify
|
||||
* it under the terms of the GNU General Public License as published by
|
||||
* the Free Software Foundation; either version 2 of the License, or
|
||||
|
|
@ -18,21 +16,21 @@
|
|||
* http://www.gnu.org/copyleft/gpl.html
|
||||
*
|
||||
* @file
|
||||
* @ingroup Cache
|
||||
*/
|
||||
|
||||
namespace Wikimedia\ObjectCache;
|
||||
|
||||
/**
|
||||
* This is a wrapper for APCu's shared memory functions
|
||||
* Store data in the local server memory via APCu (php-apcu)
|
||||
*
|
||||
* Use PHP serialization to avoid bugs and easily create CAS tokens.
|
||||
* APCu has a memory corruption bug when the serializer is set to 'default'.
|
||||
* See T120267, and upstream bug reports:
|
||||
* - https://github.com/krakjoe/apcu/issues/38
|
||||
* - https://github.com/krakjoe/apcu/issues/35
|
||||
* - https://github.com/krakjoe/apcu/issues/111
|
||||
* Past issues of note:
|
||||
* - Memory corruption when `apc.serializer=default` in INI:
|
||||
* https://phabricator.wikimedia.org/T120267
|
||||
* - We used to recommend `apc.serializer=php` as non-default setting, and if not set,
|
||||
* applied serialize() manually to workaround bugs and to create values we can use
|
||||
* as CAS tokens. Upstream defaults to serializer=php since php-apcu 5.1.15 (2018).
|
||||
* https://gerrit.wikimedia.org/r/671634
|
||||
*
|
||||
* @see https://www.php.net/apcu
|
||||
* @ingroup Cache
|
||||
*/
|
||||
class APCUBagOStuff extends MediumSpecificBagOStuff {
|
||||
|
|
|
|||
|
|
@ -1,8 +1,5 @@
|
|||
<?php
|
||||
/**
|
||||
* Copyright © 2003-2004 Brooke Vibber <bvibber@wikimedia.org>
|
||||
* https://www.mediawiki.org/
|
||||
*
|
||||
* This program is free software; you can redistribute it and/or modify
|
||||
* it under the terms of the GNU General Public License as published by
|
||||
* the Free Software Foundation; either version 2 of the License, or
|
||||
|
|
@ -19,11 +16,16 @@
|
|||
* http://www.gnu.org/copyleft/gpl.html
|
||||
*
|
||||
* @file
|
||||
* @ingroup Cache
|
||||
*/
|
||||
|
||||
/**
|
||||
* @defgroup Cache Cache
|
||||
* @defgroup Cache BagOStuff
|
||||
*
|
||||
* Most important classes are:
|
||||
*
|
||||
* @see ObjectCacheFactory
|
||||
* @see WANObjectCache
|
||||
* @see BagOStuff
|
||||
*/
|
||||
|
||||
namespace Wikimedia\ObjectCache;
|
||||
|
|
@ -38,13 +40,11 @@ use Wikimedia\ScopedCallback;
|
|||
use Wikimedia\Stats\StatsFactory;
|
||||
|
||||
/**
|
||||
* Class representing a cache/ephemeral data store
|
||||
*
|
||||
* This interface is intended to be more or less compatible with the PHP memcached client.
|
||||
* Abstract class for any ephemeral data store
|
||||
*
|
||||
* Class instances should be created with an intended access scope for the dataset, such as:
|
||||
* - a) A single PHP thread on a server (e.g. stored in a PHP variable)
|
||||
* - b) A single application server (e.g. stored in APC or sqlite)
|
||||
* - b) A single application server (e.g. stored in php-apcu or sqlite)
|
||||
* - c) All application servers in datacenter (e.g. stored in memcached or mysql)
|
||||
* - d) All application servers in all datacenters (e.g. stored via mcrouter or dynomite)
|
||||
*
|
||||
|
|
@ -79,6 +79,7 @@ use Wikimedia\Stats\StatsFactory;
|
|||
* @stable to extend
|
||||
* @newable
|
||||
* @ingroup Cache
|
||||
* @copyright 2003-2004 Brooke Vibber <bvibber@wikimedia.org>
|
||||
*/
|
||||
abstract class BagOStuff implements
|
||||
ExpirationAwareness,
|
||||
|
|
|
|||
|
|
@ -1,7 +1,5 @@
|
|||
<?php
|
||||
/**
|
||||
* Wrapper around a BagOStuff that caches data in memory
|
||||
*
|
||||
* This program is free software; you can redistribute it and/or modify
|
||||
* it under the terms of the GNU General Public License as published by
|
||||
* the Free Software Foundation; either version 2 of the License, or
|
||||
|
|
@ -18,19 +16,17 @@
|
|||
* http://www.gnu.org/copyleft/gpl.html
|
||||
*
|
||||
* @file
|
||||
* @ingroup Cache
|
||||
*/
|
||||
|
||||
namespace Wikimedia\ObjectCache;
|
||||
|
||||
/**
|
||||
* Wrapper around a BagOStuff that caches data in memory
|
||||
* Wrap any BagOStuff and add an in-process memory cache to it.
|
||||
*
|
||||
* The differences between CachedBagOStuff and MultiWriteBagOStuff are:
|
||||
* * CachedBagOStuff supports only one "backend".
|
||||
* * There's a flag for writes to only go to the in-memory cache.
|
||||
* * The in-memory cache is always updated.
|
||||
* * Locks go to the backend cache (with MultiWriteBagOStuff, it would wind
|
||||
* - CachedBagOStuff supports only one "backend".
|
||||
* - There's a flag for writes to only go to the in-memory cache.
|
||||
* - The in-memory cache is always updated.
|
||||
* - Locks go to the backend cache (with MultiWriteBagOStuff, it would wind
|
||||
* up going to the HashBagOStuff used for the in-memory cache).
|
||||
*
|
||||
* @newable
|
||||
|
|
|
|||
|
|
@ -1,7 +1,5 @@
|
|||
<?php
|
||||
/**
|
||||
* Dummy object caching.
|
||||
*
|
||||
* This program is free software; you can redistribute it and/or modify
|
||||
* it under the terms of the GNU General Public License as published by
|
||||
* the Free Software Foundation; either version 2 of the License, or
|
||||
|
|
@ -18,13 +16,15 @@
|
|||
* http://www.gnu.org/copyleft/gpl.html
|
||||
*
|
||||
* @file
|
||||
* @ingroup Cache
|
||||
*/
|
||||
|
||||
namespace Wikimedia\ObjectCache;
|
||||
|
||||
/**
|
||||
* A BagOStuff object with no objects in it. Used to provide a no-op object to calling code.
|
||||
* No-op implementation that stores nothing.
|
||||
*
|
||||
* Used as placeholder or fallback when disabling caching.
|
||||
*
|
||||
* This can be used in configuration via the CACHE_NONE constant.
|
||||
*
|
||||
* @ingroup Cache
|
||||
*/
|
||||
|
|
|
|||
|
|
@ -1,7 +1,5 @@
|
|||
<?php
|
||||
/**
|
||||
* Per-process memory cache for storing items.
|
||||
*
|
||||
* This program is free software; you can redistribute it and/or modify
|
||||
* it under the terms of the GNU General Public License as published by
|
||||
* the Free Software Foundation; either version 2 of the License, or
|
||||
|
|
@ -18,7 +16,6 @@
|
|||
* http://www.gnu.org/copyleft/gpl.html
|
||||
*
|
||||
* @file
|
||||
* @ingroup Cache
|
||||
*/
|
||||
|
||||
namespace Wikimedia\ObjectCache;
|
||||
|
|
@ -26,9 +23,11 @@ namespace Wikimedia\ObjectCache;
|
|||
use InvalidArgumentException;
|
||||
|
||||
/**
|
||||
* Simple store for keeping values in an associative array for the current process.
|
||||
* Store data in a memory for the current request/process only.
|
||||
*
|
||||
* Data will not persist and is not shared with other processes.
|
||||
* This keeps values in a simple associative array.
|
||||
* Data will not persist and is not shared with other requests
|
||||
* on the same server.
|
||||
*
|
||||
* @newable
|
||||
* @ingroup Cache
|
||||
|
|
|
|||
|
|
@ -1,7 +1,5 @@
|
|||
<?php
|
||||
/**
|
||||
* Storage medium specific cache for storing items.
|
||||
*
|
||||
* This program is free software; you can redistribute it and/or modify
|
||||
* it under the terms of the GNU General Public License as published by
|
||||
* the Free Software Foundation; either version 2 of the License, or
|
||||
|
|
@ -18,9 +16,7 @@
|
|||
* http://www.gnu.org/copyleft/gpl.html
|
||||
*
|
||||
* @file
|
||||
* @ingroup Cache
|
||||
*/
|
||||
|
||||
namespace Wikimedia\ObjectCache;
|
||||
|
||||
use InvalidArgumentException;
|
||||
|
|
@ -30,9 +26,10 @@ use stdClass;
|
|||
use Wikimedia\WaitConditionLoop;
|
||||
|
||||
/**
|
||||
* Storage medium specific cache for storing items (e.g. redis, memcached, ...)
|
||||
* Helper classs that implements most of BagOStuff for a backend.
|
||||
*
|
||||
* This should not be used for proxy classes that simply wrap other cache instances
|
||||
* This should be used by concrete implementations only. Wrapper classes that
|
||||
* proxy another BagOStuff should extend and implement BagOStuff directly.
|
||||
*
|
||||
* @ingroup Cache
|
||||
* @since 1.34
|
||||
|
|
|
|||
|
|
@ -1,7 +1,5 @@
|
|||
<?php
|
||||
/**
|
||||
* Base class for memcached clients.
|
||||
*
|
||||
* This program is free software; you can redistribute it and/or modify
|
||||
* it under the terms of the GNU General Public License as published by
|
||||
* the Free Software Foundation; either version 2 of the License, or
|
||||
|
|
@ -18,9 +16,7 @@
|
|||
* http://www.gnu.org/copyleft/gpl.html
|
||||
*
|
||||
* @file
|
||||
* @ingroup Cache
|
||||
*/
|
||||
|
||||
namespace Wikimedia\ObjectCache;
|
||||
|
||||
use Exception;
|
||||
|
|
@ -28,7 +24,9 @@ use InvalidArgumentException;
|
|||
use RuntimeException;
|
||||
|
||||
/**
|
||||
* Base class for memcached clients.
|
||||
* Store data in a memcached server or memcached cluster.
|
||||
*
|
||||
* This is a base class for MemcachedPhpBagOStuff and MemcachedPeclBagOStuff.
|
||||
*
|
||||
* @ingroup Cache
|
||||
*/
|
||||
|
|
|
|||
|
|
@ -1,7 +1,5 @@
|
|||
<?php
|
||||
/**
|
||||
* Object caching using memcached.
|
||||
*
|
||||
* This program is free software; you can redistribute it and/or modify
|
||||
* it under the terms of the GNU General Public License as published by
|
||||
* the Free Software Foundation; either version 2 of the License, or
|
||||
|
|
@ -18,9 +16,7 @@
|
|||
* http://www.gnu.org/copyleft/gpl.html
|
||||
*
|
||||
* @file
|
||||
* @ingroup Cache
|
||||
*/
|
||||
|
||||
namespace Wikimedia\ObjectCache;
|
||||
|
||||
use Memcached;
|
||||
|
|
@ -29,7 +25,10 @@ use UnexpectedValueException;
|
|||
use Wikimedia\ScopedCallback;
|
||||
|
||||
/**
|
||||
* A wrapper class for the PECL memcached client
|
||||
* Store data on memcached server(s) via the php-memcached PECL extension.
|
||||
*
|
||||
* To use memcached out of the box without any PECL dependency, use the
|
||||
* MemcachedPhpBagOStuff class instead.
|
||||
*
|
||||
* @ingroup Cache
|
||||
*/
|
||||
|
|
|
|||
|
|
@ -1,7 +1,5 @@
|
|||
<?php
|
||||
/**
|
||||
* Object caching using memcached.
|
||||
*
|
||||
* This program is free software; you can redistribute it and/or modify
|
||||
* it under the terms of the GNU General Public License as published by
|
||||
* the Free Software Foundation; either version 2 of the License, or
|
||||
|
|
@ -18,15 +16,18 @@
|
|||
* http://www.gnu.org/copyleft/gpl.html
|
||||
*
|
||||
* @file
|
||||
* @ingroup Cache
|
||||
*/
|
||||
|
||||
namespace Wikimedia\ObjectCache;
|
||||
|
||||
use MemcachedClient;
|
||||
|
||||
/**
|
||||
* A wrapper class for the pure-PHP memcached client, exposing a BagOStuff interface.
|
||||
* Store data on memcached servers(s) via a pure-PHP memcached client.
|
||||
*
|
||||
* In configuration, the CACHE_MEMCACHED will activate the MemcachedPhpBagOStuff
|
||||
* class. This works out of the box without any PHP extension or other PECL
|
||||
* dependencies. If you can install the php-memcached PECL extension,
|
||||
* it is recommended to use MemcachedPeclBagOStuff instead.
|
||||
*
|
||||
* @ingroup Cache
|
||||
*/
|
||||
|
|
|
|||
|
|
@ -1,7 +1,5 @@
|
|||
<?php
|
||||
/**
|
||||
* Wrapper for object caching in different caches.
|
||||
*
|
||||
* This program is free software; you can redistribute it and/or modify
|
||||
* it under the terms of the GNU General Public License as published by
|
||||
* the Free Software Foundation; either version 2 of the License, or
|
||||
|
|
@ -18,21 +16,86 @@
|
|||
* http://www.gnu.org/copyleft/gpl.html
|
||||
*
|
||||
* @file
|
||||
* @ingroup Cache
|
||||
*/
|
||||
|
||||
namespace Wikimedia\ObjectCache;
|
||||
|
||||
use InvalidArgumentException;
|
||||
use Wikimedia\ObjectFactory\ObjectFactory;
|
||||
|
||||
/**
|
||||
* A cache class that replicates all writes to multiple child caches. Reads
|
||||
* are implemented by reading from the caches in the order they are given in
|
||||
* the configuration until a cache gives a positive result.
|
||||
* Wrap multiple BagOStuff objects, to implement different caching tiers.
|
||||
*
|
||||
* Note that cache key construction will use the first cache backend in the list,
|
||||
* so make sure that the other backends can handle such keys (e.g. via encoding).
|
||||
* The order of the caches is important. The first tier is considered the primary
|
||||
* and highest tier which must handle the majority of the load for reads,
|
||||
* and is generally less persistent, smaller, and faster (e.g. evicts data
|
||||
* regularly based on demand, keeping fewer keys at a given time).
|
||||
* The other caches are consider secondary and lower tiers, which should
|
||||
* hold more data and retain it for longer than the primary tier.
|
||||
*
|
||||
* Data writes ("set") go to all given BagOStuff caches.
|
||||
* If the `replication => async` option is set, then only the primary write
|
||||
* is blocking during the web request, with other writes deferred until
|
||||
* after the web response is sent.
|
||||
*
|
||||
* Data reads try each cache in the order they are given, until a value is found.
|
||||
* When a value is found at a secondary tier, it is automatically copied (back)
|
||||
* to the primary tier.
|
||||
*
|
||||
* **Example**: Keep popular data in memcached, with a fallback to a MySQL database.
|
||||
* This is how ParserCache is used at Wikimedia Foundation (as of 2024).
|
||||
*
|
||||
* ```
|
||||
* $wgObjectCaches['parsercache-multiwrite'] = [
|
||||
* 'class' => 'MultiWriteBagOStuff',
|
||||
* 'caches' => [
|
||||
* 0 => [
|
||||
* 'class' => 'MemcachedPeclBagOStuff',
|
||||
* 'servers' => [ '127.0.0.1:11212' ],
|
||||
* ],
|
||||
* 1 => [
|
||||
* 'class' => 'SqlBagOStuff',
|
||||
* 'servers' => $parserCacheDbServers,
|
||||
* 'purgePeriod' => 0,
|
||||
* 'tableName' => 'pc',
|
||||
* 'shards' => 256,
|
||||
* 'reportDupes' => false
|
||||
* ],
|
||||
* ]
|
||||
* ];
|
||||
* ```
|
||||
*
|
||||
* If you configure a memcached server for MultiWriteBagOStuff that is the same
|
||||
* as the one used for MediaWiki more generally, it is recommended to specify
|
||||
* the tier via ObjectCache::getInstance() so that the same object and Memcached
|
||||
* connection can be re-used.
|
||||
*
|
||||
* ```
|
||||
* $wgObjectCaches['my-memcached'] = [ .. ];
|
||||
* $wgMainCacheType = 'my-memcached';
|
||||
*
|
||||
* $wgObjectCaches['parsercache-multiwrite'] = [
|
||||
* 'class' => 'MultiWriteBagOStuff',
|
||||
* 'caches' => [
|
||||
* 0 => [
|
||||
* 'factory' => [ 'ObjectCache', 'getInstance' ],
|
||||
* 'args' => [ 'my-memcached' ],
|
||||
* ],
|
||||
* 1 => [
|
||||
* 'class' => 'SqlBagOStuff',
|
||||
* 'servers' => $parserCacheDbServers,
|
||||
* 'purgePeriod' => 0,
|
||||
* 'tableName' => 'pc',
|
||||
* 'shards' => 256,
|
||||
* 'reportDupes' => false
|
||||
* ],
|
||||
* ]
|
||||
* ];
|
||||
* ```
|
||||
*
|
||||
* The makeKey() method of this class uses an implementation-agnostic encoding.
|
||||
* When it forward gets and sets to the other BagOStuff objects, keys are
|
||||
* automatically re-encoded. For example, to satisfy the character and length
|
||||
* constraints of MemcachedBagOStuff.
|
||||
*
|
||||
* @newable
|
||||
* @ingroup Cache
|
||||
|
|
|
|||
|
|
@ -8,7 +8,7 @@ use Psr\Log\LoggerInterface;
|
|||
use Wikimedia\Http\MultiHttpClient;
|
||||
|
||||
/**
|
||||
* Interface to key-value storage behind an HTTP server.
|
||||
* Store key-value data via an HTTP service.
|
||||
*
|
||||
* ### Important caveats
|
||||
*
|
||||
|
|
|
|||
|
|
@ -1,7 +1,5 @@
|
|||
<?php
|
||||
/**
|
||||
* Object caching using Redis (http://redis.io/).
|
||||
*
|
||||
* This program is free software; you can redistribute it and/or modify
|
||||
* it under the terms of the GNU General Public License as published by
|
||||
* the Free Software Foundation; either version 2 of the License, or
|
||||
|
|
@ -19,7 +17,6 @@
|
|||
*
|
||||
* @file
|
||||
*/
|
||||
|
||||
namespace Wikimedia\ObjectCache;
|
||||
|
||||
use ArrayUtils;
|
||||
|
|
@ -30,9 +27,14 @@ use RedisConnRef;
|
|||
use RedisException;
|
||||
|
||||
/**
|
||||
* Redis-based caching module for redis server >= 2.6.12 and phpredis >= 2.2.4
|
||||
* Store data in Redis.
|
||||
*
|
||||
* This requires the php-redis PECL extension (2.2.4 or later) and
|
||||
* a Redis server (2.6.12 or later).
|
||||
*
|
||||
* @see http://redis.io/
|
||||
* @see https://github.com/phpredis/phpredis/blob/d310ed7c8/Changelog.md
|
||||
*
|
||||
* @note Avoid use of Redis::MULTI transactions for twemproxy support
|
||||
*
|
||||
* @ingroup Cache
|
||||
|
|
|
|||
|
|
@ -16,7 +16,6 @@
|
|||
* http://www.gnu.org/copyleft/gpl.html
|
||||
*
|
||||
* @file
|
||||
* @ingroup Cache
|
||||
*/
|
||||
|
||||
use Psr\Log\LoggerAwareInterface;
|
||||
|
|
@ -5,6 +5,7 @@
|
|||
* on serializing classes.
|
||||
*
|
||||
* @since 1.34
|
||||
* @ingroup Cache
|
||||
*/
|
||||
class SerializedValueContainer {
|
||||
private const SCHEMA = '__svc_schema__';
|
||||
|
|
|
|||
|
|
@ -1,7 +1,5 @@
|
|||
<?php
|
||||
/**
|
||||
* Generic interface providing Time-To-Live constants for expirable object storage
|
||||
*
|
||||
* This program is free software; you can redistribute it and/or modify
|
||||
* it under the terms of the GNU General Public License as published by
|
||||
* the Free Software Foundation; either version 2 of the License, or
|
||||
|
|
@ -18,7 +16,6 @@
|
|||
* http://www.gnu.org/copyleft/gpl.html
|
||||
*
|
||||
* @file
|
||||
* @ingroup Cache
|
||||
*/
|
||||
|
||||
namespace Wikimedia\LightweightObjectStore;
|
||||
|
|
|
|||
|
|
@ -1,7 +1,5 @@
|
|||
<?php
|
||||
/**
|
||||
* Generic interface providing error code and quality-of-service constants for object stores
|
||||
*
|
||||
* This program is free software; you can redistribute it and/or modify
|
||||
* it under the terms of the GNU General Public License as published by
|
||||
* the Free Software Foundation; either version 2 of the License, or
|
||||
|
|
@ -18,7 +16,6 @@
|
|||
* http://www.gnu.org/copyleft/gpl.html
|
||||
*
|
||||
* @file
|
||||
* @ingroup Cache
|
||||
*/
|
||||
|
||||
namespace Wikimedia\LightweightObjectStore;
|
||||
|
|
|
|||
Loading…
Reference in a new issue