3 * Data caching with dependencies.
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.
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.
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
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.
30 class DependencyWrapper
{
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.
40 function __construct( $value = false, $deps = array() ) {
41 $this->value
= $value;
43 if ( !is_array( $deps ) ) {
44 $deps = array( $deps );
51 * Returns true if any of the dependencies have expired
55 function isExpired() {
56 foreach ( $this->deps
as $dep ) {
57 if ( $dep->isExpired() ) {
66 * Initialise dependency values in preparation for storing. This must be
67 * called before serialization.
69 function initialiseDeps() {
70 foreach ( $this->deps
as $dep ) {
71 $dep->loadDependencyValues();
76 * Get the user-defined value
84 * Store the wrapper to a cache
86 * @param $cache BagOStuff
90 function storeToCache( $cache, $key, $expiry = 0 ) {
91 $this->initialiseDeps();
92 $cache->set( $key, $this, $expiry );
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.
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
109 * @return mixed The value, or null if it was not present in the cache and no
110 * callback was defined.
112 static function getValueFromCache( $cache, $key, $expiry = 0, $callback = false,
113 $callbackParams = array(), $deps = array()
115 $obj = $cache->get( $key );
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 );
135 abstract class CacheDependency
{
137 * Returns true if the dependency is expired, false otherwise
139 abstract function isExpired();
142 * Hook to perform any expensive pre-serialize loading of dependency values.
144 function loadDependencyValues() {
151 class FileDependency
extends CacheDependency
{
152 var $filename, $timestamp;
155 * Create a file dependency
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
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
166 function __construct( $filename, $timestamp = null ) {
167 $this->filename
= $filename;
168 $this->timestamp
= $timestamp;
175 $this->loadDependencyValues();
177 return array( 'filename', 'timestamp' );
180 function loadDependencyValues() {
181 if ( is_null( $this->timestamp
) ) {
182 if ( !file_exists( $this->filename
) ) {
183 # Dependency on a non-existent file
184 # This is a valid concept!
185 $this->timestamp
= false;
187 $this->timestamp
= filemtime( $this->filename
);
195 function isExpired() {
196 if ( !file_exists( $this->filename
) ) {
197 if ( $this->timestamp
=== false ) {
202 wfDebug( "Dependency triggered: {$this->filename} deleted.\n" );
207 $lastmod = filemtime( $this->filename
);
208 if ( $lastmod > $this->timestamp
) {
209 # Modified or created
210 wfDebug( "Dependency triggered: {$this->filename} changed.\n" );
224 class TitleDependency
extends CacheDependency
{
230 * Construct a title dependency
231 * @param $title Title
233 function __construct( Title
$title ) {
234 $this->titleObj
= $title;
235 $this->ns
= $title->getNamespace();
236 $this->dbk
= $title->getDBkey();
239 function loadDependencyValues() {
240 $this->touched
= $this->getTitle()->getTouched();
244 * Get rid of bulky Title object for sleep
249 return array( 'ns', 'dbk', 'touched' );
255 function getTitle() {
256 if ( !isset( $this->titleObj
) ) {
257 $this->titleObj
= Title
::makeTitle( $this->ns
, $this->dbk
);
260 return $this->titleObj
;
266 function isExpired() {
267 $touched = $this->getTitle()->getTouched();
269 if ( $this->touched
=== false ) {
270 if ( $touched === false ) {
277 } elseif ( $touched === false ) {
280 } elseif ( $touched > $this->touched
) {
293 class TitleListDependency
extends CacheDependency
{
298 * Construct a dependency on a list of titles
299 * @param $linkBatch LinkBatch
301 function __construct( LinkBatch
$linkBatch ) {
302 $this->linkBatch
= $linkBatch;
308 function calculateTimestamps() {
309 # Initialise values to false
310 $timestamps = array();
312 foreach ( $this->getLinkBatch()->data
as $ns => $dbks ) {
313 if ( count( $dbks ) > 0 ) {
314 $timestamps[$ns] = array();
316 foreach ( $dbks as $dbk => $value ) {
317 $timestamps[$ns][$dbk] = false;
323 if ( count( $timestamps ) ) {
324 $dbr = wfGetDB( DB_SLAVE
);
325 $where = $this->getLinkBatch()->constructSet( 'page', $dbr );
328 array( 'page_namespace', 'page_title', 'page_touched' ),
333 foreach ( $res as $row ) {
334 $timestamps[$row->page_namespace
][$row->page_title
] = $row->page_touched
;
341 function loadDependencyValues() {
342 $this->timestamps
= $this->calculateTimestamps();
349 return array( 'timestamps' );
355 function getLinkBatch() {
356 if ( !isset( $this->linkBatch
) ) {
357 $this->linkBatch
= new LinkBatch
;
358 $this->linkBatch
->setArray( $this->timestamps
);
361 return $this->linkBatch
;
367 function isExpired() {
368 $newTimestamps = $this->calculateTimestamps();
370 foreach ( $this->timestamps
as $ns => $dbks ) {
371 foreach ( $dbks as $dbk => $oldTimestamp ) {
372 $newTimestamp = $newTimestamps[$ns][$dbk];
374 if ( $oldTimestamp === false ) {
375 if ( $newTimestamp === false ) {
381 } elseif ( $newTimestamp === false ) {
384 } elseif ( $newTimestamp > $oldTimestamp ) {
400 class GlobalDependency
extends CacheDependency
{
403 function __construct( $name ) {
405 $this->value
= $GLOBALS[$name];
411 function isExpired() {
412 if ( !isset( $GLOBALS[$this->name
] ) ) {
416 return $GLOBALS[$this->name
] != $this->value
;
423 class ConstantDependency
extends CacheDependency
{
426 function __construct( $name ) {
428 $this->value
= constant( $name );
434 function isExpired() {
435 return constant( $this->name
) != $this->value
;