FINAL suepr merge step : added all modules to this super repos

sites/all/modules/contrib/dev/ctools/includes/cache.inc

@@ -0,0 +1,169 @@
+<?php
+
+/**
+ * @file
+ *
+ * Plugins to handle cache-indirection.
+ *
+ * Simple plugin management to allow clients to more tightly control where
+ * object caches are stored.
+ *
+ * CTools provides an object cache mechanism, and it also provides a number
+ * of subsystems that are designed to plug into larger systems. When doing
+ * caching on multi-step forms (in particular during AJAX operations) these
+ * subsystems often need to operate their own cache. In reality, its best
+ * for everyone if they are able to piggyback off of the larger cache.
+ *
+ * This system allows this by registering plugins to control where caches
+ * are actually stored. For the most part, the subsystems could care less
+ * where the data is fetched from and stored to. All it needs to know is
+ * that it can 'get', 'set' and 'clear' caches. Additionally, some caches
+ * might need extra operations such as 'lock' and 'finalize', and other
+ * operations may be needed based upon the specific uses for the cache
+ * plugins.
+ *
+ * To utilize cache plugins, there are two pieces of data. First, there is
+ * the mechanism, which is simply the name of the plugin to use. CTools
+ * provides a 'simple' mechanism which goes straight through to the object
+ * cache. The second piece of data is the 'key' which is a unique identifier
+ * that can be used to find the data needed. Keys can be generated any number
+ * of ways, and the plugin must be agnostic about the key itself.
+ *
+ * That said, the 'mechanism' can be specified as pluginame::data and that
+ * data can be used to derive additional data. For example, it is often
+ * desirable to NOT store any cached data until original data (i.e, user
+ * input) has been received. The data can be used to derive this original
+ * data so that when a 'get' is called, if the cache is missed it can create
+ * the data needed. This can help prevent unwanted cache entries from
+ * building up just by visiting edit UIs without actually modifying anything.
+ *
+ * Modules wishing to implement cache indirection mechanisms need to implement
+ * a plugin of type 'cache' for the module 'ctools' and provide the .inc file.
+ * It should provide callbacks for 'cache set', 'cache get', and 'cache clear'.
+ * It can provide callbacks for 'break' and 'finalize' if these are relevant
+ * to the caching mechanism (i.e, for use with locking caches such as the page
+ * manager cache). Other operations may be utilized but at this time are not part
+ * of CTools.
+ */
+
+/**
+ * Fetch data from an indirect cache.
+ *
+ * @param string $mechanism
+ *   A string containing the plugin name, and an optional data element to
+ *   send to the plugin separated by two colons.
+ *
+ * @param string $key
+ *   The key used to identify the cache.
+ *
+ * @return mixed
+ *   The cached data. This can be any format as the plugin does not necessarily
+ *   have knowledge of what is being cached.
+ */
+function ctools_cache_get($mechanism, $key) {
+  return ctools_cache_operation($mechanism, $key, 'get');
+}
+
+/**
+ * Store data in an indirect cache.
+ *
+ * @param string $mechanism
+ *   A string containing the plugin name, and an optional data element to
+ *   send to the plugin separated by two colons.
+ *
+ * @param string $key
+ *   The key used to identify the cache.
+ *
+ * @param mixed $object
+ *   The data to cache. This can be any format as the plugin does not
+ *   necessarily have knowledge of what is being cached.
+ */
+function ctools_cache_set($mechanism, $key, $object) {
+  return ctools_cache_operation($mechanism, $key, 'set', $object);
+}
+
+/**
+ * Clear data from an indirect cache.
+ *
+ * @param string $mechanism
+ *   A string containing the plugin name, and an optional data element to
+ *   send to the plugin separated by two colons.
+ *
+ * @param string $key
+ *   The key used to identify the cache.
+ */
+function ctools_cache_clear($mechanism, $key) {
+  return ctools_cache_operation($mechanism, $key, 'clear');
+
+}
+
+/**
+ * Perform a secondary operation on an indirect cache.
+ *
+ * Additional operations, beyond get, set and clear may be items
+ * such as 'break' and 'finalize', which are needed to support cache
+ * locking. Other operations may be added by users of the indirect
+ * caching functions as needed.
+ *
+ * @param string $mechanism
+ *   A string containing the plugin name, and an optional data element to
+ *   send to the plugin separated by two colons.
+ *
+ * @param string $key
+ *   The key used to identify the cache.
+ *
+ * @param string $op
+ *   The operation to call, such as 'break' or 'finalize'.
+ *
+ * @param mixed $object
+ *   The cache data being operated on, in case it is necessary. This is
+ *   optional so no references should be used.
+ *
+ * @return mixed
+ *   The operation may or may not return a value.
+ */
+function ctools_cache_operation($mechanism, $key, $op, $object = NULL) {
+  list($plugin, $data) = ctools_cache_find_plugin($mechanism);
+  if (empty($plugin)) {
+    return;
+  }
+
+  $function = ctools_plugin_get_function($plugin, "cache $op");
+  if (empty($function)) {
+    return;
+  }
+
+  return $function($data, $key, $object, $op);
+}
+
+/**
+ * Take a mechanism and return a plugin and data.
+ *
+ * @param string $mechanism
+ *   A string containing the plugin name, and an optional data element to
+ *   send to the plugin separated by two colons.
+ *
+ * @return array
+ *   An array, the first element will be the plugin and the second element
+ *   will be the data. If the plugin could not be found, the $plugin will
+ *   be NULL.
+ */
+function ctools_cache_find_plugin($mechanism) {
+  if (strpos($mechanism, '::') !== FALSE) {
+    // use explode(2) to ensure that the data can contain double
+    // colons, just in case.
+    list($name, $data) = explode('::', $mechanism, 2);
+  }
+  else {
+    $name = $mechanism;
+    $data = '';
+  }
+
+  if (empty($name)) {
+    return array(NULL, $data);
+  }
+
+  ctools_include('plugins');
+  $plugin = ctools_get_plugins('ctools', 'cache', $name);
+  return array($plugin, $data);
+}