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         var $filename, $timestamp;
 153
 154         /**
 155          * Create a file dependency
 156          *
 157          * @param string $filename the name of the file, preferably fully qualified
 158          * @param $timestamp Mixed: the unix last modified timestamp, or false if the
 159          *        file does not exist. If omitted, the timestamp will be loaded from
 160          *        the file.
 161          *
 162          * A dependency on a nonexistent file will be triggered when the file is
 163          * created. A dependency on an existing file will be triggered when the
 164          * file is changed.
 165          */
 166         function __construct( $filename, $timestamp = null ) {
 167                 $this->filename = $filename;
 168                 $this->timestamp = $timestamp;
 169         }
 170
 171         /**
 172          * @return array
 173          */
 174         function __sleep() {
 175                 $this->loadDependencyValues();
 176
 177                 return array( 'filename', 'timestamp' );
 178         }
 179
 180         function loadDependencyValues() {
 181                 if ( is_null( $this->timestamp ) ) {
 182                         if ( !file_exists( $this->filename ) ) {
 183                                 # Dependency on a non-existent file
 184                                 # This is a valid concept!
 185                                 $this->timestamp = false;
 186                         } else {
 187                                 $this->timestamp = filemtime( $this->filename );
 188                         }
 189                 }
 190         }
 191
 192         /**
 193          * @return bool
 194          */
 195         function isExpired() {
 196                 if ( !file_exists( $this->filename ) ) {
 197                         if ( $this->timestamp === false ) {
 198                                 # Still nonexistent
 199                                 return false;
 200                         } else {
 201                                 # Deleted
 202                                 wfDebug( "Dependency triggered: {$this->filename} deleted.\n" );
 203
 204                                 return true;
 205                         }
 206                 } else {
 207                         $lastmod = filemtime( $this->filename );
 208                         if ( $lastmod > $this->timestamp ) {
 209                                 # Modified or created
 210                                 wfDebug( "Dependency triggered: {$this->filename} changed.\n" );
 211
 212                                 return true;
 213                         } else {
 214                                 # Not modified
 215                                 return false;
 216                         }
 217                 }
 218         }
 219 }
 220
 221 /**
 222  * @ingroup Cache
 223  */
 224 class TitleDependency extends CacheDependency {
 225         var $titleObj;
 226         var $ns, $dbk;
 227         var $touched;
 228
 229         /**
 230          * Construct a title dependency
 231          * @param $title Title
 232          */
 233         function __construct( Title $title ) {
 234                 $this->titleObj = $title;
 235                 $this->ns = $title->getNamespace();
 236                 $this->dbk = $title->getDBkey();
 237         }
 238
 239         function loadDependencyValues() {
 240                 $this->touched = $this->getTitle()->getTouched();
 241         }
 242
 243         /**
 244          * Get rid of bulky Title object for sleep
 245          *
 246          * @return array
 247          */
 248         function __sleep() {
 249                 return array( 'ns', 'dbk', 'touched' );
 250         }
 251
 252         /**
 253          * @return Title
 254          */
 255         function getTitle() {
 256                 if ( !isset( $this->titleObj ) ) {
 257                         $this->titleObj = Title::makeTitle( $this->ns, $this->dbk );
 258                 }
 259
 260                 return $this->titleObj;
 261         }
 262
 263         /**
 264          * @return bool
 265          */
 266         function isExpired() {
 267                 $touched = $this->getTitle()->getTouched();
 268
 269                 if ( $this->touched === false ) {
 270                         if ( $touched === false ) {
 271                                 # Still missing
 272                                 return false;
 273                         } else {
 274                                 # Created
 275                                 return true;
 276                         }
 277                 } elseif ( $touched === false ) {
 278                         # Deleted
 279                         return true;
 280                 } elseif ( $touched > $this->touched ) {
 281                         # Updated
 282                         return true;
 283                 } else {
 284                         # Unmodified
 285                         return false;
 286                 }
 287         }
 288 }
 289
 290 /**
 291  * @ingroup Cache
 292  */
 293 class TitleListDependency extends CacheDependency {
 294         var $linkBatch;
 295         var $timestamps;
 296
 297         /**
 298          * Construct a dependency on a list of titles
 299          * @param $linkBatch LinkBatch
 300          */
 301         function __construct( LinkBatch $linkBatch ) {
 302                 $this->linkBatch = $linkBatch;
 303         }
 304
 305         /**
 306          * @return array
 307          */
 308         function calculateTimestamps() {
 309                 # Initialise values to false
 310                 $timestamps = array();
 311
 312                 foreach ( $this->getLinkBatch()->data as $ns => $dbks ) {
 313                         if ( count( $dbks ) > 0 ) {
 314                                 $timestamps[$ns] = array();
 315
 316                                 foreach ( $dbks as $dbk => $value ) {
 317                                         $timestamps[$ns][$dbk] = false;
 318                                 }
 319                         }
 320                 }
 321
 322                 # Do the query
 323                 if ( count( $timestamps ) ) {
 324                         $dbr = wfGetDB( DB_SLAVE );
 325                         $where = $this->getLinkBatch()->constructSet( 'page', $dbr );
 326                         $res = $dbr->select(
 327                                 'page',
 328                                 array( 'page_namespace', 'page_title', 'page_touched' ),
 329                                 $where,
 330                                 __METHOD__
 331                         );
 332
 333                         foreach ( $res as $row ) {
 334                                 $timestamps[$row->page_namespace][$row->page_title] = $row->page_touched;
 335                         }
 336                 }
 337
 338                 return $timestamps;
 339         }
 340
 341         function loadDependencyValues() {
 342                 $this->timestamps = $this->calculateTimestamps();
 343         }
 344
 345         /**
 346          * @return array
 347          */
 348         function __sleep() {
 349                 return array( 'timestamps' );
 350         }
 351
 352         /**
 353          * @return LinkBatch
 354          */
 355         function getLinkBatch() {
 356                 if ( !isset( $this->linkBatch ) ) {
 357                         $this->linkBatch = new LinkBatch;
 358                         $this->linkBatch->setArray( $this->timestamps );
 359                 }
 360
 361                 return $this->linkBatch;
 362         }
 363
 364         /**
 365          * @return bool
 366          */
 367         function isExpired() {
 368                 $newTimestamps = $this->calculateTimestamps();
 369
 370                 foreach ( $this->timestamps as $ns => $dbks ) {
 371                         foreach ( $dbks as $dbk => $oldTimestamp ) {
 372                                 $newTimestamp = $newTimestamps[$ns][$dbk];
 373
 374                                 if ( $oldTimestamp === false ) {
 375                                         if ( $newTimestamp === false ) {
 376                                                 # Still missing
 377                                         } else {
 378                                                 # Created
 379                                                 return true;
 380                                         }
 381                                 } elseif ( $newTimestamp === false ) {
 382                                         # Deleted
 383                                         return true;
 384                                 } elseif ( $newTimestamp > $oldTimestamp ) {
 385                                         # Updated
 386                                         return true;
 387                                 } else {
 388                                         # Unmodified
 389                                 }
 390                         }
 391                 }
 392
 393                 return false;
 394         }
 395 }
 396
 397 /**
 398  * @ingroup Cache
 399  */
 400 class GlobalDependency extends CacheDependency {
 401         var $name, $value;
 402
 403         function __construct( $name ) {
 404                 $this->name = $name;
 405                 $this->value = $GLOBALS[$name];
 406         }
 407
 408         /**
 409          * @return bool
 410          */
 411         function isExpired() {
 412                 if ( !isset( $GLOBALS[$this->name] ) ) {
 413                         return true;
 414                 }
 415
 416                 return $GLOBALS[$this->name] != $this->value;
 417         }
 418 }
 419
 420 /**
 421  * @ingroup Cache
 422  */
 423 class ConstantDependency extends CacheDependency {
 424         var $name, $value;
 425
 426         function __construct( $name ) {
 427                 $this->name = $name;
 428                 $this->value = constant( $name );
 429         }
 430
 431         /**
 432          * @return bool
 433          */
 434         function isExpired() {
 435                 return constant( $this->name ) != $this->value;
 436         }
 437 }