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          * Nothing is stored nor deleted if the callback returns false
 119          *
 120          * @param string $key
 121          * @param int $ttl Time-to-live (seconds)
 122          * @param callable $callback Callback that derives the new value
 123          * @param int $flags Bitfield of BagOStuff::READ_* or BagOStuff::WRITE_* constants [optional]
 124          * @return mixed The cached value if found or the result of $callback otherwise
 125          * @since 1.27
 126          */
 127         final public function getWithSetCallback( $key, $ttl, $callback, $flags = 0 ) {
 128                 $value = $this->get( $key, $flags );
 129
 130                 if ( $value === false ) {
 131                         if ( !is_callable( $callback ) ) {
 132                                 throw new InvalidArgumentException( "Invalid cache miss callback provided." );
 133                         }
 134                         $value = call_user_func( $callback );
 135                         if ( $value !== false ) {
 136                                 $this->set( $key, $value, $ttl, $flags );
 137                         }
 138                 }
 139
 140                 return $value;
 141         }
 142
 143         /**
 144          * Get an item with the given key
 145          *
 146          * If the key includes a deterministic input hash (e.g. the key can only have
 147          * the correct value) or complete staleness checks are handled by the caller
 148          * (e.g. nothing relies on the TTL), then the READ_VERIFIED flag should be set.
 149          * This lets tiered backends know they can safely upgrade a cached value to
 150          * higher tiers using standard TTLs.
 151          *
 152          * @param string $key
 153          * @param int $flags Bitfield of BagOStuff::READ_* constants [optional]
 154          * @return mixed Returns false on failure or if the item does not exist
 155          */
 156         abstract public function get( $key, $flags = 0 );
 157
 158         /**
 159          * Set an item
 160          *
 161          * @param string $key
 162          * @param mixed $value
 163          * @param int $exptime Either an interval in seconds or a unix timestamp for expiry
 164          * @param int $flags Bitfield of BagOStuff::WRITE_* constants
 165          * @return bool Success
 166          */
 167         abstract public function set( $key, $value, $exptime = 0, $flags = 0 );
 168
 169         /**
 170          * Delete an item
 171          *
 172          * For large values written using WRITE_ALLOW_SEGMENTS, this only deletes the main
 173          * segment list key unless WRITE_PRUNE_SEGMENTS is in the flags. While deleting the segment
 174          * list key has the effect of functionally deleting the key, it leaves unused blobs in cache.
 175          *
 176          * @param string $key
 177          * @return bool True if the item was deleted or not found, false on failure
 178          * @param int $flags Bitfield of BagOStuff::WRITE_* constants
 179          */
 180         abstract public function delete( $key, $flags = 0 );
 181
 182         /**
 183          * Insert an item if it does not already exist
 184          *
 185          * @param string $key
 186          * @param mixed $value
 187          * @param int $exptime
 188          * @param int $flags Bitfield of BagOStuff::WRITE_* constants (since 1.33)
 189          * @return bool Success
 190          */
 191         abstract public function add( $key, $value, $exptime = 0, $flags = 0 );
 192
 193         /**
 194          * Merge changes into the existing cache value (possibly creating a new one)
 195          *
 196          * The callback function returns the new value given the current value
 197          * (which will be false if not present), and takes the arguments:
 198          * (this BagOStuff, cache key, current value, TTL).
 199          * The TTL parameter is reference set to $exptime. It can be overriden in the callback.
 200          * Nothing is stored nor deleted if the callback returns false.
 201          *
 202          * @param string $key
 203          * @param callable $callback Callback method to be executed
 204          * @param int $exptime Either an interval in seconds or a unix timestamp for expiry
 205          * @param int $attempts The amount of times to attempt a merge in case of failure
 206          * @param int $flags Bitfield of BagOStuff::WRITE_* constants
 207          * @return bool Success
 208          * @throws InvalidArgumentException
 209          */
 210         abstract public function merge(
 211                 $key,
 212                 callable $callback,
 213                 $exptime = 0,
 214                 $attempts = 10,
 215                 $flags = 0
 216         );
 217
 218         /**
 219          * Change the expiration on a key if it exists
 220          *
 221          * If an expiry in the past is given then the key will immediately be expired
 222          *
 223          * For large values written using WRITE_ALLOW_SEGMENTS, this only changes the TTL of the
 224          * main segment list key. While lowering the TTL of the segment list key has the effect of
 225          * functionally lowering the TTL of the key, it might leave unused blobs in cache for longer.
 226          * Raising the TTL of such keys is not effective, since the expiration of a single segment
 227          * key effectively expires the entire value.
 228          *
 229          * @param string $key
 230          * @param int $exptime TTL or UNIX timestamp
 231          * @param int $flags Bitfield of BagOStuff::WRITE_* constants (since 1.33)
 232          * @return bool Success Returns false on failure or if the item does not exist
 233          * @since 1.28
 234          */
 235         abstract public function changeTTL( $key, $exptime = 0, $flags = 0 );
 236
 237         /**
 238          * Acquire an advisory lock on a key string
 239          *
 240          * Note that if reentry is enabled, duplicate calls ignore $expiry
 241          *
 242          * @param string $key
 243          * @param int $timeout Lock wait timeout; 0 for non-blocking [optional]
 244          * @param int $expiry Lock expiry [optional]; 1 day maximum
 245          * @param string $rclass Allow reentry if set and the current lock used this value
 246          * @return bool Success
 247          */
 248         abstract public function lock( $key, $timeout = 6, $expiry = 6, $rclass = '' );
 249
 250         /**
 251          * Release an advisory lock on a key string
 252          *
 253          * @param string $key
 254          * @return bool Success
 255          */
 256         abstract public function unlock( $key );
 257
 258         /**
 259          * Get a lightweight exclusive self-unlocking lock
 260          *
 261          * Note that the same lock cannot be acquired twice.
 262          *
 263          * This is useful for task de-duplication or to avoid obtrusive
 264          * (though non-corrupting) DB errors like INSERT key conflicts
 265          * or deadlocks when using LOCK IN SHARE MODE.
 266          *
 267          * @param string $key
 268          * @param int $timeout Lock wait timeout; 0 for non-blocking [optional]
 269          * @param int $expiry Lock expiry [optional]; 1 day maximum
 270          * @param string $rclass Allow reentry if set and the current lock used this value
 271          * @return ScopedCallback|null Returns null on failure
 272          * @since 1.26
 273          */
 274         final public function getScopedLock( $key, $timeout = 6, $expiry = 30, $rclass = '' ) {
 275                 $expiry = min( $expiry ?: INF, self::TTL_DAY );
 276
 277                 if ( !$this->lock( $key, $timeout, $expiry, $rclass ) ) {
 278                         return null;
 279                 }
 280
 281                 $lSince = $this->getCurrentTime(); // lock timestamp
 282
 283                 return new ScopedCallback( function () use ( $key, $lSince, $expiry ) {
 284                         $latency = 0.050; // latency skew (err towards keeping lock present)
 285                         $age = ( $this->getCurrentTime() - $lSince + $latency );
 286                         if ( ( $age + $latency ) >= $expiry ) {
 287                                 $this->logger->warning(
 288                                         "Lock for {key} held too long ({age} sec).",
 289                                         [ 'key' => $key, 'age' => $age ]
 290                                 );
 291                                 return; // expired; it's not "safe" to delete the key
 292                         }
 293                         $this->unlock( $key );
 294                 } );
 295         }
 296
 297         /**
 298          * Delete all objects expiring before a certain date.
 299          * @param string|int $timestamp The reference date in MW or TS_UNIX format
 300          * @param callable|null $progress Optional, a function which will be called
 301          *     regularly during long-running operations with the percentage progress
 302          *     as the first parameter. [optional]
 303          * @param int $limit Maximum number of keys to delete [default: INF]
 304          *
 305          * @return bool Success; false if unimplemented
 306          */
 307         abstract public function deleteObjectsExpiringBefore(
 308                 $timestamp,
 309                 callable $progress = null,
 310                 $limit = INF
 311         );
 312
 313         /**
 314          * Get an associative array containing the item for each of the keys that have items.
 315          * @param string[] $keys List of keys
 316          * @param int $flags Bitfield; supports READ_LATEST [optional]
 317          * @return mixed[] Map of (key => value) for existing keys
 318          */
 319         abstract public function getMulti( array $keys, $flags = 0 );
 320
 321         /**
 322          * Batch insertion/replace
 323          *
 324          * This does not support WRITE_ALLOW_SEGMENTS to avoid excessive read I/O
 325          *
 326          * WRITE_BACKGROUND can be used for bulk insertion where the response is not vital
 327          *
 328          * @param mixed[] $data Map of (key => value)
 329          * @param int $exptime Either an interval in seconds or a unix timestamp for expiry
 330          * @param int $flags Bitfield of BagOStuff::WRITE_* constants (since 1.33)
 331          * @return bool Success
 332          * @since 1.24
 333          */
 334         abstract public function setMulti( array $data, $exptime = 0, $flags = 0 );
 335
 336         /**
 337          * Batch deletion
 338          *
 339          * This does not support WRITE_ALLOW_SEGMENTS to avoid excessive read I/O
 340          *
 341          * WRITE_BACKGROUND can be used for bulk deletion where the response is not vital
 342          *
 343          * @param string[] $keys List of keys
 344          * @param int $flags Bitfield of BagOStuff::WRITE_* constants
 345          * @return bool Success
 346          * @since 1.33
 347          */
 348         abstract public function deleteMulti( array $keys, $flags = 0 );
 349
 350         /**
 351          * Change the expiration of multiple keys that exist
 352          *
 353          * @see BagOStuff::changeTTL()
 354          *
 355          * @param string[] $keys List of keys
 356          * @param int $exptime TTL or UNIX timestamp
 357          * @param int $flags Bitfield of BagOStuff::WRITE_* constants (since 1.33)
 358          * @return bool Success
 359          * @since 1.34
 360          */
 361         abstract public function changeTTLMulti( array $keys, $exptime, $flags = 0 );
 362
 363         /**
 364          * Increase stored value of $key by $value while preserving its TTL
 365          * @param string $key Key to increase
 366          * @param int $value Value to add to $key (default: 1) [optional]
 367          * @return int|bool New value or false on failure
 368          */
 369         abstract public function incr( $key, $value = 1 );
 370
 371         /**
 372          * Decrease stored value of $key by $value while preserving its TTL
 373          * @param string $key
 374          * @param int $value Value to subtract from $key (default: 1) [optional]
 375          * @return int|bool New value or false on failure
 376          */
 377         abstract public function decr( $key, $value = 1 );
 378
 379         /**
 380          * Increase stored value of $key by $value while preserving its TTL
 381          *
 382          * This will create the key with value $init and TTL $ttl instead if not present
 383          *
 384          * @param string $key
 385          * @param int $ttl
 386          * @param int $value
 387          * @param int $init
 388          * @return int|bool New value or false on failure
 389          * @since 1.24
 390          */
 391         abstract public function incrWithInit( $key, $ttl, $value = 1, $init = 1 );
 392
 393         /**
 394          * Get the "last error" registered; clearLastError() should be called manually
 395          * @return int ERR_* constant for the "last error" registry
 396          * @since 1.23
 397          */
 398         abstract public function getLastError();
 399
 400         /**
 401          * Clear the "last error" registry
 402          * @since 1.23
 403          */
 404         abstract public function clearLastError();
 405
 406         /**
 407          * Let a callback be run to avoid wasting time on special blocking calls
 408          *
 409          * The callbacks may or may not be called ever, in any particular order.
 410          * They are likely to be invoked when something WRITE_SYNC is used used.
 411          * They should follow a caching pattern as shown below, so that any code
 412          * using the work will get it's result no matter what happens.
 413          * @code
 414          *     $result = null;
 415          *     $workCallback = function () use ( &$result ) {
 416          *         if ( !$result ) {
 417          *             $result = ....
 418          *         }
 419          *         return $result;
 420          *     }
 421          * @endcode
 422          *
 423          * @param callable $workCallback
 424          * @since 1.28
 425          */
 426         abstract public function addBusyCallback( callable $workCallback );
 427
 428         /**
 429          * Construct a cache key.
 430          *
 431          * @since 1.27
 432          * @param string $keyspace
 433          * @param array $args
 434          * @return string Colon-delimited list of $keyspace followed by escaped components of $args
 435          */
 436         abstract public function makeKeyInternal( $keyspace, $args );
 437
 438         /**
 439          * Make a global cache key.
 440          *
 441          * @since 1.27
 442          * @param string $class Key class
 443          * @param string|null $component [optional] Key component (starting with a key collection name)
 444          * @return string Colon-delimited list of $keyspace followed by escaped components of $args
 445          */
 446         abstract public function makeGlobalKey( $class, $component = null );
 447
 448         /**
 449          * Make a cache key, scoped to this instance's keyspace.
 450          *
 451          * @since 1.27
 452          * @param string $class Key class
 453          * @param string|null $component [optional] Key component (starting with a key collection name)
 454          * @return string Colon-delimited list of $keyspace followed by escaped components of $args
 455          */
 456         abstract public function makeKey( $class, $component = null );
 457
 458         /**
 459          * @param int $flag ATTR_* class constant
 460          * @return int QOS_* class constant
 461          * @since 1.28
 462          */
 463         public function getQoS( $flag ) {
 464                 return $this->attrMap[$flag] ?? self::QOS_UNKNOWN;
 465         }
 466
 467         /**
 468          * @return int|float The chunk size, in bytes, of segmented objects (INF for no limit)
 469          * @since 1.34
 470          */
 471         public function getSegmentationSize() {
 472                 return INF;
 473         }
 474
 475         /**
 476          * @return int|float Maximum total segmented object size in bytes (INF for no limit)
 477          * @since 1.34
 478          */
 479         public function getSegmentedValueMaxSize() {
 480                 return INF;
 481         }
 482
 483         /**
 484          * Merge the flag maps of one or more BagOStuff objects into a "lowest common denominator" map
 485          *
 486          * @param BagOStuff[] $bags
 487          * @return int[] Resulting flag map (class ATTR_* constant => class QOS_* constant)
 488          */
 489         final protected function mergeFlagMaps( array $bags ) {
 490                 $map = [];
 491                 foreach ( $bags as $bag ) {
 492                         foreach ( $bag->attrMap as $attr => $rank ) {
 493                                 if ( isset( $map[$attr] ) ) {
 494                                         $map[$attr] = min( $map[$attr], $rank );
 495                                 } else {
 496                                         $map[$attr] = $rank;
 497                                 }
 498                         }
 499                 }
 500
 501                 return $map;
 502         }
 503
 504         /**
 505          * @internal For testing only
 506          * @return float UNIX timestamp
 507          * @codeCoverageIgnore
 508          */
 509         public function getCurrentTime() {
 510                 return $this->wallClockOverride ?: microtime( true );
 511         }
 512
 513         /**
 514          * @internal For testing only
 515          * @param float|null &$time Mock UNIX timestamp
 516          * @codeCoverageIgnore
 517          */
 518         public function setMockTime( &$time ) {
 519                 $this->wallClockOverride =& $time;
 520         }
 521 }