From 8268b5e72c2c634c9c5ebecd66b2f19adaa624ec Mon Sep 17 00:00:00 2001 From: Timo Tijhof Date: Fri, 30 Aug 2024 05:22:34 +0100 Subject: [PATCH] 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 --- autoload.php | 2 +- includes/libs/objectcache/APCUBagOStuff.php | 20 +++-- includes/libs/objectcache/BagOStuff.php | 19 ++--- includes/libs/objectcache/CachedBagOStuff.php | 14 ++-- includes/libs/objectcache/EmptyBagOStuff.php | 10 +-- includes/libs/objectcache/HashBagOStuff.php | 9 +-- .../objectcache/MediumSpecificBagOStuff.php | 9 +-- .../libs/objectcache/MemcachedBagOStuff.php | 8 +- .../objectcache/MemcachedPeclBagOStuff.php | 9 +-- .../objectcache/MemcachedPhpBagOStuff.php | 11 +-- .../libs/objectcache/MultiWriteBagOStuff.php | 81 ++++++++++++++++--- includes/libs/objectcache/RESTBagOStuff.php | 2 +- includes/libs/objectcache/RedisBagOStuff.php | 10 ++- .../{wancache => }/WANObjectCache.php | 1 - .../serialized/SerializedValueContainer.php | 1 + .../objectcache/utils/ExpirationAwareness.php | 3 - .../objectcache/utils/StorageAwareness.php | 3 - 17 files changed, 130 insertions(+), 82 deletions(-) rename includes/libs/objectcache/{wancache => }/WANObjectCache.php (99%) diff --git a/autoload.php b/autoload.php index 5939c300e3a..db60138867a 100644 --- a/autoload.php +++ b/autoload.php @@ -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', diff --git a/includes/libs/objectcache/APCUBagOStuff.php b/includes/libs/objectcache/APCUBagOStuff.php index 9f88883b374..dbcf03295d3 100644 --- a/includes/libs/objectcache/APCUBagOStuff.php +++ b/includes/libs/objectcache/APCUBagOStuff.php @@ -1,7 +1,5 @@ - * 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 */ abstract class BagOStuff implements ExpirationAwareness, diff --git a/includes/libs/objectcache/CachedBagOStuff.php b/includes/libs/objectcache/CachedBagOStuff.php index 80163e8e283..3e209ac7de8 100644 --- a/includes/libs/objectcache/CachedBagOStuff.php +++ b/includes/libs/objectcache/CachedBagOStuff.php @@ -1,7 +1,5 @@ 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 diff --git a/includes/libs/objectcache/RESTBagOStuff.php b/includes/libs/objectcache/RESTBagOStuff.php index f8efad53622..284f4c79058 100644 --- a/includes/libs/objectcache/RESTBagOStuff.php +++ b/includes/libs/objectcache/RESTBagOStuff.php @@ -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 * diff --git a/includes/libs/objectcache/RedisBagOStuff.php b/includes/libs/objectcache/RedisBagOStuff.php index 77708e972ea..c2cd85bfe1f 100644 --- a/includes/libs/objectcache/RedisBagOStuff.php +++ b/includes/libs/objectcache/RedisBagOStuff.php @@ -1,7 +1,5 @@ = 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 diff --git a/includes/libs/objectcache/wancache/WANObjectCache.php b/includes/libs/objectcache/WANObjectCache.php similarity index 99% rename from includes/libs/objectcache/wancache/WANObjectCache.php rename to includes/libs/objectcache/WANObjectCache.php index ebe8973ecbc..4d3b4998ac2 100644 --- a/includes/libs/objectcache/wancache/WANObjectCache.php +++ b/includes/libs/objectcache/WANObjectCache.php @@ -16,7 +16,6 @@ * http://www.gnu.org/copyleft/gpl.html * * @file - * @ingroup Cache */ use Psr\Log\LoggerAwareInterface; diff --git a/includes/libs/objectcache/serialized/SerializedValueContainer.php b/includes/libs/objectcache/serialized/SerializedValueContainer.php index 1d915105387..2ccf73025db 100644 --- a/includes/libs/objectcache/serialized/SerializedValueContainer.php +++ b/includes/libs/objectcache/serialized/SerializedValueContainer.php @@ -5,6 +5,7 @@ * on serializing classes. * * @since 1.34 + * @ingroup Cache */ class SerializedValueContainer { private const SCHEMA = '__svc_schema__'; diff --git a/includes/libs/objectcache/utils/ExpirationAwareness.php b/includes/libs/objectcache/utils/ExpirationAwareness.php index 9f79c952a5b..b011d9da99f 100644 --- a/includes/libs/objectcache/utils/ExpirationAwareness.php +++ b/includes/libs/objectcache/utils/ExpirationAwareness.php @@ -1,7 +1,5 @@