includes/cache/CacheDependency.php

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