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 use MediaWiki\MediaWikiServices;
  24
  25 /**
  26  * This class stores an arbitrary value along with its dependencies.
  27  * Users should typically only use DependencyWrapper::getValueFromCache(),
  28  * rather than instantiating one of these objects directly.
  29  * @ingroup Cache
  30  */
  31 class DependencyWrapper {
  32         private $value;
  33         /** @var CacheDependency[] */
  34         private $deps;
  35
  36         /**
  37          * Create an instance.
  38          * @param mixed $value The user-supplied value
  39          * @param CacheDependency|CacheDependency[] $deps A dependency or dependency
  40          *   array. All dependencies must be objects implementing CacheDependency.
  41          */
  42         function __construct( $value = false, $deps = [] ) {
  43                 $this->value = $value;
  44
  45                 if ( !is_array( $deps ) ) {
  46                         $deps = [ $deps ];
  47                 }
  48
  49                 $this->deps = $deps;
  50         }
  51
  52         /**
  53          * Returns true if any of the dependencies have expired
  54          *
  55          * @return bool
  56          */
  57         function isExpired() {
  58                 foreach ( $this->deps as $dep ) {
  59                         if ( $dep->isExpired() ) {
  60                                 return true;
  61                         }
  62                 }
  63
  64                 return false;
  65         }
  66
  67         /**
  68          * Initialise dependency values in preparation for storing. This must be
  69          * called before serialization.
  70          */
  71         function initialiseDeps() {
  72                 foreach ( $this->deps as $dep ) {
  73                         $dep->loadDependencyValues();
  74                 }
  75         }
  76
  77         /**
  78          * Get the user-defined value
  79          * @return bool|mixed
  80          */
  81         function getValue() {
  82                 return $this->value;
  83         }
  84
  85         /**
  86          * Store the wrapper to a cache
  87          *
  88          * @param BagOStuff $cache
  89          * @param string $key
  90          * @param int $expiry
  91          */
  92         function storeToCache( $cache, $key, $expiry = 0 ) {
  93                 $this->initialiseDeps();
  94                 $cache->set( $key, $this, $expiry );
  95         }
  96
  97         /**
  98          * Attempt to get a value from the cache. If the value is expired or missing,
  99          * it will be generated with the callback function (if present), and the newly
 100          * calculated value will be stored to the cache in a wrapper.
 101          *
 102          * @param BagOStuff $cache A cache object
 103          * @param string $key The cache key
 104          * @param int $expiry The expiry timestamp or interval in seconds
 105          * @param bool|callable $callback The callback for generating the value, or false
 106          * @param array $callbackParams The function parameters for the callback
 107          * @param array $deps The dependencies to store on a cache miss. Note: these
 108          *    are not the dependencies used on a cache hit! Cache hits use the stored
 109          *    dependency array.
 110          *
 111          * @return mixed The value, or null if it was not present in the cache and no
 112          *    callback was defined.
 113          */
 114         static function getValueFromCache( $cache, $key, $expiry = 0, $callback = false,
 115                 $callbackParams = [], $deps = []
 116         ) {
 117                 $obj = $cache->get( $key );
 118
 119                 if ( is_object( $obj ) && $obj instanceof DependencyWrapper && !$obj->isExpired() ) {
 120                         $value = $obj->value;
 121                 } elseif ( $callback ) {
 122                         $value = call_user_func_array( $callback, $callbackParams );
 123                         # Cache the newly-generated value
 124                         $wrapper = new DependencyWrapper( $value, $deps );
 125                         $wrapper->storeToCache( $cache, $key, $expiry );
 126                 } else {
 127                         $value = null;
 128                 }
 129
 130                 return $value;
 131         }
 132 }
 133
 134 /**
 135  * @ingroup Cache
 136  */
 137 abstract class CacheDependency {
 138         /**
 139          * Returns true if the dependency is expired, false otherwise
 140          */
 141         abstract function isExpired();
 142
 143         /**
 144          * Hook to perform any expensive pre-serialize loading of dependency values.
 145          */
 146         function loadDependencyValues() {
 147         }
 148 }
 149
 150 /**
 151  * @ingroup Cache
 152  */
 153 class FileDependency extends CacheDependency {
 154         private $filename;
 155         private $timestamp;
 156
 157         /**
 158          * Create a file dependency
 159          *
 160          * @param string $filename The name of the file, preferably fully qualified
 161          * @param null|bool|int $timestamp The unix last modified timestamp, or false if the
 162          *        file does not exist. If omitted, the timestamp will be loaded from
 163          *        the file.
 164          *
 165          * A dependency on a nonexistent file will be triggered when the file is
 166          * created. A dependency on an existing file will be triggered when the
 167          * file is changed.
 168          */
 169         function __construct( $filename, $timestamp = null ) {
 170                 $this->filename = $filename;
 171                 $this->timestamp = $timestamp;
 172         }
 173
 174         /**
 175          * @return array
 176          */
 177         function __sleep() {
 178                 $this->loadDependencyValues();
 179
 180                 return [ 'filename', 'timestamp' ];
 181         }
 182
 183         function loadDependencyValues() {
 184                 if ( is_null( $this->timestamp ) ) {
 185                         MediaWiki\suppressWarnings();
 186                         # Dependency on a non-existent file stores "false"
 187                         # This is a valid concept!
 188                         $this->timestamp = filemtime( $this->filename );
 189                         MediaWiki\restoreWarnings();
 190                 }
 191         }
 192
 193         /**
 194          * @return bool
 195          */
 196         function isExpired() {
 197                 MediaWiki\suppressWarnings();
 198                 $lastmod = filemtime( $this->filename );
 199                 MediaWiki\restoreWarnings();
 200                 if ( $lastmod === false ) {
 201                         if ( $this->timestamp === false ) {
 202                                 # Still nonexistent
 203                                 return false;
 204                         } else {
 205                                 # Deleted
 206                                 wfDebug( "Dependency triggered: {$this->filename} deleted.\n" );
 207
 208                                 return true;
 209                         }
 210                 } else {
 211                         if ( $lastmod > $this->timestamp ) {
 212                                 # Modified or created
 213                                 wfDebug( "Dependency triggered: {$this->filename} changed.\n" );
 214
 215                                 return true;
 216                         } else {
 217                                 # Not modified
 218                                 return false;
 219                         }
 220                 }
 221         }
 222 }
 223
 224 /**
 225  * @ingroup Cache
 226  */
 227 class GlobalDependency extends CacheDependency {
 228         private $name;
 229         private $value;
 230
 231         function __construct( $name ) {
 232                 $this->name = $name;
 233                 $this->value = $GLOBALS[$name];
 234         }
 235
 236         /**
 237          * @return bool
 238          */
 239         function isExpired() {
 240                 if ( !isset( $GLOBALS[$this->name] ) ) {
 241                         return true;
 242                 }
 243
 244                 return $GLOBALS[$this->name] != $this->value;
 245         }
 246 }
 247
 248 /**
 249  * @ingroup Cache
 250  */
 251 class MainConfigDependency extends CacheDependency {
 252         private $name;
 253         private $value;
 254
 255         function __construct( $name ) {
 256                 $this->name = $name;
 257                 $this->value = $this->getConfig()->get( $this->name );
 258         }
 259
 260         private function getConfig() {
 261                 return MediaWikiServices::getInstance()->getMainConfig();
 262         }
 263
 264         /**
 265          * @return bool
 266          */
 267         function isExpired() {
 268                 if ( !$this->getConfig()->has( $this->name ) ) {
 269                         return true;
 270                 }
 271
 272                 return $this->getConfig()->get( $this->name ) != $this->value;
 273         }
 274 }
 275
 276 /**
 277  * @ingroup Cache
 278  */
 279 class ConstantDependency extends CacheDependency {
 280         private $name;
 281         private $value;
 282
 283         function __construct( $name ) {
 284                 $this->name = $name;
 285                 $this->value = constant( $name );
 286         }
 287
 288         /**
 289          * @return bool
 290          */
 291         function isExpired() {
 292                 return constant( $this->name ) != $this->value;
 293         }
 294 }