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 GlobalDependency extends CacheDependency {
 226         private $name;
 227         private $value;
 228
 229         function __construct( $name ) {
 230                 $this->name = $name;
 231                 $this->value = $GLOBALS[$name];
 232         }
 233
 234         /**
 235          * @return bool
 236          */
 237         function isExpired() {
 238                 if ( !isset( $GLOBALS[$this->name] ) ) {
 239                         return true;
 240                 }
 241
 242                 return $GLOBALS[$this->name] != $this->value;
 243         }
 244 }
 245
 246 /**
 247  * @ingroup Cache
 248  */
 249 class ConstantDependency extends CacheDependency {
 250         private $name;
 251         private $value;
 252
 253         function __construct( $name ) {
 254                 $this->name = $name;
 255                 $this->value = constant( $name );
 256         }
 257
 258         /**
 259          * @return bool
 260          */
 261         function isExpired() {
 262                 return constant( $this->name ) != $this->value;
 263         }
 264 }