send_message -> sendMessage

[quix0rs-gnu-social.git] / lib / cache.php

diff --git a/lib/cache.php b/lib/cache.php
index 31d2f84d2da657ea9e80d918d23d026fcf81312a..c09a1dd9f27c75676eb24f634f6c0378547c798d 100644 (file)
--- a/lib/cache.php
+++ b/lib/cache.php
@@ -30,15 +30,33 @@
 /**
  * Interface for caching
  *
- * An abstract interface for caching.
+ * An abstract interface for caching. Because we originally used the
+ * Memcache plugin directly, the interface uses a small subset of the
+ * Memcache interface.
  *
+ * @category  Cache
+ * @package   StatusNet
+ * @author    Evan Prodromou <evan@status.net>
+ * @copyright 2009 StatusNet, Inc.
+ * @license   http://www.fsf.org/licensing/licenses/agpl-3.0.html AGPL 3.0
+ * @link      http://status.net/
  */
 
 class Cache
 {
-    var $_items = array();
+    var $_items   = array();
     static $_inst = null;
 
+    const COMPRESSED = 1;
+
+    /**
+     * Singleton constructor
+     *
+     * Use this to get the singleton instance of Cache.
+     *
+     * @return Cache cache object
+     */
+
     static function instance()
     {
         if (is_null(self::$_inst)) {
@@ -48,9 +66,21 @@ class Cache
         return self::$_inst;
     }
 
+    /**
+     * Create a cache key from input text
+     *
+     * Builds a cache key from input text. Helps to namespace
+     * the cache area (if shared with other applications or sites)
+     * and prevent conflicts.
+     *
+     * @param string $extra the real part of the key
+     *
+     * @return string full key
+     */
+
     static function key($extra)
     {
-        $base_key = common_config('memcached', 'base');
+        $base_key = common_config('cache', 'base');
 
         if (empty($base_key)) {
             $base_key = common_keyize(common_config('site', 'name'));
@@ -59,6 +89,16 @@ class Cache
         return 'statusnet:' . $base_key . ':' . $extra;
     }
 
+    /**
+     * Make a string suitable for use as a key
+     *
+     * Useful for turning primary keys of tables into cache keys.
+     *
+     * @param string $str string to turn into a key
+     *
+     * @return string keyized string
+     */
+
     static function keyize($str)
     {
         $str = strtolower($str);
@@ -66,16 +106,23 @@ class Cache
         return $str;
     }
 
+    /**
+     * Get a value associated with a key
+     *
+     * The value should have been set previously.
+     *
+     * @param string $key Lookup key
+     *
+     * @return string retrieved value or null if unfound
+     */
+
     function get($key)
     {
-        $value = null;
+        $value = false;
 
-        if (!Event::handle('StartCacheGet', array(&$key, &$value))) {
+        if (Event::handle('StartCacheGet', array(&$key, &$value))) {
             if (array_key_exists($key, $this->_items)) {
-                common_log(LOG_INFO, 'Cache HIT for key ' . $key);
-                $value = $this->_items[$key];
-            } else {
-                common_log(LOG_INFO, 'Cache MISS for key ' . $key);
+                $value = unserialize($this->_items[$key]);
             }
             Event::handle('EndCacheGet', array($key, &$value));
         }
@@ -83,27 +130,75 @@ class Cache
         return $value;
     }
 
+    /**
+     * Set the value associated with a key
+     *
+     * @param string  $key    The key to use for lookups
+     * @param string  $value  The value to store
+     * @param integer $flag   Flags to use, may include Cache::COMPRESSED
+     * @param integer $expiry Expiry value, mostly ignored
+     *
+     * @return boolean success flag
+     */
+
     function set($key, $value, $flag=null, $expiry=null)
     {
         $success = false;
 
-        if (!Event::handle('StartCacheSet', array(&$key, &$value, &$flag, &$expiry, &$success))) {
-            common_log(LOG_INFO, 'Setting cache value for key ' . $key);
-            $this->_items[$key] = $value;
+        if (Event::handle('StartCacheSet', array(&$key, &$value, &$flag,
+                                                 &$expiry, &$success))) {
+
+            $this->_items[$key] = serialize($value);
+
             $success = true;
-            Event::handle('EndCacheSet', array($key, $value, $flag, $expiry));
+
+            Event::handle('EndCacheSet', array($key, $value, $flag,
+                                               $expiry));
         }
 
         return $success;
     }
 
+    /**
+     * Atomically increment an existing numeric value.
+     * Existing expiration time should remain unchanged, if any.
+     *
+     * @param string  $key    The key to use for lookups
+     * @param int     $step   Amount to increment (default 1)
+     *
+     * @return mixed incremented value, or false if not set.
+     */
+    function increment($key, $step=1)
+    {
+        $value = false;
+        if (Event::handle('StartCacheIncrement', array(&$key, &$step, &$value))) {
+            // Fallback is not guaranteed to be atomic,
+            // and may original expiry value.
+            $value = $this->get($key);
+            if ($value !== false) {
+                $value += $step;
+                $ok = $this->set($key, $value);
+                $got = $this->get($key);
+            }
+            Event::handle('EndCacheIncrement', array($key, $step, $value));
+        }
+        return $value;
+    }
+
+    /**
+     * Delete the value associated with a key
+     *
+     * @param string $key Key to delete
+     *
+     * @return boolean success flag
+     */
+
     function delete($key)
     {
         $success = false;
 
-        if (!Event::handle('StartCacheDelete', array(&$key, &$success))) {
-            if (array_key_exists($key, $this->_items[$key])) {
-                common_log(LOG_INFO, 'Deleting cache value for key ' . $key);
+        if (Event::handle('StartCacheDelete', array(&$key, &$success))) {
+            if (array_key_exists($key, $this->_items)) {
                 unset($this->_items[$key]);
             }
             $success = true;
@@ -112,4 +207,23 @@ class Cache
 
         return $success;
     }
+
+    /**
+     * Close or reconnect any remote connections, such as to give
+     * daemon processes a chance to reconnect on a fresh socket.
+     *
+     * @return boolean success flag
+     */
+
+    function reconnect()
+    {
+        $success = false;
+
+        if (Event::handle('StartCacheReconnect', array(&$success))) {
+            $success = true;
+            Event::handle('EndCacheReconnect', array());
+        }
+
+        return $success;
+    }
 }