Fix for r47482: put the RELEASE-NOTES entry in the "bug fixes" section and not the...
[mediawiki.git] / includes / BagOStuff.php
blob572dca6c416cbcc2e609f1cbc38f11491dc19cdb
1 <?php
3 # Copyright (C) 2003-2004 Brion Vibber <brion@pobox.com>
4 # http://www.mediawiki.org/
6 # This program is free software; you can redistribute it and/or modify
7 # it under the terms of the GNU General Public License as published by
8 # the Free Software Foundation; either version 2 of the License, or
9 # (at your option) any later version.
11 # This program is distributed in the hope that it will be useful,
12 # but WITHOUT ANY WARRANTY; without even the implied warranty of
13 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14 # GNU General Public License for more details.
16 # You should have received a copy of the GNU General Public License along
17 # with this program; if not, write to the Free Software Foundation, Inc.,
18 # 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
19 # http://www.gnu.org/copyleft/gpl.html
21 /**
22 * @defgroup Cache Cache
24 * @file
25 * @ingroup Cache
28 /**
29 * interface is intended to be more or less compatible with
30 * the PHP memcached client.
32 * backends for local hash array and SQL table included:
33 * <code>
34 * $bag = new HashBagOStuff();
35 * $bag = new MediaWikiBagOStuff($tablename); # connect to db first
36 * </code>
38 * @ingroup Cache
40 class BagOStuff {
41 var $debugmode;
43 function __construct() {
44 $this->set_debug( false );
47 function set_debug($bool) {
48 $this->debugmode = $bool;
51 /* *** THE GUTS OF THE OPERATION *** */
52 /* Override these with functional things in subclasses */
54 function get($key) {
55 /* stub */
56 return false;
59 function set($key, $value, $exptime=0) {
60 /* stub */
61 return false;
64 function delete($key, $time=0) {
65 /* stub */
66 return false;
69 function lock($key, $timeout = 0) {
70 /* stub */
71 return true;
74 function unlock($key) {
75 /* stub */
76 return true;
79 function keys() {
80 /* stub */
81 return array();
84 /* *** Emulated functions *** */
85 /* Better performance can likely be got with custom written versions */
86 function get_multi($keys) {
87 $out = array();
88 foreach($keys as $key)
89 $out[$key] = $this->get($key);
90 return $out;
93 function set_multi($hash, $exptime=0) {
94 foreach($hash as $key => $value)
95 $this->set($key, $value, $exptime);
98 function add($key, $value, $exptime=0) {
99 if( $this->get($key) == false ) {
100 $this->set($key, $value, $exptime);
101 return true;
105 function add_multi($hash, $exptime=0) {
106 foreach($hash as $key => $value)
107 $this->add($key, $value, $exptime);
110 function delete_multi($keys, $time=0) {
111 foreach($keys as $key)
112 $this->delete($key, $time);
115 function replace($key, $value, $exptime=0) {
116 if( $this->get($key) !== false )
117 $this->set($key, $value, $exptime);
120 function incr($key, $value=1) {
121 if ( !$this->lock($key) ) {
122 return false;
124 $value = intval($value);
125 if($value < 0) $value = 0;
127 $n = false;
128 if( ($n = $this->get($key)) !== false ) {
129 $n += $value;
130 $this->set($key, $n); // exptime?
132 $this->unlock($key);
133 return $n;
136 function decr($key, $value=1) {
137 if ( !$this->lock($key) ) {
138 return false;
140 $value = intval($value);
141 if($value < 0) $value = 0;
143 $m = false;
144 if( ($n = $this->get($key)) !== false ) {
145 $m = $n - $value;
146 if($m < 0) $m = 0;
147 $this->set($key, $m); // exptime?
149 $this->unlock($key);
150 return $m;
153 function _debug($text) {
154 if($this->debugmode)
155 wfDebug("BagOStuff debug: $text\n");
159 * Convert an optionally relative time to an absolute time
161 static function convertExpiry( $exptime ) {
162 if(($exptime != 0) && ($exptime < 3600*24*30)) {
163 return time() + $exptime;
164 } else {
165 return $exptime;
172 * Functional versions!
173 * This is a test of the interface, mainly. It stores things in an associative
174 * array, which is not going to persist between program runs.
176 * @ingroup Cache
178 class HashBagOStuff extends BagOStuff {
179 var $bag;
181 function __construct() {
182 $this->bag = array();
185 function _expire($key) {
186 $et = $this->bag[$key][1];
187 if(($et == 0) || ($et > time()))
188 return false;
189 $this->delete($key);
190 return true;
193 function get($key) {
194 if(!$this->bag[$key])
195 return false;
196 if($this->_expire($key))
197 return false;
198 return $this->bag[$key][0];
201 function set($key,$value,$exptime=0) {
202 $this->bag[$key] = array( $value, BagOStuff::convertExpiry( $exptime ) );
205 function delete($key,$time=0) {
206 if(!$this->bag[$key])
207 return false;
208 unset($this->bag[$key]);
209 return true;
212 function keys() {
213 return array_keys( $this->bag );
218 * Generic class to store objects in a database
220 * @ingroup Cache
222 abstract class SqlBagOStuff extends BagOStuff {
223 var $table;
224 var $lastexpireall = 0;
227 * Constructor
229 * @param $tablename String: name of the table to use
231 function __construct($tablename = 'objectcache') {
232 $this->table = $tablename;
235 function get($key) {
236 /* expire old entries if any */
237 $this->garbageCollect();
239 $res = $this->_query(
240 "SELECT value,exptime FROM $0 WHERE keyname='$1'", $key);
241 if(!$res) {
242 $this->_debug("get: ** error: " . $this->_dberror($res) . " **");
243 return false;
245 if($row=$this->_fetchobject($res)) {
246 $this->_debug("get: retrieved data; exp time is " . $row->exptime);
247 if ( $row->exptime != $this->_maxdatetime() &&
248 wfTimestamp( TS_UNIX, $row->exptime ) < time() )
250 $this->_debug("get: key has expired, deleting");
251 $this->delete($key);
252 return false;
254 return $this->_unserialize($this->_blobdecode($row->value));
255 } else {
256 $this->_debug('get: no matching rows');
258 return false;
261 function set($key,$value,$exptime=0) {
262 if ( $this->_readonly() ) {
263 return false;
265 $exptime = intval($exptime);
266 if($exptime < 0) $exptime = 0;
267 if($exptime == 0) {
268 $exp = $this->_maxdatetime();
269 } else {
270 if($exptime < 3.16e8) # ~10 years
271 $exptime += time();
272 $exp = $this->_fromunixtime($exptime);
274 $this->_begin();
275 $this->_query(
276 "DELETE FROM $0 WHERE keyname='$1'", $key );
277 $this->_doinsert($this->getTableName(), array(
278 'keyname' => $key,
279 'value' => $this->_blobencode($this->_serialize($value)),
280 'exptime' => $exp
282 $this->_commit();
283 return true; /* ? */
286 function delete($key,$time=0) {
287 if ( $this->_readonly() ) {
288 return false;
290 $this->_begin();
291 $this->_query(
292 "DELETE FROM $0 WHERE keyname='$1'", $key );
293 $this->_commit();
294 return true; /* ? */
297 function keys() {
298 $res = $this->_query( "SELECT keyname FROM $0" );
299 if(!$res) {
300 $this->_debug("keys: ** error: " . $this->_dberror($res) . " **");
301 return array();
303 $result = array();
304 while( $row = $this->_fetchobject($res) ) {
305 $result[] = $row->keyname;
307 return $result;
310 function getTableName() {
311 return $this->table;
314 function _query($sql) {
315 $reps = func_get_args();
316 $reps[0] = $this->getTableName();
317 // ewwww
318 for($i=0;$i<count($reps);$i++) {
319 $sql = str_replace(
320 '$' . $i,
321 $i > 0 ? $this->_strencode($reps[$i]) : $reps[$i],
322 $sql);
324 $res = $this->_doquery($sql);
325 if($res == false) {
326 $this->_debug('query failed: ' . $this->_dberror($res));
328 return $res;
331 function _strencode($str) {
332 /* Protect strings in SQL */
333 return str_replace( "'", "''", $str );
335 function _blobencode($str) {
336 return $str;
338 function _blobdecode($str) {
339 return $str;
342 abstract function _doinsert($table, $vals);
343 abstract function _doquery($sql);
345 abstract function _readonly();
347 function _begin() {}
348 function _commit() {}
350 function _freeresult($result) {
351 /* stub */
352 return false;
355 function _dberror($result) {
356 /* stub */
357 return 'unknown error';
360 abstract function _maxdatetime();
361 abstract function _fromunixtime($ts);
363 function garbageCollect() {
364 /* Ignore 99% of requests */
365 if ( !mt_rand( 0, 100 ) ) {
366 $nowtime = time();
367 /* Avoid repeating the delete within a few seconds */
368 if ( $nowtime > ($this->lastexpireall + 1) ) {
369 $this->lastexpireall = $nowtime;
370 $this->expireall();
375 function expireall() {
376 /* Remove any items that have expired */
377 if ( $this->_readonly() ) {
378 return false;
380 $now = $this->_fromunixtime( time() );
381 $this->_begin();
382 $this->_query( "DELETE FROM $0 WHERE exptime < '$now'" );
383 $this->_commit();
386 function deleteall() {
387 /* Clear *all* items from cache table */
388 if ( $this->_readonly() ) {
389 return false;
391 $this->_begin();
392 $this->_query( "DELETE FROM $0" );
393 $this->_commit();
397 * Serialize an object and, if possible, compress the representation.
398 * On typical message and page data, this can provide a 3X decrease
399 * in storage requirements.
401 * @param $data mixed
402 * @return string
404 function _serialize( &$data ) {
405 $serial = serialize( $data );
406 if( function_exists( 'gzdeflate' ) ) {
407 return gzdeflate( $serial );
408 } else {
409 return $serial;
414 * Unserialize and, if necessary, decompress an object.
415 * @param $serial string
416 * @return mixed
418 function _unserialize( $serial ) {
419 if( function_exists( 'gzinflate' ) ) {
420 $decomp = @gzinflate( $serial );
421 if( false !== $decomp ) {
422 $serial = $decomp;
425 $ret = unserialize( $serial );
426 return $ret;
431 * Stores objects in the main database of the wiki
433 * @ingroup Cache
435 class MediaWikiBagOStuff extends SqlBagOStuff {
436 var $tableInitialised = false;
437 var $lb, $db;
439 function _getDB(){
440 if ( !isset( $this->lb ) ) {
441 $this->lb = wfGetLBFactory()->newMainLB();
442 $this->db = $this->lb->getConnection( DB_MASTER );
443 $this->db->clearFlag( DBO_TRX );
445 return $this->db;
447 function _begin() {
448 $this->_getDB()->begin();
450 function _commit() {
451 $this->_getDB()->commit();
453 function _doquery($sql) {
454 return $this->_getDB()->query( $sql, __METHOD__ );
456 function _doinsert($t, $v) {
457 return $this->_getDB()->insert($t, $v, __METHOD__, array( 'IGNORE' ) );
459 function _fetchobject($result) {
460 return $this->_getDB()->fetchObject($result);
462 function _freeresult($result) {
463 return $this->_getDB()->freeResult($result);
465 function _dberror($result) {
466 return $this->_getDB()->lastError();
468 function _maxdatetime() {
469 if ( time() > 0x7fffffff ) {
470 return $this->_fromunixtime( 1<<62 );
471 } else {
472 return $this->_fromunixtime( 0x7fffffff );
475 function _fromunixtime($ts) {
476 return $this->_getDB()->timestamp($ts);
478 /***
479 * Note -- this should *not* check wfReadOnly().
480 * Read-only mode has been repurposed from the original
481 * "nothing must write to the database" to "users should not
482 * be able to edit or alter anything user-visible".
484 * Backend bits like the object cache should continue
485 * to work in this mode, otherwise things will blow up
486 * like the message cache failing to save its state,
487 * causing long delays (bug 11533).
489 function _readonly(){
490 return false;
492 function _strencode($s) {
493 return $this->_getDB()->strencode($s);
495 function _blobencode($s) {
496 return $this->_getDB()->encodeBlob($s);
498 function _blobdecode($s) {
499 return $this->_getDB()->decodeBlob($s);
501 function getTableName() {
502 if ( !$this->tableInitialised ) {
503 $dbw = $this->_getDB();
504 /* This is actually a hack, we should be able
505 to use Language classes here... or not */
506 if (!$dbw)
507 throw new MWException("Could not connect to database");
508 $this->table = $dbw->tableName( $this->table );
509 $this->tableInitialised = true;
511 return $this->table;
516 * This is a wrapper for Turck MMCache's shared memory functions.
518 * You can store objects with mmcache_put() and mmcache_get(), but Turck seems
519 * to use a weird custom serializer that randomly segfaults. So we wrap calls
520 * with serialize()/unserialize().
522 * The thing I noticed about the Turck serialized data was that unlike ordinary
523 * serialize(), it contained the names of methods, and judging by the amount of
524 * binary data, perhaps even the bytecode of the methods themselves. It may be
525 * that Turck's serializer is faster, so a possible future extension would be
526 * to use it for arrays but not for objects.
528 * @ingroup Cache
530 class TurckBagOStuff extends BagOStuff {
531 function get($key) {
532 $val = mmcache_get( $key );
533 if ( is_string( $val ) ) {
534 $val = unserialize( $val );
536 return $val;
539 function set($key, $value, $exptime=0) {
540 mmcache_put( $key, serialize( $value ), $exptime );
541 return true;
544 function delete($key, $time=0) {
545 mmcache_rm( $key );
546 return true;
549 function lock($key, $waitTimeout = 0 ) {
550 mmcache_lock( $key );
551 return true;
554 function unlock($key) {
555 mmcache_unlock( $key );
556 return true;
561 * This is a wrapper for APC's shared memory functions
563 * @ingroup Cache
565 class APCBagOStuff extends BagOStuff {
566 function get($key) {
567 $val = apc_fetch($key);
568 if ( is_string( $val ) ) {
569 $val = unserialize( $val );
571 return $val;
574 function set($key, $value, $exptime=0) {
575 apc_store($key, serialize($value), $exptime);
576 return true;
579 function delete($key, $time=0) {
580 apc_delete($key);
581 return true;
587 * This is a wrapper for eAccelerator's shared memory functions.
589 * This is basically identical to the Turck MMCache version,
590 * mostly because eAccelerator is based on Turck MMCache.
592 * @ingroup Cache
594 class eAccelBagOStuff extends BagOStuff {
595 function get($key) {
596 $val = eaccelerator_get( $key );
597 if ( is_string( $val ) ) {
598 $val = unserialize( $val );
600 return $val;
603 function set($key, $value, $exptime=0) {
604 eaccelerator_put( $key, serialize( $value ), $exptime );
605 return true;
608 function delete($key, $time=0) {
609 eaccelerator_rm( $key );
610 return true;
613 function lock($key, $waitTimeout = 0 ) {
614 eaccelerator_lock( $key );
615 return true;
618 function unlock($key) {
619 eaccelerator_unlock( $key );
620 return true;
625 * Wrapper for XCache object caching functions; identical interface
626 * to the APC wrapper
628 * @ingroup Cache
630 class XCacheBagOStuff extends BagOStuff {
633 * Get a value from the XCache object cache
635 * @param $key String: cache key
636 * @return mixed
638 public function get( $key ) {
639 $val = xcache_get( $key );
640 if( is_string( $val ) )
641 $val = unserialize( $val );
642 return $val;
646 * Store a value in the XCache object cache
648 * @param $key String: cache key
649 * @param $value Mixed: object to store
650 * @param $expire Int: expiration time
651 * @return bool
653 public function set( $key, $value, $expire = 0 ) {
654 xcache_set( $key, serialize( $value ), $expire );
655 return true;
659 * Remove a value from the XCache object cache
661 * @param $key String: cache key
662 * @param $time Int: not used in this implementation
663 * @return bool
665 public function delete( $key, $time = 0 ) {
666 xcache_unset( $key );
667 return true;
673 * @todo document
674 * @ingroup Cache
676 class DBABagOStuff extends BagOStuff {
677 var $mHandler, $mFile, $mReader, $mWriter, $mDisabled;
679 function __construct( $handler = 'db3', $dir = false ) {
680 if ( $dir === false ) {
681 global $wgTmpDirectory;
682 $dir = $wgTmpDirectory;
684 $this->mFile = "$dir/mw-cache-" . wfWikiID();
685 $this->mFile .= '.db';
686 wfDebug( __CLASS__.": using cache file {$this->mFile}\n" );
687 $this->mHandler = $handler;
691 * Encode value and expiry for storage
693 function encode( $value, $expiry ) {
694 # Convert to absolute time
695 $expiry = BagOStuff::convertExpiry( $expiry );
696 return sprintf( '%010u', intval( $expiry ) ) . ' ' . serialize( $value );
700 * @return list containing value first and expiry second
702 function decode( $blob ) {
703 if ( !is_string( $blob ) ) {
704 return array( null, 0 );
705 } else {
706 return array(
707 unserialize( substr( $blob, 11 ) ),
708 intval( substr( $blob, 0, 10 ) )
713 function getReader() {
714 if ( file_exists( $this->mFile ) ) {
715 $handle = dba_open( $this->mFile, 'rl', $this->mHandler );
716 } else {
717 $handle = $this->getWriter();
719 if ( !$handle ) {
720 wfDebug( "Unable to open DBA cache file {$this->mFile}\n" );
722 return $handle;
725 function getWriter() {
726 $handle = dba_open( $this->mFile, 'cl', $this->mHandler );
727 if ( !$handle ) {
728 wfDebug( "Unable to open DBA cache file {$this->mFile}\n" );
730 return $handle;
733 function get( $key ) {
734 wfProfileIn( __METHOD__ );
735 wfDebug( __METHOD__."($key)\n" );
736 $handle = $this->getReader();
737 if ( !$handle ) {
738 return null;
740 $val = dba_fetch( $key, $handle );
741 list( $val, $expiry ) = $this->decode( $val );
742 # Must close ASAP because locks are held
743 dba_close( $handle );
745 if ( !is_null( $val ) && $expiry && $expiry < time() ) {
746 # Key is expired, delete it
747 $handle = $this->getWriter();
748 dba_delete( $key, $handle );
749 dba_close( $handle );
750 wfDebug( __METHOD__.": $key expired\n" );
751 $val = null;
753 wfProfileOut( __METHOD__ );
754 return $val;
757 function set( $key, $value, $exptime=0 ) {
758 wfProfileIn( __METHOD__ );
759 wfDebug( __METHOD__."($key)\n" );
760 $blob = $this->encode( $value, $exptime );
761 $handle = $this->getWriter();
762 if ( !$handle ) {
763 return false;
765 $ret = dba_replace( $key, $blob, $handle );
766 dba_close( $handle );
767 wfProfileOut( __METHOD__ );
768 return $ret;
771 function delete( $key, $time = 0 ) {
772 wfProfileIn( __METHOD__ );
773 wfDebug( __METHOD__."($key)\n" );
774 $handle = $this->getWriter();
775 if ( !$handle ) {
776 return false;
778 $ret = dba_delete( $key, $handle );
779 dba_close( $handle );
780 wfProfileOut( __METHOD__ );
781 return $ret;
784 function add( $key, $value, $exptime = 0 ) {
785 wfProfileIn( __METHOD__ );
786 $blob = $this->encode( $value, $exptime );
787 $handle = $this->getWriter();
788 if ( !$handle ) {
789 return false;
791 $ret = dba_insert( $key, $blob, $handle );
792 # Insert failed, check to see if it failed due to an expired key
793 if ( !$ret ) {
794 list( $value, $expiry ) = $this->decode( dba_fetch( $key, $handle ) );
795 if ( $expiry < time() ) {
796 # Yes expired, delete and try again
797 dba_delete( $key, $handle );
798 $ret = dba_insert( $key, $blob, $handle );
799 # This time if it failed then it will be handled by the caller like any other race
803 dba_close( $handle );
804 wfProfileOut( __METHOD__ );
805 return $ret;
808 function keys() {
809 $reader = $this->getReader();
810 $k1 = dba_firstkey( $reader );
811 if( !$k1 ) {
812 return array();
814 $result[] = $k1;
815 while( $key = dba_nextkey( $reader ) ) {
816 $result[] = $key;
818 return $result;