includes/libs/objectcache/BagOStuff.php

   1 <?php
   2 /**
   3  * Copyright © 2003-2004 Brion Vibber <brion@pobox.com>
   4  * https://www.mediawiki.org/
   5  *
   6  * This program is free software; you can redistribute it and/or modify
   7  * it under the terms of the GNU General Public License as published by
   8  * the Free Software Foundation; either version 2 of the License, or
   9  * (at your option) any later version.
  10  *
  11  * This program is distributed in the hope that it will be useful,
  12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  14  * GNU General Public License for more details.
  15  *
  16  * You should have received a copy of the GNU General Public License along
  17  * with this program; if not, write to the Free Software Foundation, Inc.,
  18  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  19  * http://www.gnu.org/copyleft/gpl.html
  20  *
  21  * @file
  22  * @ingroup Cache
  23  */
  24
  25 /**
  26  * @defgroup Cache Cache
  27  */
  28
  29 use Psr\Log\LoggerAwareInterface;
  30 use Psr\Log\LoggerInterface;
  31 use Psr\Log\NullLogger;
  32 use Wikimedia\ScopedCallback;
  33
  34 /**
  35  * Class representing a cache/ephemeral data store
  36  *
  37  * This interface is intended to be more or less compatible with the PHP memcached client.
  38  *
  39  * Instances of this class should be created with an intended access scope, such as:
  40  *   - a) A single PHP thread on a server (e.g. stored in a PHP variable)
  41  *   - b) A single application server (e.g. stored in APC or sqlite)
  42  *   - c) All application servers in datacenter (e.g. stored in memcached or mysql)
  43  *   - d) All application servers in all datacenters (e.g. stored via mcrouter or dynomite)
  44  *
  45  * Callers should use the proper factory methods that yield BagOStuff instances. Site admins
  46  * should make sure the configuration for those factory methods matches their access scope.
  47  * BagOStuff subclasses have widely varying levels of support for replication features.
  48  *
  49  * For any given instance, methods like lock(), unlock(), merge(), and set() with WRITE_SYNC
  50  * should semantically operate over its entire access scope; any nodes/threads in that scope
  51  * should serialize appropriately when using them. Likewise, a call to get() with READ_LATEST
  52  * from one node in its access scope should reflect the prior changes of any other node its
  53  * access scope. Any get() should reflect the changes of any prior set() with WRITE_SYNC.
  54  *
  55  * Subclasses should override the default "segmentationSize" field with an appropriate value.
  56  * The value should not be larger than what the storage backend (by default) supports. It also
  57  * should be roughly informed by common performance bottlenecks (e.g. values over a certain size
  58  * having poor scalability). The same goes for the "segmentedValueMaxSize" member, which limits
  59  * the maximum size and chunk count (indirectly) of values.
  60  *
  61  * @ingroup Cache
  62  */
  63 abstract class BagOStuff implements IExpiringStore, IStoreKeyEncoder, LoggerAwareInterface {
  64         /** @var LoggerInterface */
  65         protected $logger;
  66
  67         /** @var callable|null */
  68         protected $asyncHandler;
  69         /** @var int[] Map of (ATTR_* class constant => QOS_* class constant) */
  70         protected $attrMap = [];
  71
  72         /** @var bool */
  73         protected $debugMode = false;
  74
  75         /** @var float|null */
  76         private $wallClockOverride;
  77
  78         /** Bitfield constants for get()/getMulti(); these are only advisory */
  79         const READ_LATEST = 1; // if supported, avoid reading stale data due to replication
  80         const READ_VERIFIED = 2; // promise that the caller handles detection of staleness
  81         /** Bitfield constants for set()/merge(); these are only advisory */
  82         const WRITE_SYNC = 4; // if supported, block until the write is fully replicated
  83         const WRITE_CACHE_ONLY = 8; // only change state of the in-memory cache
  84         const WRITE_ALLOW_SEGMENTS = 16; // allow partitioning of the value if it is large
  85         const WRITE_PRUNE_SEGMENTS = 32; // delete all the segments if the value is partitioned
  86         const WRITE_BACKGROUND = 64; // if supported, do not block on completion until the next read
  87
  88         /**
  89          * Parameters include:
  90          *   - logger: Psr\Log\LoggerInterface instance
  91          *   - asyncHandler: Callable to use for scheduling tasks after the web request ends.
  92          *      In CLI mode, it should run the task immediately.
  93          * @param array $params
  94          */
  95         public function __construct( array $params = [] ) {
  96                 $this->setLogger( $params['logger'] ?? new NullLogger() );
  97                 $this->asyncHandler = $params['asyncHandler'] ?? null;
  98         }
  99
 100         /**
 101          * @param LoggerInterface $logger
 102          * @return void
 103          */
 104         public function setLogger( LoggerInterface $logger ) {
 105                 $this->logger = $logger;
 106         }
 107
 108         /**
 109          * @param bool $enabled
 110          */
 111         public function setDebug( $enabled ) {
 112                 $this->debugMode = $enabled;
 113         }
 114
 115         /**
 116          * Get an item with the given key, regenerating and setting it if not found
 117          *
 118          * The callback can take $ttl as argument by reference and modify it.
 119          * Nothing is stored nor deleted if the callback returns false.
 120          *
 121          * @param string $key
 122          * @param int $ttl Time-to-live (seconds)
 123          * @param callable $callback Callback that derives the new value
 124          * @param int $flags Bitfield of BagOStuff::READ_* or BagOStuff::WRITE_* constants [optional]
 125          * @return mixed The cached value if found or the result of $callback otherwise
 126          * @since 1.27
 127          */
 128         final public function getWithSetCallback( $key, $ttl, $callback, $flags = 0 ) {
 129                 $value = $this->get( $key, $flags );
 130
 131                 if ( $value === false ) {
 132                         $value = $callback( $ttl );
 133                         if ( $value !== false ) {
 134                                 $this->set( $key, $value, $ttl, $flags );
 135                         }
 136                 }
 137
 138                 return $value;
 139         }
 140
 141         /**
 142          * Get an item with the given key
 143          *
 144          * If the key includes a deterministic input hash (e.g. the key can only have
 145          * the correct value) or complete staleness checks are handled by the caller
 146          * (e.g. nothing relies on the TTL), then the READ_VERIFIED flag should be set.
 147          * This lets tiered backends know they can safely upgrade a cached value to
 148          * higher tiers using standard TTLs.
 149          *
 150          * @param string $key
 151          * @param int $flags Bitfield of BagOStuff::READ_* constants [optional]
 152          * @return mixed Returns false on failure or if the item does not exist
 153          */
 154         abstract public function get( $key, $flags = 0 );
 155
 156         /**
 157          * Set an item
 158          *
 159          * @param string $key
 160          * @param mixed $value
 161          * @param int $exptime Either an interval in seconds or a unix timestamp for expiry
 162          * @param int $flags Bitfield of BagOStuff::WRITE_* constants
 163          * @return bool Success
 164          */
 165         abstract public function set( $key, $value, $exptime = 0, $flags = 0 );
 166
 167         /**
 168          * Delete an item
 169          *
 170          * For large values written using WRITE_ALLOW_SEGMENTS, this only deletes the main
 171          * segment list key unless WRITE_PRUNE_SEGMENTS is in the flags. While deleting the segment
 172          * list key has the effect of functionally deleting the key, it leaves unused blobs in cache.
 173          *
 174          * @param string $key
 175          * @return bool True if the item was deleted or not found, false on failure
 176          * @param int $flags Bitfield of BagOStuff::WRITE_* constants
 177          */
 178         abstract public function delete( $key, $flags = 0 );
 179
 180         /**
 181          * Insert an item if it does not already exist
 182          *
 183          * @param string $key
 184          * @param mixed $value
 185          * @param int $exptime
 186          * @param int $flags Bitfield of BagOStuff::WRITE_* constants (since 1.33)
 187          * @return bool Success
 188          */
 189         abstract public function add( $key, $value, $exptime = 0, $flags = 0 );
 190
 191         /**
 192          * Merge changes into the existing cache value (possibly creating a new one)
 193          *
 194          * The callback function returns the new value given the current value
 195          * (which will be false if not present), and takes the arguments:
 196          * (this BagOStuff, cache key, current value, TTL).
 197          * The TTL parameter is reference set to $exptime. It can be overriden in the callback.
 198          * Nothing is stored nor deleted if the callback returns false.
 199          *
 200          * @param string $key
 201          * @param callable $callback Callback method to be executed
 202          * @param int $exptime Either an interval in seconds or a unix timestamp for expiry
 203          * @param int $attempts The amount of times to attempt a merge in case of failure
 204          * @param int $flags Bitfield of BagOStuff::WRITE_* constants
 205          * @return bool Success
 206          * @throws InvalidArgumentException
 207          */
 208         abstract public function merge(
 209                 $key,
 210                 callable $callback,
 211                 $exptime = 0,
 212                 $attempts = 10,
 213                 $flags = 0
 214         );
 215
 216         /**
 217          * Change the expiration on a key if it exists
 218          *
 219          * If an expiry in the past is given then the key will immediately be expired
 220          *
 221          * For large values written using WRITE_ALLOW_SEGMENTS, this only changes the TTL of the
 222          * main segment list key. While lowering the TTL of the segment list key has the effect of
 223          * functionally lowering the TTL of the key, it might leave unused blobs in cache for longer.
 224          * Raising the TTL of such keys is not effective, since the expiration of a single segment
 225          * key effectively expires the entire value.
 226          *
 227          * @param string $key
 228          * @param int $exptime TTL or UNIX timestamp
 229          * @param int $flags Bitfield of BagOStuff::WRITE_* constants (since 1.33)
 230          * @return bool Success Returns false on failure or if the item does not exist
 231          * @since 1.28
 232          */
 233         abstract public function changeTTL( $key, $exptime = 0, $flags = 0 );
 234
 235         /**
 236          * Acquire an advisory lock on a key string
 237          *
 238          * Note that if reentry is enabled, duplicate calls ignore $expiry
 239          *
 240          * @param string $key
 241          * @param int $timeout Lock wait timeout; 0 for non-blocking [optional]
 242          * @param int $expiry Lock expiry [optional]; 1 day maximum
 243          * @param string $rclass Allow reentry if set and the current lock used this value
 244          * @return bool Success
 245          */
 246         abstract public function lock( $key, $timeout = 6, $expiry = 6, $rclass = '' );
 247
 248         /**
 249          * Release an advisory lock on a key string
 250          *
 251          * @param string $key
 252          * @return bool Success
 253          */
 254         abstract public function unlock( $key );
 255
 256         /**
 257          * Get a lightweight exclusive self-unlocking lock
 258          *
 259          * Note that the same lock cannot be acquired twice.
 260          *
 261          * This is useful for task de-duplication or to avoid obtrusive
 262          * (though non-corrupting) DB errors like INSERT key conflicts
 263          * or deadlocks when using LOCK IN SHARE MODE.
 264          *
 265          * @param string $key
 266          * @param int $timeout Lock wait timeout; 0 for non-blocking [optional]
 267          * @param int $expiry Lock expiry [optional]; 1 day maximum
 268          * @param string $rclass Allow reentry if set and the current lock used this value
 269          * @return ScopedCallback|null Returns null on failure
 270          * @since 1.26
 271          */
 272         final public function getScopedLock( $key, $timeout = 6, $expiry = 30, $rclass = '' ) {
 273                 $expiry = min( $expiry ?: INF, self::TTL_DAY );
 274
 275                 if ( !$this->lock( $key, $timeout, $expiry, $rclass ) ) {
 276                         return null;
 277                 }
 278
 279                 $lSince = $this->getCurrentTime(); // lock timestamp
 280
 281                 return new ScopedCallback( function () use ( $key, $lSince, $expiry ) {
 282                         $latency = 0.050; // latency skew (err towards keeping lock present)
 283                         $age = ( $this->getCurrentTime() - $lSince + $latency );
 284                         if ( ( $age + $latency ) >= $expiry ) {
 285                                 $this->logger->warning(
 286                                         "Lock for {key} held too long ({age} sec).",
 287                                         [ 'key' => $key, 'age' => $age ]
 288                                 );
 289                                 return; // expired; it's not "safe" to delete the key
 290                         }
 291                         $this->unlock( $key );
 292                 } );
 293         }
 294
 295         /**
 296          * Delete all objects expiring before a certain date.
 297          * @param string|int $timestamp The reference date in MW or TS_UNIX format
 298          * @param callable|null $progress Optional, a function which will be called
 299          *     regularly during long-running operations with the percentage progress
 300          *     as the first parameter. [optional]
 301          * @param int $limit Maximum number of keys to delete [default: INF]
 302          *
 303          * @return bool Success; false if unimplemented
 304          */
 305         abstract public function deleteObjectsExpiringBefore(
 306                 $timestamp,
 307                 callable $progress = null,
 308                 $limit = INF
 309         );
 310
 311         /**
 312          * Get an associative array containing the item for each of the keys that have items.
 313          * @param string[] $keys List of keys
 314          * @param int $flags Bitfield; supports READ_LATEST [optional]
 315          * @return mixed[] Map of (key => value) for existing keys
 316          */
 317         abstract public function getMulti( array $keys, $flags = 0 );
 318
 319         /**
 320          * Batch insertion/replace
 321          *
 322          * This does not support WRITE_ALLOW_SEGMENTS to avoid excessive read I/O
 323          *
 324          * WRITE_BACKGROUND can be used for bulk insertion where the response is not vital
 325          *
 326          * @param mixed[] $data Map of (key => value)
 327          * @param int $exptime Either an interval in seconds or a unix timestamp for expiry
 328          * @param int $flags Bitfield of BagOStuff::WRITE_* constants (since 1.33)
 329          * @return bool Success
 330          * @since 1.24
 331          */
 332         abstract public function setMulti( array $data, $exptime = 0, $flags = 0 );
 333
 334         /**
 335          * Batch deletion
 336          *
 337          * This does not support WRITE_ALLOW_SEGMENTS to avoid excessive read I/O
 338          *
 339          * WRITE_BACKGROUND can be used for bulk deletion where the response is not vital
 340          *
 341          * @param string[] $keys List of keys
 342          * @param int $flags Bitfield of BagOStuff::WRITE_* constants
 343          * @return bool Success
 344          * @since 1.33
 345          */
 346         abstract public function deleteMulti( array $keys, $flags = 0 );
 347
 348         /**
 349          * Change the expiration of multiple keys that exist
 350          *
 351          * @see BagOStuff::changeTTL()
 352          *
 353          * @param string[] $keys List of keys
 354          * @param int $exptime TTL or UNIX timestamp
 355          * @param int $flags Bitfield of BagOStuff::WRITE_* constants (since 1.33)
 356          * @return bool Success
 357          * @since 1.34
 358          */
 359         abstract public function changeTTLMulti( array $keys, $exptime, $flags = 0 );
 360
 361         /**
 362          * Increase stored value of $key by $value while preserving its TTL
 363          * @param string $key Key to increase
 364          * @param int $value Value to add to $key (default: 1) [optional]
 365          * @return int|bool New value or false on failure
 366          */
 367         abstract public function incr( $key, $value = 1 );
 368
 369         /**
 370          * Decrease stored value of $key by $value while preserving its TTL
 371          * @param string $key
 372          * @param int $value Value to subtract from $key (default: 1) [optional]
 373          * @return int|bool New value or false on failure
 374          */
 375         abstract public function decr( $key, $value = 1 );
 376
 377         /**
 378          * Increase stored value of $key by $value while preserving its TTL
 379          *
 380          * This will create the key with value $init and TTL $ttl instead if not present
 381          *
 382          * @param string $key
 383          * @param int $ttl
 384          * @param int $value
 385          * @param int $init
 386          * @return int|bool New value or false on failure
 387          * @since 1.24
 388          */
 389         abstract public function incrWithInit( $key, $ttl, $value = 1, $init = 1 );
 390
 391         /**
 392          * Get the "last error" registered; clearLastError() should be called manually
 393          * @return int ERR_* constant for the "last error" registry
 394          * @since 1.23
 395          */
 396         abstract public function getLastError();
 397
 398         /**
 399          * Clear the "last error" registry
 400          * @since 1.23
 401          */
 402         abstract public function clearLastError();
 403
 404         /**
 405          * Let a callback be run to avoid wasting time on special blocking calls
 406          *
 407          * The callbacks may or may not be called ever, in any particular order.
 408          * They are likely to be invoked when something WRITE_SYNC is used used.
 409          * They should follow a caching pattern as shown below, so that any code
 410          * using the work will get it's result no matter what happens.
 411          * @code
 412          *     $result = null;
 413          *     $workCallback = function () use ( &$result ) {
 414          *         if ( !$result ) {
 415          *             $result = ....
 416          *         }
 417          *         return $result;
 418          *     }
 419          * @endcode
 420          *
 421          * @param callable $workCallback
 422          * @since 1.28
 423          */
 424         abstract public function addBusyCallback( callable $workCallback );
 425
 426         /**
 427          * Construct a cache key.
 428          *
 429          * @since 1.27
 430          * @param string $keyspace
 431          * @param array $args
 432          * @return string Colon-delimited list of $keyspace followed by escaped components of $args
 433          */
 434         abstract public function makeKeyInternal( $keyspace, $args );
 435
 436         /**
 437          * Make a global cache key.
 438          *
 439          * @since 1.27
 440          * @param string $class Key class
 441          * @param string ...$components Key components (starting with a key collection name)
 442          * @return string Colon-delimited list of $keyspace followed by escaped components
 443          */
 444         abstract public function makeGlobalKey( $class, ...$components );
 445
 446         /**
 447          * Make a cache key, scoped to this instance's keyspace.
 448          *
 449          * @since 1.27
 450          * @param string $class Key class
 451          * @param string ...$components Key components (starting with a key collection name)
 452          * @return string Colon-delimited list of $keyspace followed by escaped components
 453          */
 454         abstract public function makeKey( $class, ...$components );
 455
 456         /**
 457          * @param int $flag ATTR_* class constant
 458          * @return int QOS_* class constant
 459          * @since 1.28
 460          */
 461         public function getQoS( $flag ) {
 462                 return $this->attrMap[$flag] ?? self::QOS_UNKNOWN;
 463         }
 464
 465         /**
 466          * @return int|float The chunk size, in bytes, of segmented objects (INF for no limit)
 467          * @since 1.34
 468          */
 469         public function getSegmentationSize() {
 470                 return INF;
 471         }
 472
 473         /**
 474          * @return int|float Maximum total segmented object size in bytes (INF for no limit)
 475          * @since 1.34
 476          */
 477         public function getSegmentedValueMaxSize() {
 478                 return INF;
 479         }
 480
 481         /**
 482          * Merge the flag maps of one or more BagOStuff objects into a "lowest common denominator" map
 483          *
 484          * @param BagOStuff[] $bags
 485          * @return int[] Resulting flag map (class ATTR_* constant => class QOS_* constant)
 486          */
 487         final protected function mergeFlagMaps( array $bags ) {
 488                 $map = [];
 489                 foreach ( $bags as $bag ) {
 490                         foreach ( $bag->attrMap as $attr => $rank ) {
 491                                 if ( isset( $map[$attr] ) ) {
 492                                         $map[$attr] = min( $map[$attr], $rank );
 493                                 } else {
 494                                         $map[$attr] = $rank;
 495                                 }
 496                         }
 497                 }
 498
 499                 return $map;
 500         }
 501
 502         /**
 503          * @internal For testing only
 504          * @return float UNIX timestamp
 505          * @codeCoverageIgnore
 506          */
 507         public function getCurrentTime() {
 508                 return $this->wallClockOverride ?: microtime( true );
 509         }
 510
 511         /**
 512          * @internal For testing only
 513          * @param float|null &$time Mock UNIX timestamp
 514          * @codeCoverageIgnore
 515          */
 516         public function setMockTime( &$time ) {
 517                 $this->wallClockOverride =& $time;
 518         }
 519 }