includes/cache/CacheDependency.php

   1 <?php
   2 /**
   3  * Data caching with dependencies.
   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 /**
  25  * This class stores an arbitrary value along with its dependencies.
  26  * Users should typically only use DependencyWrapper::getValueFromCache(),
  27  * rather than instantiating one of these objects directly.
  28  * @ingroup Cache
  29  */
  30 class DependencyWrapper {
  31         private $value;
  32         private $deps;
  33
  34         /**
  35          * Create an instance.
  36          * @param $value Mixed: the user-supplied value
  37          * @param $deps Mixed: a dependency or dependency array. All dependencies
  38          *        must be objects implementing CacheDependency.
  39          */
  40         function __construct( $value = false, $deps = array() ) {
  41                 $this->value = $value;
  42
  43                 if ( !is_array( $deps ) ) {
  44                         $deps = array( $deps );
  45                 }
  46
  47                 $this->deps = $deps;
  48         }
  49
  50         /**
  51          * Returns true if any of the dependencies have expired
  52          *
  53          * @return bool
  54          */
  55         function isExpired() {
  56                 foreach ( $this->deps as $dep ) {
  57                         if ( $dep->isExpired() ) {
  58                                 return true;
  59                         }
  60                 }
  61
  62                 return false;
  63         }
  64
  65         /**
  66          * Initialise dependency values in preparation for storing. This must be
  67          * called before serialization.
  68          */
  69         function initialiseDeps() {
  70                 foreach ( $this->deps as $dep ) {
  71                         $dep->loadDependencyValues();
  72                 }
  73         }
  74
  75         /**
  76          * Get the user-defined value
  77          * @return bool|Mixed
  78          */
  79         function getValue() {
  80                 return $this->value;
  81         }
  82
  83         /**
  84          * Store the wrapper to a cache
  85          *
  86          * @param $cache BagOStuff
  87          * @param $key
  88          * @param $expiry
  89          */
  90         function storeToCache( $cache, $key, $expiry = 0 ) {
  91                 $this->initialiseDeps();
  92                 $cache->set( $key, $this, $expiry );
  93         }
  94
  95         /**
  96          * Attempt to get a value from the cache. If the value is expired or missing,
  97          * it will be generated with the callback function (if present), and the newly
  98          * calculated value will be stored to the cache in a wrapper.
  99          *
 100          * @param $cache BagOStuff a cache object such as $wgMemc
 101          * @param string $key the cache key
 102          * @param $expiry Integer: the expiry timestamp or interval in seconds
 103          * @param $callback Mixed: the callback for generating the value, or false
 104          * @param array $callbackParams the function parameters for the callback
 105          * @param array $deps the dependencies to store on a cache miss. Note: these
 106          *    are not the dependencies used on a cache hit! Cache hits use the stored
 107          *    dependency array.
 108          *
 109          * @return mixed The value, or null if it was not present in the cache and no
 110          *    callback was defined.
 111          */
 112         static function getValueFromCache( $cache, $key, $expiry = 0, $callback = false,
 113                 $callbackParams = array(), $deps = array()
 114         ) {
 115                 $obj = $cache->get( $key );
 116
 117                 if ( is_object( $obj ) && $obj instanceof DependencyWrapper && !$obj->isExpired() ) {
 118                         $value = $obj->value;
 119                 } elseif ( $callback ) {
 120                         $value = call_user_func_array( $callback, $callbackParams );
 121                         # Cache the newly-generated value
 122                         $wrapper = new DependencyWrapper( $value, $deps );
 123                         $wrapper->storeToCache( $cache, $key, $expiry );
 124                 } else {
 125                         $value = null;
 126                 }
 127
 128                 return $value;
 129         }
 130 }
 131
 132 /**
 133  * @ingroup Cache
 134  */
 135 abstract class CacheDependency {
 136         /**
 137          * Returns true if the dependency is expired, false otherwise
 138          */
 139         abstract function isExpired();
 140
 141         /**
 142          * Hook to perform any expensive pre-serialize loading of dependency values.
 143          */
 144         function loadDependencyValues() {
 145         }
 146 }
 147
 148 /**
 149  * @ingroup Cache
 150  */
 151 class FileDependency extends CacheDependency {
 152         private $filename;
 153         private $timestamp;
 154
 155         /**
 156          * Create a file dependency
 157          *
 158          * @param string $filename the name of the file, preferably fully qualified
 159          * @param $timestamp Mixed: the unix last modified timestamp, or false if the
 160          *        file does not exist. If omitted, the timestamp will be loaded from
 161          *        the file.
 162          *
 163          * A dependency on a nonexistent file will be triggered when the file is
 164          * created. A dependency on an existing file will be triggered when the
 165          * file is changed.
 166          */
 167         function __construct( $filename, $timestamp = null ) {
 168                 $this->filename = $filename;
 169                 $this->timestamp = $timestamp;
 170         }
 171
 172         /**
 173          * @return array
 174          */
 175         function __sleep() {
 176                 $this->loadDependencyValues();
 177
 178                 return array( 'filename', 'timestamp' );
 179         }
 180
 181         function loadDependencyValues() {
 182                 if ( is_null( $this->timestamp ) ) {
 183                         if ( !file_exists( $this->filename ) ) {
 184                                 # Dependency on a non-existent file
 185                                 # This is a valid concept!
 186                                 $this->timestamp = false;
 187                         } else {
 188                                 $this->timestamp = filemtime( $this->filename );
 189                         }
 190                 }
 191         }
 192
 193         /**
 194          * @return bool
 195          */
 196         function isExpired() {
 197                 if ( !file_exists( $this->filename ) ) {
 198                         if ( $this->timestamp === false ) {
 199                                 # Still nonexistent
 200                                 return false;
 201                         } else {
 202                                 # Deleted
 203                                 wfDebug( "Dependency triggered: {$this->filename} deleted.\n" );
 204
 205                                 return true;
 206                         }
 207                 } else {
 208                         $lastmod = filemtime( $this->filename );
 209                         if ( $lastmod > $this->timestamp ) {
 210                                 # Modified or created
 211                                 wfDebug( "Dependency triggered: {$this->filename} changed.\n" );
 212
 213                                 return true;
 214                         } else {
 215                                 # Not modified
 216                                 return false;
 217                         }
 218                 }
 219         }
 220 }
 221
 222 /**
 223  * @ingroup Cache
 224  */
 225 class TitleDependency extends CacheDependency {
 226         private $titleObj;
 227         private $ns;
 228         private $dbk;
 229         private $touched;
 230
 231         /**
 232          * Construct a title dependency
 233          * @param $title Title
 234          */
 235         function __construct( Title $title ) {
 236                 $this->titleObj = $title;
 237                 $this->ns = $title->getNamespace();
 238                 $this->dbk = $title->getDBkey();
 239         }
 240
 241         function loadDependencyValues() {
 242                 $this->touched = $this->getTitle()->getTouched();
 243         }
 244
 245         /**
 246          * Get rid of bulky Title object for sleep
 247          *
 248          * @return array
 249          */
 250         function __sleep() {
 251                 return array( 'ns', 'dbk', 'touched' );
 252         }
 253
 254         /**
 255          * @return Title
 256          */
 257         function getTitle() {
 258                 if ( !isset( $this->titleObj ) ) {
 259                         $this->titleObj = Title::makeTitle( $this->ns, $this->dbk );
 260                 }
 261
 262                 return $this->titleObj;
 263         }
 264
 265         /**
 266          * @return bool
 267          */
 268         function isExpired() {
 269                 $touched = $this->getTitle()->getTouched();
 270
 271                 if ( $this->touched === false ) {
 272                         if ( $touched === false ) {
 273                                 # Still missing
 274                                 return false;
 275                         } else {
 276                                 # Created
 277                                 return true;
 278                         }
 279                 } elseif ( $touched === false ) {
 280                         # Deleted
 281                         return true;
 282                 } elseif ( $touched > $this->touched ) {
 283                         # Updated
 284                         return true;
 285                 } else {
 286                         # Unmodified
 287                         return false;
 288                 }
 289         }
 290 }
 291
 292 /**
 293  * @ingroup Cache
 294  */
 295 class TitleListDependency extends CacheDependency {
 296         private $linkBatch;
 297         private $timestamps;
 298
 299         /**
 300          * Construct a dependency on a list of titles
 301          * @param $linkBatch LinkBatch
 302          */
 303         function __construct( LinkBatch $linkBatch ) {
 304                 $this->linkBatch = $linkBatch;
 305         }
 306
 307         /**
 308          * @return array
 309          */
 310         function calculateTimestamps() {
 311                 # Initialise values to false
 312                 $timestamps = array();
 313
 314                 foreach ( $this->getLinkBatch()->data as $ns => $dbks ) {
 315                         if ( count( $dbks ) > 0 ) {
 316                                 $timestamps[$ns] = array();
 317
 318                                 foreach ( $dbks as $dbk => $value ) {
 319                                         $timestamps[$ns][$dbk] = false;
 320                                 }
 321                         }
 322                 }
 323
 324                 # Do the query
 325                 if ( count( $timestamps ) ) {
 326                         $dbr = wfGetDB( DB_SLAVE );
 327                         $where = $this->getLinkBatch()->constructSet( 'page', $dbr );
 328                         $res = $dbr->select(
 329                                 'page',
 330                                 array( 'page_namespace', 'page_title', 'page_touched' ),
 331                                 $where,
 332                                 __METHOD__
 333                         );
 334
 335                         foreach ( $res as $row ) {
 336                                 $timestamps[$row->page_namespace][$row->page_title] = $row->page_touched;
 337                         }
 338                 }
 339
 340                 return $timestamps;
 341         }
 342
 343         function loadDependencyValues() {
 344                 $this->timestamps = $this->calculateTimestamps();
 345         }
 346
 347         /**
 348          * @return array
 349          */
 350         function __sleep() {
 351                 return array( 'timestamps' );
 352         }
 353
 354         /**
 355          * @return LinkBatch
 356          */
 357         function getLinkBatch() {
 358                 if ( !isset( $this->linkBatch ) ) {
 359                         $this->linkBatch = new LinkBatch;
 360                         $this->linkBatch->setArray( $this->timestamps );
 361                 }
 362
 363                 return $this->linkBatch;
 364         }
 365
 366         /**
 367          * @return bool
 368          */
 369         function isExpired() {
 370                 $newTimestamps = $this->calculateTimestamps();
 371
 372                 foreach ( $this->timestamps as $ns => $dbks ) {
 373                         foreach ( $dbks as $dbk => $oldTimestamp ) {
 374                                 $newTimestamp = $newTimestamps[$ns][$dbk];
 375
 376                                 if ( $oldTimestamp === false ) {
 377                                         if ( $newTimestamp === false ) {
 378                                                 # Still missing
 379                                         } else {
 380                                                 # Created
 381                                                 return true;
 382                                         }
 383                                 } elseif ( $newTimestamp === false ) {
 384                                         # Deleted
 385                                         return true;
 386                                 } elseif ( $newTimestamp > $oldTimestamp ) {
 387                                         # Updated
 388                                         return true;
 389                                 } else {
 390                                         # Unmodified
 391                                 }
 392                         }
 393                 }
 394
 395                 return false;
 396         }
 397 }
 398
 399 /**
 400  * @ingroup Cache
 401  */
 402 class GlobalDependency extends CacheDependency {
 403         private $name;
 404         private $value;
 405
 406         function __construct( $name ) {
 407                 $this->name = $name;
 408                 $this->value = $GLOBALS[$name];
 409         }
 410
 411         /**
 412          * @return bool
 413          */
 414         function isExpired() {
 415                 if ( !isset( $GLOBALS[$this->name] ) ) {
 416                         return true;
 417                 }
 418
 419                 return $GLOBALS[$this->name] != $this->value;
 420         }
 421 }
 422
 423 /**
 424  * @ingroup Cache
 425  */
 426 class ConstantDependency extends CacheDependency {
 427         private $name;
 428         private $value;
 429
 430         function __construct( $name ) {
 431                 $this->name = $name;
 432                 $this->value = constant( $name );
 433         }
 434
 435         /**
 436          * @return bool
 437          */
 438         function isExpired() {
 439                 return constant( $this->name ) != $this->value;
 440         }
 441 }