includes/libs/objectcache/MediumSpecificBagOStuff.php

   1 <?php
   2 /**
   3  * Storage medium specific cache for storing items.
   4  *
   5  * This program is free software; you can redistribute it and/or modify
   6  * it under the terms of the GNU General Public License as published by
   7  * the Free Software Foundation; either version 2 of the License, or
   8  * (at your option) any later version.
   9  *
  10  * This program is distributed in the hope that it will be useful,
  11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  13  * GNU General Public License for more details.
  14  *
  15  * You should have received a copy of the GNU General Public License along
  16  * with this program; if not, write to the Free Software Foundation, Inc.,
  17  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  18  * http://www.gnu.org/copyleft/gpl.html
  19  *
  20  * @file
  21  * @ingroup Cache
  22  */
  23
  24 use Wikimedia\WaitConditionLoop;
  25
  26 /**
  27  * Storage medium specific cache for storing items (e.g. redis, memcached, ...)
  28  *
  29  * This should not be used for proxy classes that simply wrap other cache instances
  30  *
  31  * @ingroup Cache
  32  * @since 1.34
  33  */
  34 abstract class MediumSpecificBagOStuff extends BagOStuff {
  35         /** @var array[] Lock tracking */
  36         protected $locks = [];
  37         /** @var int ERR_* class constant */
  38         protected $lastError = self::ERR_NONE;
  39         /** @var string */
  40         protected $keyspace = 'local';
  41         /** @var int Seconds */
  42         protected $syncTimeout;
  43         /** @var int Bytes; chunk size of segmented cache values */
  44         protected $segmentationSize;
  45         /** @var int Bytes; maximum total size of a segmented cache value */
  46         protected $segmentedValueMaxSize;
  47
  48         /** @var array */
  49         private $duplicateKeyLookups = [];
  50         /** @var bool */
  51         private $reportDupes = false;
  52         /** @var bool */
  53         private $dupeTrackScheduled = false;
  54
  55         /** @var callable[] */
  56         protected $busyCallbacks = [];
  57
  58         /** @var string Component to use for key construction of blob segment keys */
  59         const SEGMENT_COMPONENT = 'segment';
  60
  61         /**
  62          * @see BagOStuff::__construct()
  63          * Additional $params options include:
  64          *   - logger: Psr\Log\LoggerInterface instance
  65          *   - keyspace: Default keyspace for $this->makeKey()
  66          *   - reportDupes: Whether to emit warning log messages for all keys that were
  67          *      requested more than once (requires an asyncHandler).
  68          *   - syncTimeout: How long to wait with WRITE_SYNC in seconds.
  69          *   - segmentationSize: The chunk size, in bytes, of segmented values. The value should
  70          *      not exceed the maximum size of values in the storage backend, as configured by
  71          *      the site administrator.
  72          *   - segmentedValueMaxSize: The maximum total size, in bytes, of segmented values.
  73          *      This should be configured to a reasonable size give the site traffic and the
  74          *      amount of I/O between application and cache servers that the network can handle.
  75          * @param array $params
  76          */
  77         public function __construct( array $params = [] ) {
  78                 parent::__construct( $params );
  79
  80                 if ( isset( $params['keyspace'] ) ) {
  81                         $this->keyspace = $params['keyspace'];
  82                 }
  83
  84                 if ( !empty( $params['reportDupes'] ) && is_callable( $this->asyncHandler ) ) {
  85                         $this->reportDupes = true;
  86                 }
  87
  88                 $this->syncTimeout = $params['syncTimeout'] ?? 3;
  89                 $this->segmentationSize = $params['segmentationSize'] ?? 8388608; // 8MiB
  90                 $this->segmentedValueMaxSize = $params['segmentedValueMaxSize'] ?? 67108864; // 64MiB
  91         }
  92
  93         /**
  94          * Get an item with the given key
  95          *
  96          * If the key includes a deterministic input hash (e.g. the key can only have
  97          * the correct value) or complete staleness checks are handled by the caller
  98          * (e.g. nothing relies on the TTL), then the READ_VERIFIED flag should be set.
  99          * This lets tiered backends know they can safely upgrade a cached value to
 100          * higher tiers using standard TTLs.
 101          *
 102          * @param string $key
 103          * @param int $flags Bitfield of BagOStuff::READ_* constants [optional]
 104          * @return mixed Returns false on failure or if the item does not exist
 105          */
 106         public function get( $key, $flags = 0 ) {
 107                 $this->trackDuplicateKeys( $key );
 108
 109                 return $this->resolveSegments( $key, $this->doGet( $key, $flags ) );
 110         }
 111
 112         /**
 113          * Track the number of times that a given key has been used.
 114          * @param string $key
 115          */
 116         private function trackDuplicateKeys( $key ) {
 117                 if ( !$this->reportDupes ) {
 118                         return;
 119                 }
 120
 121                 if ( !isset( $this->duplicateKeyLookups[$key] ) ) {
 122                         // Track that we have seen this key. This N-1 counting style allows
 123                         // easy filtering with array_filter() later.
 124                         $this->duplicateKeyLookups[$key] = 0;
 125                 } else {
 126                         $this->duplicateKeyLookups[$key] += 1;
 127
 128                         if ( $this->dupeTrackScheduled === false ) {
 129                                 $this->dupeTrackScheduled = true;
 130                                 // Schedule a callback that logs keys processed more than once by get().
 131                                 call_user_func( $this->asyncHandler, function () {
 132                                         $dups = array_filter( $this->duplicateKeyLookups );
 133                                         foreach ( $dups as $key => $count ) {
 134                                                 $this->logger->warning(
 135                                                         'Duplicate get(): "{key}" fetched {count} times',
 136                                                         // Count is N-1 of the actual lookup count
 137                                                         [ 'key' => $key, 'count' => $count + 1, ]
 138                                                 );
 139                                         }
 140                                 } );
 141                         }
 142                 }
 143         }
 144
 145         /**
 146          * @param string $key
 147          * @param int $flags Bitfield of BagOStuff::READ_* constants [optional]
 148          * @param mixed|null &$casToken Token to use for check-and-set comparisons
 149          * @return mixed Returns false on failure or if the item does not exist
 150          */
 151         abstract protected function doGet( $key, $flags = 0, &$casToken = null );
 152
 153         /**
 154          * Set an item
 155          *
 156          * @param string $key
 157          * @param mixed $value
 158          * @param int $exptime Either an interval in seconds or a unix timestamp for expiry
 159          * @param int $flags Bitfield of BagOStuff::WRITE_* constants
 160          * @return bool Success
 161          */
 162         public function set( $key, $value, $exptime = 0, $flags = 0 ) {
 163                 list( $entry, $usable ) = $this->makeValueOrSegmentList( $key, $value, $exptime, $flags );
 164                 // Only when all segments (if any) are stored should the main key be changed
 165                 return $usable ? $this->doSet( $key, $entry, $exptime, $flags ) : false;
 166         }
 167
 168         /**
 169          * Set an item
 170          *
 171          * @param string $key
 172          * @param mixed $value
 173          * @param int $exptime Either an interval in seconds or a unix timestamp for expiry
 174          * @param int $flags Bitfield of BagOStuff::WRITE_* constants
 175          * @return bool Success
 176          */
 177         abstract protected function doSet( $key, $value, $exptime = 0, $flags = 0 );
 178
 179         /**
 180          * Delete an item
 181          *
 182          * For large values written using WRITE_ALLOW_SEGMENTS, this only deletes the main
 183          * segment list key unless WRITE_PRUNE_SEGMENTS is in the flags. While deleting the segment
 184          * list key has the effect of functionally deleting the key, it leaves unused blobs in cache.
 185          *
 186          * @param string $key
 187          * @param int $flags Bitfield of BagOStuff::WRITE_* constants
 188          * @return bool True if the item was deleted or not found, false on failure
 189          */
 190         public function delete( $key, $flags = 0 ) {
 191                 if ( !$this->fieldHasFlags( $flags, self::WRITE_PRUNE_SEGMENTS ) ) {
 192                         return $this->doDelete( $key, $flags );
 193                 }
 194
 195                 $mainValue = $this->doGet( $key, self::READ_LATEST );
 196                 if ( !$this->doDelete( $key, $flags ) ) {
 197                         return false;
 198                 }
 199
 200                 if ( !SerializedValueContainer::isSegmented( $mainValue ) ) {
 201                         return true; // no segments to delete
 202                 }
 203
 204                 $orderedKeys = array_map(
 205                         function ( $segmentHash ) use ( $key ) {
 206                                 return $this->makeGlobalKey( self::SEGMENT_COMPONENT, $key, $segmentHash );
 207                         },
 208                         $mainValue->{SerializedValueContainer::SEGMENTED_HASHES}
 209                 );
 210
 211                 return $this->deleteMulti( $orderedKeys, $flags & ~self::WRITE_PRUNE_SEGMENTS );
 212         }
 213
 214         /**
 215          * Delete an item
 216          *
 217          * @param string $key
 218          * @param int $flags Bitfield of BagOStuff::WRITE_* constants
 219          * @return bool True if the item was deleted or not found, false on failure
 220          */
 221         abstract protected function doDelete( $key, $flags = 0 );
 222
 223         public function add( $key, $value, $exptime = 0, $flags = 0 ) {
 224                 list( $entry, $usable ) = $this->makeValueOrSegmentList( $key, $value, $exptime, $flags );
 225                 // Only when all segments (if any) are stored should the main key be changed
 226                 return $usable ? $this->doAdd( $key, $entry, $exptime, $flags ) : false;
 227         }
 228
 229         /**
 230          * Insert an item if it does not already exist
 231          *
 232          * @param string $key
 233          * @param mixed $value
 234          * @param int $exptime
 235          * @param int $flags Bitfield of BagOStuff::WRITE_* constants (since 1.33)
 236          * @return bool Success
 237          */
 238         abstract protected function doAdd( $key, $value, $exptime = 0, $flags = 0 );
 239
 240         /**
 241          * Merge changes into the existing cache value (possibly creating a new one)
 242          *
 243          * The callback function returns the new value given the current value
 244          * (which will be false if not present), and takes the arguments:
 245          * (this BagOStuff, cache key, current value, TTL).
 246          * The TTL parameter is reference set to $exptime. It can be overriden in the callback.
 247          * Nothing is stored nor deleted if the callback returns false.
 248          *
 249          * @param string $key
 250          * @param callable $callback Callback method to be executed
 251          * @param int $exptime Either an interval in seconds or a unix timestamp for expiry
 252          * @param int $attempts The amount of times to attempt a merge in case of failure
 253          * @param int $flags Bitfield of BagOStuff::WRITE_* constants
 254          * @return bool Success
 255          */
 256         public function merge( $key, callable $callback, $exptime = 0, $attempts = 10, $flags = 0 ) {
 257                 return $this->mergeViaCas( $key, $callback, $exptime, $attempts, $flags );
 258         }
 259
 260         /**
 261          * @param string $key
 262          * @param callable $callback Callback method to be executed
 263          * @param int $exptime Either an interval in seconds or a unix timestamp for expiry
 264          * @param int $attempts The amount of times to attempt a merge in case of failure
 265          * @param int $flags Bitfield of BagOStuff::WRITE_* constants
 266          * @return bool Success
 267          * @see BagOStuff::merge()
 268          */
 269         final protected function mergeViaCas( $key, callable $callback, $exptime, $attempts, $flags ) {
 270                 $attemptsLeft = $attempts;
 271                 do {
 272                         $token = null; // passed by reference
 273                         // Get the old value and CAS token from cache
 274                         $this->clearLastError();
 275                         $currentValue = $this->resolveSegments(
 276                                 $key,
 277                                 $this->doGet( $key, $flags, $token )
 278                         );
 279                         if ( $this->getLastError() ) {
 280                                 // Don't spam slow retries due to network problems (retry only on races)
 281                                 $this->logger->warning(
 282                                         __METHOD__ . ' failed due to read I/O error on get() for {key}.',
 283                                         [ 'key' => $key ]
 284                                 );
 285                                 $success = false;
 286                                 break;
 287                         }
 288
 289                         // Derive the new value from the old value
 290                         $value = call_user_func( $callback, $this, $key, $currentValue, $exptime );
 291                         $keyWasNonexistant = ( $currentValue === false );
 292                         $valueMatchesOldValue = ( $value === $currentValue );
 293                         unset( $currentValue ); // free RAM in case the value is large
 294
 295                         $this->clearLastError();
 296                         if ( $value === false || $exptime < 0 ) {
 297                                 $success = true; // do nothing
 298                         } elseif ( $valueMatchesOldValue && $attemptsLeft !== $attempts ) {
 299                                 $success = true; // recently set by another thread to the same value
 300                         } elseif ( $keyWasNonexistant ) {
 301                                 // Try to create the key, failing if it gets created in the meantime
 302                                 $success = $this->add( $key, $value, $exptime, $flags );
 303                         } else {
 304                                 // Try to update the key, failing if it gets changed in the meantime
 305                                 $success = $this->cas( $token, $key, $value, $exptime, $flags );
 306                         }
 307                         if ( $this->getLastError() ) {
 308                                 // Don't spam slow retries due to network problems (retry only on races)
 309                                 $this->logger->warning(
 310                                         __METHOD__ . ' failed due to write I/O error for {key}.',
 311                                         [ 'key' => $key ]
 312                                 );
 313                                 $success = false;
 314                                 break;
 315                         }
 316
 317                 } while ( !$success && --$attemptsLeft );
 318
 319                 return $success;
 320         }
 321
 322         /**
 323          * Check and set an item
 324          *
 325          * @param mixed $casToken
 326          * @param string $key
 327          * @param mixed $value
 328          * @param int $exptime Either an interval in seconds or a unix timestamp for expiry
 329          * @param int $flags Bitfield of BagOStuff::WRITE_* constants
 330          * @return bool Success
 331          */
 332         protected function cas( $casToken, $key, $value, $exptime = 0, $flags = 0 ) {
 333                 if ( $casToken === null ) {
 334                         $this->logger->warning(
 335                                 __METHOD__ . ' got empty CAS token for {key}.',
 336                                 [ 'key' => $key ]
 337                         );
 338
 339                         return false; // caller may have meant to use add()?
 340                 }
 341
 342                 list( $entry, $usable ) = $this->makeValueOrSegmentList( $key, $value, $exptime, $flags );
 343                 // Only when all segments (if any) are stored should the main key be changed
 344                 return $usable ? $this->doCas( $casToken, $key, $entry, $exptime, $flags ) : false;
 345         }
 346
 347         /**
 348          * Check and set an item
 349          *
 350          * @param mixed $casToken
 351          * @param string $key
 352          * @param mixed $value
 353          * @param int $exptime Either an interval in seconds or a unix timestamp for expiry
 354          * @param int $flags Bitfield of BagOStuff::WRITE_* constants
 355          * @return bool Success
 356          */
 357         protected function doCas( $casToken, $key, $value, $exptime = 0, $flags = 0 ) {
 358                 // @TODO: the lock() call assumes that all other relavent sets() use one
 359                 if ( !$this->lock( $key, 0 ) ) {
 360                         return false; // non-blocking
 361                 }
 362
 363                 $curCasToken = null; // passed by reference
 364                 $this->clearLastError();
 365                 $this->doGet( $key, self::READ_LATEST, $curCasToken );
 366                 if ( is_object( $curCasToken ) ) {
 367                         // Using === does not work with objects since it checks for instance identity
 368                         throw new UnexpectedValueException( "CAS token cannot be an object" );
 369                 }
 370                 if ( $this->getLastError() ) {
 371                         // Fail if the old CAS token could not be read
 372                         $success = false;
 373                         $this->logger->warning(
 374                                 __METHOD__ . ' failed due to write I/O error for {key}.',
 375                                 [ 'key' => $key ]
 376                         );
 377                 } elseif ( $casToken === $curCasToken ) {
 378                         $success = $this->doSet( $key, $value, $exptime, $flags );
 379                 } else {
 380                         $success = false; // mismatched or failed
 381                         $this->logger->info(
 382                                 __METHOD__ . ' failed due to race condition for {key}.',
 383                                 [ 'key' => $key ]
 384                         );
 385                 }
 386
 387                 $this->unlock( $key );
 388
 389                 return $success;
 390         }
 391
 392         /**
 393          * Change the expiration on a key if it exists
 394          *
 395          * If an expiry in the past is given then the key will immediately be expired
 396          *
 397          * For large values written using WRITE_ALLOW_SEGMENTS, this only changes the TTL of the
 398          * main segment list key. While lowering the TTL of the segment list key has the effect of
 399          * functionally lowering the TTL of the key, it might leave unused blobs in cache for longer.
 400          * Raising the TTL of such keys is not effective, since the expiration of a single segment
 401          * key effectively expires the entire value.
 402          *
 403          * @param string $key
 404          * @param int $exptime TTL or UNIX timestamp
 405          * @param int $flags Bitfield of BagOStuff::WRITE_* constants (since 1.33)
 406          * @return bool Success Returns false on failure or if the item does not exist
 407          * @since 1.28
 408          */
 409         public function changeTTL( $key, $exptime = 0, $flags = 0 ) {
 410                 return $this->doChangeTTL( $key, $exptime, $flags );
 411         }
 412
 413         /**
 414          * @param string $key
 415          * @param int $exptime
 416          * @param int $flags
 417          * @return bool
 418          */
 419         protected function doChangeTTL( $key, $exptime, $flags ) {
 420                 if ( !$this->lock( $key, 0 ) ) {
 421                         return false;
 422                 }
 423
 424                 $expiry = $this->getExpirationAsTimestamp( $exptime );
 425                 $delete = ( $expiry != self::TTL_INDEFINITE && $expiry < $this->getCurrentTime() );
 426
 427                 // Use doGet() to avoid having to trigger resolveSegments()
 428                 $blob = $this->doGet( $key, self::READ_LATEST );
 429                 if ( $blob ) {
 430                         if ( $delete ) {
 431                                 $ok = $this->doDelete( $key, $flags );
 432                         } else {
 433                                 $ok = $this->doSet( $key, $blob, $exptime, $flags );
 434                         }
 435                 } else {
 436                         $ok = false;
 437                 }
 438
 439                 $this->unlock( $key );
 440
 441                 return $ok;
 442         }
 443
 444         /**
 445          * Acquire an advisory lock on a key string
 446          *
 447          * Note that if reentry is enabled, duplicate calls ignore $expiry
 448          *
 449          * @param string $key
 450          * @param int $timeout Lock wait timeout; 0 for non-blocking [optional]
 451          * @param int $expiry Lock expiry [optional]; 1 day maximum
 452          * @param string $rclass Allow reentry if set and the current lock used this value
 453          * @return bool Success
 454          */
 455         public function lock( $key, $timeout = 6, $expiry = 6, $rclass = '' ) {
 456                 // Avoid deadlocks and allow lock reentry if specified
 457                 if ( isset( $this->locks[$key] ) ) {
 458                         if ( $rclass != '' && $this->locks[$key]['class'] === $rclass ) {
 459                                 ++$this->locks[$key]['depth'];
 460                                 return true;
 461                         } else {
 462                                 return false;
 463                         }
 464                 }
 465
 466                 $fname = __METHOD__;
 467                 $expiry = min( $expiry ?: INF, self::TTL_DAY );
 468                 $loop = new WaitConditionLoop(
 469                         function () use ( $key, $expiry, $fname ) {
 470                                 $this->clearLastError();
 471                                 if ( $this->add( "{$key}:lock", 1, $expiry ) ) {
 472                                         return WaitConditionLoop::CONDITION_REACHED; // locked!
 473                                 } elseif ( $this->getLastError() ) {
 474                                         $this->logger->warning(
 475                                                 $fname . ' failed due to I/O error for {key}.',
 476                                                 [ 'key' => $key ]
 477                                         );
 478
 479                                         return WaitConditionLoop::CONDITION_ABORTED; // network partition?
 480                                 }
 481
 482                                 return WaitConditionLoop::CONDITION_CONTINUE;
 483                         },
 484                         $timeout
 485                 );
 486
 487                 $code = $loop->invoke();
 488                 $locked = ( $code === $loop::CONDITION_REACHED );
 489                 if ( $locked ) {
 490                         $this->locks[$key] = [ 'class' => $rclass, 'depth' => 1 ];
 491                 } elseif ( $code === $loop::CONDITION_TIMED_OUT ) {
 492                         $this->logger->warning(
 493                                 "$fname failed due to timeout for {key}.",
 494                                 [ 'key' => $key, 'timeout' => $timeout ]
 495                         );
 496                 }
 497
 498                 return $locked;
 499         }
 500
 501         /**
 502          * Release an advisory lock on a key string
 503          *
 504          * @param string $key
 505          * @return bool Success
 506          */
 507         public function unlock( $key ) {
 508                 if ( !isset( $this->locks[$key] ) ) {
 509                         return false;
 510                 }
 511
 512                 if ( --$this->locks[$key]['depth'] <= 0 ) {
 513                         unset( $this->locks[$key] );
 514
 515                         $ok = $this->doDelete( "{$key}:lock" );
 516                         if ( !$ok ) {
 517                                 $this->logger->warning(
 518                                         __METHOD__ . ' failed to release lock for {key}.',
 519                                         [ 'key' => $key ]
 520                                 );
 521                         }
 522
 523                         return $ok;
 524                 }
 525
 526                 return true;
 527         }
 528
 529         /**
 530          * Delete all objects expiring before a certain date.
 531          * @param string|int $timestamp The reference date in MW or TS_UNIX format
 532          * @param callable|null $progress Optional, a function which will be called
 533          *     regularly during long-running operations with the percentage progress
 534          *     as the first parameter. [optional]
 535          * @param int $limit Maximum number of keys to delete [default: INF]
 536          *
 537          * @return bool Success; false if unimplemented
 538          */
 539         public function deleteObjectsExpiringBefore(
 540                 $timestamp,
 541                 callable $progress = null,
 542                 $limit = INF
 543         ) {
 544                 return false;
 545         }
 546
 547         /**
 548          * Get an associative array containing the item for each of the keys that have items.
 549          * @param string[] $keys List of keys; can be a map of (unused => key) for convenience
 550          * @param int $flags Bitfield; supports READ_LATEST [optional]
 551          * @return mixed[] Map of (key => value) for existing keys; preserves the order of $keys
 552          */
 553         public function getMulti( array $keys, $flags = 0 ) {
 554                 $foundByKey = $this->doGetMulti( $keys, $flags );
 555
 556                 $res = [];
 557                 foreach ( $keys as $key ) {
 558                         // Resolve one blob at a time (avoids too much I/O at once)
 559                         if ( array_key_exists( $key, $foundByKey ) ) {
 560                                 // A value should not appear in the key if a segment is missing
 561                                 $value = $this->resolveSegments( $key, $foundByKey[$key] );
 562                                 if ( $value !== false ) {
 563                                         $res[$key] = $value;
 564                                 }
 565                         }
 566                 }
 567
 568                 return $res;
 569         }
 570
 571         /**
 572          * Get an associative array containing the item for each of the keys that have items.
 573          * @param string[] $keys List of keys
 574          * @param int $flags Bitfield; supports READ_LATEST [optional]
 575          * @return array Map of (key => value) for existing keys
 576          */
 577         protected function doGetMulti( array $keys, $flags = 0 ) {
 578                 $res = [];
 579                 foreach ( $keys as $key ) {
 580                         $val = $this->doGet( $key, $flags );
 581                         if ( $val !== false ) {
 582                                 $res[$key] = $val;
 583                         }
 584                 }
 585
 586                 return $res;
 587         }
 588
 589         /**
 590          * Batch insertion/replace
 591          *
 592          * This does not support WRITE_ALLOW_SEGMENTS to avoid excessive read I/O
 593          *
 594          * @param mixed[] $data Map of (key => value)
 595          * @param int $exptime Either an interval in seconds or a unix timestamp for expiry
 596          * @param int $flags Bitfield of BagOStuff::WRITE_* constants (since 1.33)
 597          * @return bool Success
 598          * @since 1.24
 599          */
 600         public function setMulti( array $data, $exptime = 0, $flags = 0 ) {
 601                 if ( $this->fieldHasFlags( $flags, self::WRITE_ALLOW_SEGMENTS ) ) {
 602                         throw new InvalidArgumentException( __METHOD__ . ' got WRITE_ALLOW_SEGMENTS' );
 603                 }
 604
 605                 return $this->doSetMulti( $data, $exptime, $flags );
 606         }
 607
 608         /**
 609          * @param mixed[] $data Map of (key => value)
 610          * @param int $exptime Either an interval in seconds or a unix timestamp for expiry
 611          * @param int $flags Bitfield of BagOStuff::WRITE_* constants
 612          * @return bool Success
 613          */
 614         protected function doSetMulti( array $data, $exptime = 0, $flags = 0 ) {
 615                 $res = true;
 616                 foreach ( $data as $key => $value ) {
 617                         $res = $this->doSet( $key, $value, $exptime, $flags ) && $res;
 618                 }
 619
 620                 return $res;
 621         }
 622
 623         /**
 624          * Batch deletion
 625          *
 626          * This does not support WRITE_ALLOW_SEGMENTS to avoid excessive read I/O
 627          *
 628          * @param string[] $keys List of keys
 629          * @param int $flags Bitfield of BagOStuff::WRITE_* constants
 630          * @return bool Success
 631          * @since 1.33
 632          */
 633         public function deleteMulti( array $keys, $flags = 0 ) {
 634                 if ( $this->fieldHasFlags( $flags, self::WRITE_PRUNE_SEGMENTS ) ) {
 635                         throw new InvalidArgumentException( __METHOD__ . ' got WRITE_PRUNE_SEGMENTS' );
 636                 }
 637
 638                 return $this->doDeleteMulti( $keys, $flags );
 639         }
 640
 641         /**
 642          * @param string[] $keys List of keys
 643          * @param int $flags Bitfield of BagOStuff::WRITE_* constants
 644          * @return bool Success
 645          */
 646         protected function doDeleteMulti( array $keys, $flags = 0 ) {
 647                 $res = true;
 648                 foreach ( $keys as $key ) {
 649                         $res = $this->doDelete( $key, $flags ) && $res;
 650                 }
 651                 return $res;
 652         }
 653
 654         /**
 655          * Change the expiration of multiple keys that exist
 656          *
 657          * @param string[] $keys List of keys
 658          * @param int $exptime TTL or UNIX timestamp
 659          * @param int $flags Bitfield of BagOStuff::WRITE_* constants (since 1.33)
 660          * @return bool Success
 661          * @see BagOStuff::changeTTL()
 662          *
 663          * @since 1.34
 664          */
 665         public function changeTTLMulti( array $keys, $exptime, $flags = 0 ) {
 666                 $res = true;
 667                 foreach ( $keys as $key ) {
 668                         $res = $this->doChangeTTL( $key, $exptime, $flags ) && $res;
 669                 }
 670
 671                 return $res;
 672         }
 673
 674         public function incrWithInit( $key, $exptime, $value = 1, $init = null, $flags = 0 ) {
 675                 $init = is_int( $init ) ? $init : $value;
 676                 $this->clearLastError();
 677                 $newValue = $this->incr( $key, $value, $flags );
 678                 if ( $newValue === false && !$this->getLastError() ) {
 679                         // No key set; initialize
 680                         $newValue = $this->add( $key, (int)$init, $exptime, $flags ) ? $init : false;
 681                         if ( $newValue === false && !$this->getLastError() ) {
 682                                 // Raced out initializing; increment
 683                                 $newValue = $this->incr( $key, $value, $flags );
 684                         }
 685                 }
 686
 687                 return $newValue;
 688         }
 689
 690         /**
 691          * Get and reassemble the chunks of blob at the given key
 692          *
 693          * @param string $key
 694          * @param mixed $mainValue
 695          * @return string|null|bool The combined string, false if missing, null on error
 696          */
 697         final protected function resolveSegments( $key, $mainValue ) {
 698                 if ( SerializedValueContainer::isUnified( $mainValue ) ) {
 699                         return $this->unserialize( $mainValue->{SerializedValueContainer::UNIFIED_DATA} );
 700                 }
 701
 702                 if ( SerializedValueContainer::isSegmented( $mainValue ) ) {
 703                         $orderedKeys = array_map(
 704                                 function ( $segmentHash ) use ( $key ) {
 705                                         return $this->makeGlobalKey( self::SEGMENT_COMPONENT, $key, $segmentHash );
 706                                 },
 707                                 $mainValue->{SerializedValueContainer::SEGMENTED_HASHES}
 708                         );
 709
 710                         $segmentsByKey = $this->doGetMulti( $orderedKeys );
 711
 712                         $parts = [];
 713                         foreach ( $orderedKeys as $segmentKey ) {
 714                                 if ( isset( $segmentsByKey[$segmentKey] ) ) {
 715                                         $parts[] = $segmentsByKey[$segmentKey];
 716                                 } else {
 717                                         return false; // missing segment
 718                                 }
 719                         }
 720
 721                         return $this->unserialize( implode( '', $parts ) );
 722                 }
 723
 724                 return $mainValue;
 725         }
 726
 727         /**
 728          * Get the "last error" registered; clearLastError() should be called manually
 729          * @return int ERR_* constant for the "last error" registry
 730          * @since 1.23
 731          */
 732         public function getLastError() {
 733                 return $this->lastError;
 734         }
 735
 736         /**
 737          * Clear the "last error" registry
 738          * @since 1.23
 739          */
 740         public function clearLastError() {
 741                 $this->lastError = self::ERR_NONE;
 742         }
 743
 744         /**
 745          * Set the "last error" registry
 746          * @param int $err ERR_* constant
 747          * @since 1.23
 748          */
 749         protected function setLastError( $err ) {
 750                 $this->lastError = $err;
 751         }
 752
 753         final public function addBusyCallback( callable $workCallback ) {
 754                 $this->busyCallbacks[] = $workCallback;
 755         }
 756
 757         /**
 758          * Determine the entry (inline or segment list) to store under a key to save the value
 759          *
 760          * @param string $key
 761          * @param mixed $value
 762          * @param int $exptime
 763          * @param int $flags
 764          * @return array (inline value or segment list, whether the entry is usable)
 765          * @since 1.34
 766          */
 767         final protected function makeValueOrSegmentList( $key, $value, $exptime, $flags ) {
 768                 $entry = $value;
 769                 $usable = true;
 770
 771                 if (
 772                         $this->fieldHasFlags( $flags, self::WRITE_ALLOW_SEGMENTS ) &&
 773                         !is_int( $value ) && // avoid breaking incr()/decr()
 774                         is_finite( $this->segmentationSize )
 775                 ) {
 776                         $segmentSize = $this->segmentationSize;
 777                         $maxTotalSize = $this->segmentedValueMaxSize;
 778
 779                         $serialized = $this->serialize( $value );
 780                         $size = strlen( $serialized );
 781                         if ( $size > $maxTotalSize ) {
 782                                 $this->logger->warning(
 783                                         "Value for {key} exceeds $maxTotalSize bytes; cannot segment.",
 784                                         [ 'key' => $key ]
 785                                 );
 786                         } elseif ( $size <= $segmentSize ) {
 787                                 // The serialized value was already computed, so just use it inline
 788                                 $entry = SerializedValueContainer::newUnified( $serialized );
 789                         } else {
 790                                 // Split the serialized value into chunks and store them at different keys
 791                                 $chunksByKey = [];
 792                                 $segmentHashes = [];
 793                                 $count = intdiv( $size, $segmentSize ) + ( ( $size % $segmentSize ) ? 1 : 0 );
 794                                 for ( $i = 0; $i < $count; ++$i ) {
 795                                         $segment = substr( $serialized, $i * $segmentSize, $segmentSize );
 796                                         $hash = sha1( $segment );
 797                                         $chunkKey = $this->makeGlobalKey( self::SEGMENT_COMPONENT, $key, $hash );
 798                                         $chunksByKey[$chunkKey] = $segment;
 799                                         $segmentHashes[] = $hash;
 800                                 }
 801                                 $flags &= ~self::WRITE_ALLOW_SEGMENTS; // sanity
 802                                 $usable = $this->setMulti( $chunksByKey, $exptime, $flags );
 803                                 $entry = SerializedValueContainer::newSegmented( $segmentHashes );
 804                         }
 805                 }
 806
 807                 return [ $entry, $usable ];
 808         }
 809
 810         /**
 811          * @param int|float $exptime
 812          * @return bool Whether the expiry is non-infinite, and, negative or not a UNIX timestamp
 813          * @since 1.34
 814          */
 815         final protected function isRelativeExpiration( $exptime ) {
 816                 return ( $exptime !== self::TTL_INDEFINITE && $exptime < ( 10 * self::TTL_YEAR ) );
 817         }
 818
 819         /**
 820          * Convert an optionally relative timestamp to an absolute time
 821          *
 822          * The input value will be cast to an integer and interpreted as follows:
 823          *   - zero: no expiry; return zero (e.g. TTL_INDEFINITE)
 824          *   - negative: relative TTL; return UNIX timestamp offset by this value
 825          *   - positive (< 10 years): relative TTL; return UNIX timestamp offset by this value
 826          *   - positive (>= 10 years): absolute UNIX timestamp; return this value
 827          *
 828          * @param int $exptime
 829          * @return int Expiration timestamp or TTL_INDEFINITE for indefinite
 830          * @since 1.34
 831          */
 832         final protected function getExpirationAsTimestamp( $exptime ) {
 833                 if ( $exptime == self::TTL_INDEFINITE ) {
 834                         return $exptime;
 835                 }
 836
 837                 return $this->isRelativeExpiration( $exptime )
 838                         ? intval( $this->getCurrentTime() + $exptime )
 839                         : $exptime;
 840         }
 841
 842         /**
 843          * Convert an optionally absolute expiry time to a relative time. If an
 844          * absolute time is specified which is in the past, use a short expiry time.
 845          *
 846          * The input value will be cast to an integer and interpreted as follows:
 847          *   - zero: no expiry; return zero (e.g. TTL_INDEFINITE)
 848          *   - negative: relative TTL; return a short expiry time (1 second)
 849          *   - positive (< 10 years): relative TTL; return this value
 850          *   - positive (>= 10 years): absolute UNIX timestamp; return offset to current time
 851          *
 852          * @param int $exptime
 853          * @return int Relative TTL or TTL_INDEFINITE for indefinite
 854          * @since 1.34
 855          */
 856         final protected function getExpirationAsTTL( $exptime ) {
 857                 if ( $exptime == self::TTL_INDEFINITE ) {
 858                         return $exptime;
 859                 }
 860
 861                 return $this->isRelativeExpiration( $exptime )
 862                         ? $exptime
 863                         : (int)max( $exptime - $this->getCurrentTime(), 1 );
 864         }
 865
 866         /**
 867          * Check if a value is an integer
 868          *
 869          * @param mixed $value
 870          * @return bool
 871          */
 872         final protected function isInteger( $value ) {
 873                 if ( is_int( $value ) ) {
 874                         return true;
 875                 } elseif ( !is_string( $value ) ) {
 876                         return false;
 877                 }
 878
 879                 $integer = (int)$value;
 880
 881                 return ( $value === (string)$integer );
 882         }
 883
 884         public function makeKeyInternal( $keyspace, $args ) {
 885                 $key = $keyspace;
 886                 foreach ( $args as $arg ) {
 887                         $key .= ':' . str_replace( ':', '%3A', $arg );
 888                 }
 889                 return strtr( $key, ' ', '_' );
 890         }
 891
 892         /**
 893          * Make a global cache key.
 894          *
 895          * @param string $class Key class
 896          * @param string ...$components Key components (starting with a key collection name)
 897          * @return string Colon-delimited list of $keyspace followed by escaped components
 898          * @since 1.27
 899          */
 900         public function makeGlobalKey( $class, ...$components ) {
 901                 return $this->makeKeyInternal( 'global', func_get_args() );
 902         }
 903
 904         /**
 905          * Make a cache key, scoped to this instance's keyspace.
 906          *
 907          * @param string $class Key class
 908          * @param string ...$components Key components (starting with a key collection name)
 909          * @return string Colon-delimited list of $keyspace followed by escaped components
 910          * @since 1.27
 911          */
 912         public function makeKey( $class, ...$components ) {
 913                 return $this->makeKeyInternal( $this->keyspace, func_get_args() );
 914         }
 915
 916         /**
 917          * @param int $flag ATTR_* class constant
 918          * @return int QOS_* class constant
 919          * @since 1.28
 920          */
 921         public function getQoS( $flag ) {
 922                 return $this->attrMap[$flag] ?? self::QOS_UNKNOWN;
 923         }
 924
 925         public function getSegmentationSize() {
 926                 return $this->segmentationSize;
 927         }
 928
 929         public function getSegmentedValueMaxSize() {
 930                 return $this->segmentedValueMaxSize;
 931         }
 932
 933         /**
 934          * @param mixed $value
 935          * @return string|int String/integer representation
 936          * @note Special handling is usually needed for integers so incr()/decr() work
 937          */
 938         protected function serialize( $value ) {
 939                 return is_int( $value ) ? $value : serialize( $value );
 940         }
 941
 942         /**
 943          * @param string|int $value
 944          * @return mixed Original value or false on error
 945          * @note Special handling is usually needed for integers so incr()/decr() work
 946          */
 947         protected function unserialize( $value ) {
 948                 return $this->isInteger( $value ) ? (int)$value : unserialize( $value );
 949         }
 950
 951         /**
 952          * @param string $text
 953          */
 954         protected function debug( $text ) {
 955                 if ( $this->debugMode ) {
 956                         $this->logger->debug( "{class} debug: $text", [ 'class' => static::class ] );
 957                 }
 958         }
 959 }