cache.inc in Chaos Tool Suite (ctools) 7

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.

File

includes/cache.inc

<?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,
  );
}

Functions

Name	Description
ctools_cache_clear	Clear data from an indirect cache.
ctools_cache_find_plugin	Take a mechanism and return a plugin and data.
ctools_cache_get	Fetch data from an indirect cache.
ctools_cache_operation	Perform a secondary operation on an indirect cache.
ctools_cache_set	Store data in an indirect cache.