includes/libs/objectcache/HashBagOStuff.php

   1 <?php
   2 /**
   3  * This program is free software; you can redistribute it and/or modify
   4  * it under the terms of the GNU General Public License as published by
   5  * the Free Software Foundation; either version 2 of the License, or
   6  * (at your option) any later version.
   7  *
   8  * This program is distributed in the hope that it will be useful,
   9  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  10  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  11  * GNU General Public License for more details.
  12  *
  13  * You should have received a copy of the GNU General Public License along
  14  * with this program; if not, write to the Free Software Foundation, Inc.,
  15  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  16  * http://www.gnu.org/copyleft/gpl.html
  17  *
  18  * @file
  19  */
  20
  21 namespace Wikimedia\ObjectCache;
  22
  23 use InvalidArgumentException;
  24
  25 /**
  26  * Store data in a memory for the current request/process only.
  27  *
  28  * This keeps values in a simple associative array.
  29  * Data will not persist and is not shared with other requests
  30  * on the same server.
  31  *
  32  * @newable
  33  * @ingroup Cache
  34  */
  35 class HashBagOStuff extends MediumSpecificBagOStuff {
  36         /** @var mixed[] */
  37         protected $bag = [];
  38         /** @var int|double Max entries allowed, INF for unlimited */
  39         protected $maxCacheKeys;
  40
  41         /** @var string CAS token prefix for this instance */
  42         private $token;
  43
  44         /** @var int CAS token counter */
  45         private static $casCounter = 0;
  46
  47         public const KEY_VAL = 0;
  48         public const KEY_EXP = 1;
  49         public const KEY_CAS = 2;
  50
  51         /**
  52          * @stable to call
  53          *
  54          * @param array $params Additional parameters include:
  55          *   - maxKeys : only allow this many keys (using oldest-first eviction)
  56          *
  57          * @phpcs:ignore Generic.Files.LineLength
  58          * @phan-param array{logger?:\Psr\Log\LoggerInterface,asyncHandler?:callable,keyspace?:string,reportDupes?:bool,segmentationSize?:int,segmentedValueMaxSize?:int,maxKeys?:int} $params
  59          */
  60         public function __construct( $params = [] ) {
  61                 $params['segmentationSize'] ??= INF;
  62                 parent::__construct( $params );
  63
  64                 $this->token = microtime( true ) . ':' . mt_rand();
  65                 $maxKeys = $params['maxKeys'] ?? INF;
  66                 if ( $maxKeys !== INF && ( !is_int( $maxKeys ) || $maxKeys <= 0 ) ) {
  67                         throw new InvalidArgumentException( '$maxKeys parameter must be above zero' );
  68                 }
  69                 $this->maxCacheKeys = $maxKeys;
  70
  71                 $this->attrMap[self::ATTR_DURABILITY] = self::QOS_DURABILITY_SCRIPT;
  72         }
  73
  74         protected function doGet( $key, $flags = 0, &$casToken = null ) {
  75                 $getToken = ( $casToken === self::PASS_BY_REF );
  76                 $casToken = null;
  77
  78                 if ( !$this->hasKey( $key ) || $this->expire( $key ) ) {
  79                         return false;
  80                 }
  81
  82                 // Refresh key position for maxCacheKeys eviction
  83                 $temp = $this->bag[$key];
  84                 unset( $this->bag[$key] );
  85                 $this->bag[$key] = $temp;
  86
  87                 $value = $this->bag[$key][self::KEY_VAL];
  88                 if ( $getToken && $value !== false ) {
  89                         $casToken = $this->bag[$key][self::KEY_CAS];
  90                 }
  91
  92                 return $value;
  93         }
  94
  95         protected function doSet( $key, $value, $exptime = 0, $flags = 0 ) {
  96                 // Refresh key position for maxCacheKeys eviction
  97                 unset( $this->bag[$key] );
  98                 $this->bag[$key] = [
  99                         self::KEY_VAL => $value,
 100                         self::KEY_EXP => $this->getExpirationAsTimestamp( $exptime ),
 101                         self::KEY_CAS => $this->token . ':' . ++self::$casCounter
 102                 ];
 103
 104                 if ( count( $this->bag ) > $this->maxCacheKeys ) {
 105                         $evictKey = array_key_first( $this->bag );
 106                         unset( $this->bag[$evictKey] );
 107                 }
 108
 109                 return true;
 110         }
 111
 112         protected function doAdd( $key, $value, $exptime = 0, $flags = 0 ) {
 113                 if ( $this->hasKey( $key ) && !$this->expire( $key ) ) {
 114                         // key already set
 115                         return false;
 116                 }
 117
 118                 return $this->doSet( $key, $value, $exptime, $flags );
 119         }
 120
 121         protected function doDelete( $key, $flags = 0 ) {
 122                 unset( $this->bag[$key] );
 123
 124                 return true;
 125         }
 126
 127         protected function doIncrWithInit( $key, $exptime, $step, $init, $flags ) {
 128                 $curValue = $this->doGet( $key );
 129                 if ( $curValue === false ) {
 130                         $newValue = $this->doSet( $key, $init, $exptime ) ? $init : false;
 131                 } elseif ( $this->isInteger( $curValue ) ) {
 132                         $newValue = max( $curValue + $step, 0 );
 133                         $this->bag[$key][self::KEY_VAL] = $newValue;
 134                 } else {
 135                         $newValue = false;
 136                 }
 137
 138                 return $newValue;
 139         }
 140
 141         /**
 142          * Clear all values in cache
 143          */
 144         public function clear() {
 145                 $this->bag = [];
 146         }
 147
 148         /**
 149          * @param string $key
 150          *
 151          * @return bool
 152          */
 153         protected function expire( $key ) {
 154                 $et = $this->bag[$key][self::KEY_EXP];
 155                 if ( $et == self::TTL_INDEFINITE || $et > $this->getCurrentTime() ) {
 156                         return false;
 157                 }
 158
 159                 $this->doDelete( $key );
 160
 161                 return true;
 162         }
 163
 164         /**
 165          * Does this bag have a non-null value for the given key?
 166          *
 167          * @param string $key
 168          *
 169          * @return bool
 170          * @since 1.27
 171          */
 172         public function hasKey( $key ) {
 173                 return isset( $this->bag[$key] );
 174         }
 175 }
 176
 177 /** @deprecated class alias since 1.43 */
 178 class_alias( HashBagOStuff::class, 'HashBagOStuff' );