lib/cache.php

   1 <?php
   2 /**
   3  * StatusNet, the distributed open-source microblogging tool
   4  *
   5  * Cache interface plus default in-memory cache implementation
   6  *
   7  * PHP version 5
   8  *
   9  * LICENCE: This program is free software: you can redistribute it and/or modify
  10  * it under the terms of the GNU Affero General Public License as published by
  11  * the Free Software Foundation, either version 3 of the License, or
  12  * (at your option) any later version.
  13  *
  14  * This program is distributed in the hope that it will be useful,
  15  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  16  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  17  * GNU Affero General Public License for more details.
  18  *
  19  * You should have received a copy of the GNU Affero General Public License
  20  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  21  *
  22  * @category  Cache
  23  * @package   StatusNet
  24  * @author    Evan Prodromou <evan@status.net>
  25  * @copyright 2009 StatusNet, Inc.
  26  * @license   http://www.fsf.org/licensing/licenses/agpl-3.0.html GNU Affero General Public License version 3.0
  27  * @link      http://status.net/
  28  */
  29
  30 /**
  31  * Interface for caching
  32  *
  33  * An abstract interface for caching. Because we originally used the
  34  * Memcache plugin directly, the interface uses a small subset of the
  35  * Memcache interface.
  36  *
  37  * @category  Cache
  38  * @package   StatusNet
  39  * @author    Evan Prodromou <evan@status.net>
  40  * @copyright 2009 StatusNet, Inc.
  41  * @license   http://www.fsf.org/licensing/licenses/agpl-3.0.html AGPL 3.0
  42  * @link      http://status.net/
  43  */
  44
  45 class Cache
  46 {
  47     var $_items   = array();
  48     static $_inst = null;
  49
  50     const COMPRESSED = 1;
  51
  52     /**
  53      * Singleton constructor
  54      *
  55      * Use this to get the singleton instance of Cache.
  56      *
  57      * @return Cache cache object
  58      */
  59
  60     static function instance()
  61     {
  62         if (is_null(self::$_inst)) {
  63             self::$_inst = new Cache();
  64         }
  65
  66         return self::$_inst;
  67     }
  68
  69     /**
  70      * Create a cache key from input text
  71      *
  72      * Builds a cache key from input text. Helps to namespace
  73      * the cache area (if shared with other applications or sites)
  74      * and prevent conflicts.
  75      *
  76      * @param string $extra the real part of the key
  77      *
  78      * @return string full key
  79      */
  80
  81     static function key($extra)
  82     {
  83         $base_key = common_config('cache', 'base');
  84
  85         if (empty($base_key)) {
  86             $base_key = common_keyize(common_config('site', 'name'));
  87         }
  88
  89         return 'statusnet:' . $base_key . ':' . $extra;
  90     }
  91
  92     /**
  93      * Make a string suitable for use as a key
  94      *
  95      * Useful for turning primary keys of tables into cache keys.
  96      *
  97      * @param string $str string to turn into a key
  98      *
  99      * @return string keyized string
 100      */
 101
 102     static function keyize($str)
 103     {
 104         $str = strtolower($str);
 105         $str = preg_replace('/\s/', '_', $str);
 106         return $str;
 107     }
 108
 109     /**
 110      * Get a value associated with a key
 111      *
 112      * The value should have been set previously.
 113      *
 114      * @param string $key Lookup key
 115      *
 116      * @return string retrieved value or null if unfound
 117      */
 118
 119     function get($key)
 120     {
 121         $value = false;
 122
 123         if (Event::handle('StartCacheGet', array(&$key, &$value))) {
 124             if (array_key_exists($key, $this->_items)) {
 125                 $value = unserialize($this->_items[$key]);
 126             }
 127             Event::handle('EndCacheGet', array($key, &$value));
 128         }
 129
 130         return $value;
 131     }
 132
 133     /**
 134      * Set the value associated with a key
 135      *
 136      * @param string  $key    The key to use for lookups
 137      * @param string  $value  The value to store
 138      * @param integer $flag   Flags to use, may include Cache::COMPRESSED
 139      * @param integer $expiry Expiry value, mostly ignored
 140      *
 141      * @return boolean success flag
 142      */
 143
 144     function set($key, $value, $flag=null, $expiry=null)
 145     {
 146         $success = false;
 147
 148         if (Event::handle('StartCacheSet', array(&$key, &$value, &$flag,
 149                                                  &$expiry, &$success))) {
 150
 151             $this->_items[$key] = serialize($value);
 152
 153             $success = true;
 154
 155             Event::handle('EndCacheSet', array($key, $value, $flag,
 156                                                $expiry));
 157         }
 158
 159         return $success;
 160     }
 161
 162     /**
 163      * Atomically increment an existing numeric value.
 164      * Existing expiration time should remain unchanged, if any.
 165      *
 166      * @param string  $key    The key to use for lookups
 167      * @param int     $step   Amount to increment (default 1)
 168      *
 169      * @return mixed incremented value, or false if not set.
 170      */
 171     function increment($key, $step=1)
 172     {
 173         $value = false;
 174         if (Event::handle('StartCacheIncrement', array(&$key, &$step, &$value))) {
 175             // Fallback is not guaranteed to be atomic,
 176             // and may original expiry value.
 177             $value = $this->get($key);
 178             if ($value !== false) {
 179                 $value += $step;
 180                 $ok = $this->set($key, $value);
 181                 $got = $this->get($key);
 182             }
 183             Event::handle('EndCacheIncrement', array($key, $step, $value));
 184         }
 185         return $value;
 186     }
 187
 188     /**
 189      * Delete the value associated with a key
 190      *
 191      * @param string $key Key to delete
 192      *
 193      * @return boolean success flag
 194      */
 195
 196     function delete($key)
 197     {
 198         $success = false;
 199
 200         if (Event::handle('StartCacheDelete', array(&$key, &$success))) {
 201             if (array_key_exists($key, $this->_items)) {
 202                 unset($this->_items[$key]);
 203             }
 204             $success = true;
 205             Event::handle('EndCacheDelete', array($key));
 206         }
 207
 208         return $success;
 209     }
 210
 211     /**
 212      * Close or reconnect any remote connections, such as to give
 213      * daemon processes a chance to reconnect on a fresh socket.
 214      *
 215      * @return boolean success flag
 216      */
 217
 218     function reconnect()
 219     {
 220         $success = false;
 221
 222         if (Event::handle('StartCacheReconnect', array(&$success))) {
 223             $success = true;
 224             Event::handle('EndCacheReconnect', array());
 225         }
 226
 227         return $success;
 228     }
 229 }