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