includes/objectcache/BagOStuff.php

   1 <?php
   2 /**
   3  * Classes to cache objects in PHP accelerators, SQL database or DBA files
   4  *
   5  * Copyright © 2003-2004 Brion Vibber <brion@pobox.com>
   6  * http://www.mediawiki.org/
   7  *
   8  * This program is free software; you can redistribute it and/or modify
   9  * it under the terms of the GNU General Public License as published by
  10  * the Free Software Foundation; either version 2 of the License, or
  11  * (at your option) any later version.
  12  *
  13  * This program is distributed in the hope that it will be useful,
  14  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  15  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  16  * GNU General Public License for more details.
  17  *
  18  * You should have received a copy of the GNU General Public License along
  19  * with this program; if not, write to the Free Software Foundation, Inc.,
  20  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  21  * http://www.gnu.org/copyleft/gpl.html
  22  *
  23  * @file
  24  * @ingroup Cache
  25  */
  26
  27 /**
  28  * @defgroup Cache Cache
  29  */
  30
  31 /**
  32  * interface is intended to be more or less compatible with
  33  * the PHP memcached client.
  34  *
  35  * backends for local hash array and SQL table included:
  36  * <code>
  37  *   $bag = new HashBagOStuff();
  38  *   $bag = new SqlBagOStuff(); # connect to db first
  39  * </code>
  40  *
  41  * @ingroup Cache
  42  */
  43 abstract class BagOStuff {
  44         private $debugMode = false;
  45
  46         /**
  47          * @param $bool bool
  48          */
  49         public function setDebug( $bool ) {
  50                 $this->debugMode = $bool;
  51         }
  52
  53         /* *** THE GUTS OF THE OPERATION *** */
  54         /* Override these with functional things in subclasses */
  55
  56         /**
  57          * Get an item with the given key. Returns false if it does not exist.
  58          * @param $key string
  59          * @param $casToken[optional] mixed
  60          * @return mixed Returns false on failure
  61          */
  62         abstract public function get( $key, &$casToken = null );
  63
  64         /**
  65          * Set an item.
  66          * @param $key string
  67          * @param $value mixed
  68          * @param $exptime int Either an interval in seconds or a unix timestamp for expiry
  69          * @return bool success
  70          */
  71         abstract public function set( $key, $value, $exptime = 0 );
  72
  73         /**
  74          * Check and set an item.
  75          * @param $casToken mixed
  76          * @param $key string
  77          * @param $value mixed
  78          * @param $exptime int Either an interval in seconds or a unix timestamp for expiry
  79          * @return bool success
  80          */
  81         abstract public function cas( $casToken, $key, $value, $exptime = 0 );
  82
  83         /**
  84          * Delete an item.
  85          * @param $key string
  86          * @param $time int Amount of time to delay the operation (mostly memcached-specific)
  87          * @return bool True if the item was deleted or not found, false on failure
  88          */
  89         abstract public function delete( $key, $time = 0 );
  90
  91         /**
  92          * Merge changes into the existing cache value (possibly creating a new one)
  93          *
  94          * @param $key string
  95          * @param $callback closure Callback method to be executed
  96          * @param $exptime int Either an interval in seconds or a unix timestamp for expiry
  97          * @param $attempts int The amount of times to attempt a merge in case of failure
  98          * @return bool success
  99          */
 100         public function merge( $key, closure $callback, $exptime = 0, $attempts = 10 ) {
 101                 return $this->mergeViaCas( $key, $callback, $exptime, $attempts );
 102         }
 103
 104         /**
 105          * @see BagOStuff::merge()
 106          *
 107          * @param $key string
 108          * @param $callback closure Callback method to be executed
 109          * @param $exptime int Either an interval in seconds or a unix timestamp for expiry
 110          * @param $attempts int The amount of times to attempt a merge in case of failure
 111          * @return bool success
 112          */
 113         protected function mergeViaCas( $key, closure $callback, $exptime = 0, $attempts = 10 ) {
 114                 do {
 115                         $casToken = null; // passed by reference
 116                         $currentValue = $this->get( $key, $casToken ); // get the old value
 117                         $value = $callback( $this, $key, $currentValue ); // derive the new value
 118
 119                         if ( $value === false ) {
 120                                 $success = true; // do nothing
 121                         } elseif ( $currentValue === false ) {
 122                                 // Try to create the key, failing if it gets created in the meantime
 123                                 $success = $this->add( $key, $value, $exptime );
 124                         } else {
 125                                 // Try to update the key, failing if it gets changed in the meantime
 126                                 $success = $this->cas( $casToken, $key, $value, $exptime );
 127                         }
 128                 } while ( !$success && --$attempts );
 129
 130                 return $success;
 131         }
 132
 133         /**
 134          * @see BagOStuff::merge()
 135          *
 136          * @param $key string
 137          * @param $callback closure Callback method to be executed
 138          * @param $exptime int Either an interval in seconds or a unix timestamp for expiry
 139          * @param $attempts int The amount of times to attempt a merge in case of failure
 140          * @return bool success
 141          */
 142         protected function mergeViaLock( $key, closure $callback, $exptime = 0, $attempts = 10 ) {
 143                 if ( !$this->lock( $key, 60 ) ) {
 144                         return false;
 145                 }
 146
 147                 $currentValue = $this->get( $key ); // get the old value
 148                 $value = $callback( $this, $key, $currentValue ); // derive the new value
 149
 150                 if ( $value === false ) {
 151                         $success = true; // do nothing
 152                 } else {
 153                         $success = $this->set( $key, $value, $exptime ); // set the new value
 154                 }
 155
 156                 if ( !$this->unlock( $key ) ) {
 157                         // this should never happen
 158                         trigger_error( "Could not release lock for key '$key'." );
 159                 }
 160
 161                 return $success;
 162         }
 163
 164         /**
 165          * @param $key string
 166          * @param $timeout integer [optional]
 167          * @return bool success
 168          */
 169         public function lock( $key, $timeout = 60 ) {
 170                 $timestamp = microtime( true ); // starting UNIX timestamp
 171                 if ( $this->add( "{$key}:lock", $timeout ) ) {
 172                         return true;
 173                 }
 174
 175                 $uRTT  = ceil( 1e6 * ( microtime( true ) - $timestamp ) ); // estimate RTT (us)
 176                 $sleep = 2*$uRTT; // rough time to do get()+set()
 177
 178                 $locked   = false; // lock acquired
 179                 $attempts = 0; // failed attempts
 180                 do {
 181                         if ( ++$attempts >= 3 && $sleep <= 1e6 ) {
 182                                 // Exponentially back off after failed attempts to avoid network spam.
 183                                 // About 2*$uRTT*(2^n-1) us of "sleep" happen for the next n attempts.
 184                                 $sleep *= 2;
 185                         }
 186                         usleep( $sleep ); // back off
 187                         $locked = $this->add( "{$key}:lock", $timeout );
 188                 } while( !$locked );
 189
 190                 return $locked;
 191         }
 192
 193         /**
 194          * @param $key string
 195          * @return bool success
 196          */
 197         public function unlock( $key ) {
 198                 return $this->delete( "{$key}:lock" );
 199         }
 200
 201         /**
 202          * @todo: what is this?
 203          * @return Array
 204          */
 205         public function keys() {
 206                 /* stub */
 207                 return array();
 208         }
 209
 210         /**
 211          * Delete all objects expiring before a certain date.
 212          * @param $date string The reference date in MW format
 213          * @param $progressCallback callback|bool Optional, a function which will be called
 214          *     regularly during long-running operations with the percentage progress
 215          *     as the first parameter.
 216          *
 217          * @return bool on success, false if unimplemented
 218          */
 219         public function deleteObjectsExpiringBefore( $date, $progressCallback = false ) {
 220                 // stub
 221                 return false;
 222         }
 223
 224         /* *** Emulated functions *** */
 225
 226         /**
 227          * Get an associative array containing the item for each of the keys that have items.
 228          * @param $keys Array List of strings
 229          * @return Array
 230          */
 231         public function getMulti( array $keys ) {
 232                 $res = array();
 233                 foreach ( $keys as $key ) {
 234                         $val = $this->get( $key );
 235                         if ( $val !== false ) {
 236                                 $res[$key] = $val;
 237                         }
 238                 }
 239                 return $res;
 240         }
 241
 242         /**
 243          * @param $key string
 244          * @param $value mixed
 245          * @param $exptime integer
 246          * @return bool success
 247          */
 248         public function add( $key, $value, $exptime = 0 ) {
 249                 if ( $this->get( $key ) === false ) {
 250                         return $this->set( $key, $value, $exptime );
 251                 }
 252                 return false; // key already set
 253         }
 254
 255         /**
 256          * @param $key string
 257          * @param $value mixed
 258          * @param $exptime int
 259          * @return bool success
 260          */
 261         public function replace( $key, $value, $exptime = 0 ) {
 262                 if ( $this->get( $key ) !== false ) {
 263                         return $this->set( $key, $value, $exptime );
 264                 }
 265                 return false; // key not already set
 266         }
 267
 268         /**
 269          * Increase stored value of $key by $value while preserving its TTL
 270          * @param $key String: Key to increase
 271          * @param $value Integer: Value to add to $key (Default 1)
 272          * @return integer|bool New value or false on failure
 273          */
 274         public function incr( $key, $value = 1 ) {
 275                 if ( !$this->lock( $key ) ) {
 276                         return false;
 277                 }
 278                 $n = $this->get( $key );
 279                 if ( $this->isInteger( $n ) ) { // key exists?
 280                         $n += intval( $value );
 281                         $this->set( $key, max( 0, $n ) ); // exptime?
 282                 } else {
 283                         $n = false;
 284                 }
 285                 $this->unlock( $key );
 286
 287                 return $n;
 288         }
 289
 290         /**
 291          * Decrease stored value of $key by $value while preserving its TTL
 292          * @param $key String
 293          * @param $value Integer
 294          * @return integer
 295          */
 296         public function decr( $key, $value = 1 ) {
 297                 return $this->incr( $key, - $value );
 298         }
 299
 300         /**
 301          * @param $text string
 302          */
 303         public function debug( $text ) {
 304                 if ( $this->debugMode ) {
 305                         $class = get_class( $this );
 306                         wfDebug( "$class debug: $text\n" );
 307                 }
 308         }
 309
 310         /**
 311          * Convert an optionally relative time to an absolute time
 312          * @param $exptime integer
 313          * @return int
 314          */
 315         protected function convertExpiry( $exptime ) {
 316                 if ( ( $exptime != 0 ) && ( $exptime < 86400 * 3650 /* 10 years */ ) ) {
 317                         return time() + $exptime;
 318                 } else {
 319                         return $exptime;
 320                 }
 321         }
 322
 323         /**
 324          * Convert an optionally absolute expiry time to a relative time. If an
 325          * absolute time is specified which is in the past, use a short expiry time.
 326          *
 327          * @param $exptime integer
 328          * @return integer
 329          */
 330         protected function convertToRelative( $exptime ) {
 331                 if ( $exptime >= 86400 * 3650 /* 10 years */ ) {
 332                         $exptime -= time();
 333                         if ( $exptime <= 0 ) {
 334                                 $exptime = 1;
 335                         }
 336                         return $exptime;
 337                 } else {
 338                         return $exptime;
 339                 }
 340         }
 341
 342         /**
 343          * Check if a value is an integer
 344          *
 345          * @param $value mixed
 346          * @return bool
 347          */
 348         protected function isInteger( $value ) {
 349                 return ( is_int( $value ) || ctype_digit( $value ) );
 350         }
 351 }