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