3 * StatusNet, the distributed open-source microblogging tool
5 * Cache interface plus default in-memory cache implementation
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.
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.
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/>.
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/
31 * Interface for caching
33 * An abstract interface for caching. Because we originally used the
34 * Memcache plugin directly, the interface uses a small subset of the
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/
47 * @var array additional in-process cache for web requests;
48 * disabled on CLI, unsafe for long-running daemons
50 var $_items = array();
51 var $_inlineCache = true;
56 private function __construct() {
57 // Potentially long-running daemons or maintenance scripts
58 // should not use an in-process cache as it becomes out of
60 $this->_inlineCache = (php_sapi_name() != 'cli');
64 * Singleton constructor
66 * Use this to get the singleton instance of Cache.
68 * @return Cache cache object
70 static function instance()
72 if (is_null(self::$_inst)) {
73 self::$_inst = new Cache();
80 * Create a cache key from input text
82 * Builds a cache key from input text. Helps to namespace
83 * the cache area (if shared with other applications or sites)
84 * and prevent conflicts.
86 * @param string $extra the real part of the key
88 * @return string full key
90 static function key($extra)
92 $base_key = common_config('cache', 'base');
94 if (empty($base_key)) {
95 $base_key = self::keyize(common_config('site', 'name'));
98 return 'gnusocial:' . $base_key . ':' . $extra;
102 * Create a cache key for data dependent on code
104 * For cache elements that are dependent on changes in code, this creates
105 * a more-or-less fingerprint of the current running code and adds it to
106 * the cache key. In the case of an upgrade of core, or addition or
107 * removal of plugins, a new unique fingerprint is generated and used.
109 * There can still be problems with a) differences in versions of the
110 * plugins and b) people running code between official versions. This is
111 * usually a problem only for experienced users like developers, who know
112 * how to clear their cache.
114 * For sites that run code between versions (like the status.net cloud),
115 * there's an additional build number configuration setting.
117 * @param string $extra the real part of the key
119 * @return string full key
122 static function codeKey($extra)
124 static $prefix = null;
126 if (empty($prefix)) {
130 foreach (GNUsocial::getActivePlugins() as $plugin=>$attrs) {
138 $uniq = crc32(implode(',', $names));
140 $build = common_config('site', 'build');
142 $prefix = GNUSOCIAL_VERSION.':'.$build.':'.$uniq;
145 return Cache::key($prefix.':'.$extra);
149 * Make a string suitable for use as a key
151 * Useful for turning primary keys of tables into cache keys.
153 * @param string $str string to turn into a key
155 * @return string keyized string
157 static function keyize($str)
159 $str = strtolower($str);
160 $str = preg_replace('/\s/', '_', $str);
165 * Get a value associated with a key
167 * The value should have been set previously.
169 * @param string $key Lookup key
171 * @return string retrieved value or null if unfound
177 common_perf_counter('Cache::get', $key);
178 if (Event::handle('StartCacheGet', array(&$key, &$value))) {
179 if ($this->_inlineCache && array_key_exists($key, $this->_items)) {
180 $value = unserialize($this->_items[$key]);
182 Event::handle('EndCacheGet', array($key, &$value));
189 * Set the value associated with a key
191 * @param string $key The key to use for lookups
192 * @param string $value The value to store
193 * @param integer $flag Flags to use, may include Cache::COMPRESSED
194 * @param integer $expiry Expiry value, mostly ignored
196 * @return boolean success flag
198 function set($key, $value, $flag=null, $expiry=null)
202 common_perf_counter('Cache::set', $key);
203 if (Event::handle('StartCacheSet', array(&$key, &$value, &$flag,
204 &$expiry, &$success))) {
206 if ($this->_inlineCache) {
207 $this->_items[$key] = serialize($value);
212 Event::handle('EndCacheSet', array($key, $value, $flag,
220 * Atomically increment an existing numeric value.
221 * Existing expiration time should remain unchanged, if any.
223 * @param string $key The key to use for lookups
224 * @param int $step Amount to increment (default 1)
226 * @return mixed incremented value, or false if not set.
228 function increment($key, $step=1)
231 common_perf_counter('Cache::increment', $key);
232 if (Event::handle('StartCacheIncrement', array(&$key, &$step, &$value))) {
233 // Fallback is not guaranteed to be atomic,
234 // and may original expiry value.
235 $value = $this->get($key);
236 if ($value !== false) {
238 $ok = $this->set($key, $value);
239 $got = $this->get($key);
241 Event::handle('EndCacheIncrement', array($key, $step, $value));
247 * Delete the value associated with a key
249 * @param string $key Key to delete
251 * @return boolean success flag
253 function delete($key)
257 common_perf_counter('Cache::delete', $key);
258 if (Event::handle('StartCacheDelete', array(&$key, &$success))) {
259 if ($this->_inlineCache && array_key_exists($key, $this->_items)) {
260 unset($this->_items[$key]);
263 Event::handle('EndCacheDelete', array($key));
270 * Close or reconnect any remote connections, such as to give
271 * daemon processes a chance to reconnect on a fresh socket.
273 * @return boolean success flag
279 if (Event::handle('StartCacheReconnect', array(&$success))) {
281 Event::handle('EndCacheReconnect', array());