[Summary view] [Print] [Text view]

   1  <!-- $Id: object-cache.html,v 1.1 2009/01/23 23:14:04 merlinofchaos Exp $ -->
   2  The CTools Object Cache is a specialized cache for storing data that is non-volatile. This differs from the standard Drupal cache mechanism, which is volatile, meaning that the data can be cleared at any time and it is expected that any cached data can easily be reconstructed. In contrast, data stored in this cache is not expected to be reconstructable. It is primarily used for storing user input which is retrieved in stages, allowing for more complex user interface interactions.
   3  
   4  The object cache consists of 3 normal functions for cache maintenance, and 2 additional functions to facilitate locking.
   5  
   6  To use any of these functions, you must first use ctools_include:
   7  
   8  <pre>
   9  ctools_include('object-cache');
  10  </pre>
  11  
  12  <pre>
  13  /**
  14   * Get an object from the non-volatile ctools cache.
  15   *
  16   * This function caches in memory as well, so that multiple calls to this
  17   * will not result in multiple database reads.
  18   *
  19   * @param $obj
  20   *   A 32 character or less string to define what kind of object is being
  21   *   stored; primarily this is used to prevent collisions.
  22   * @param $name
  23   *   The name of the object being stored.
  24   * @param $skip_cache
  25   *   Skip the memory cache, meaning this must be read from the db again.
  26   *
  27   * @return
  28   *   The data that was cached.
  29   */
  30  function ctools_object_cache_get($obj, $name, $skip_cache = FALSE) {
  31  </pre>
  32  
  33  <pre>
  34  /**
  35   * Store an object in the non-volatile ctools cache.
  36   *
  37   * @param $obj
  38   *   A 32 character or less string to define what kind of object is being
  39   *   stored; primarily this is used to prevent collisions.
  40   * @param $name
  41   *   The name of the object being stored.
  42   * @param $cache
  43   *   The object to be cached. This will be serialized prior to writing.
  44   */
  45  function ctools_object_cache_set($obj, $name, $cache) {
  46  </pre>
  47  
  48  <pre>
  49  /**
  50   * Remove an object from the non-volatile ctools cache
  51   *
  52   * @param $obj
  53   *   A 32 character or less string to define what kind of object is being
  54   *   stored; primarily this is used to prevent collisions.
  55   * @param $name
  56   *   The name of the object being removed.
  57   */
  58  function ctools_object_cache_clear($obj, $name) {
  59  </pre>
  60  
  61  To facilitate locking, which is the ability to prohibit updates by other users while one user has an object cached, this system provides two functions:
  62  
  63  <pre>
  64  /**
  65   * Determine if another user has a given object cached.
  66   *
  67   * This is very useful for 'locking' objects so that only one user can
  68   * modify them.
  69   *
  70   * @param $obj
  71   *   A 32 character or less string to define what kind of object is being
  72   *   stored; primarily this is used to prevent collisions.
  73   * @param $name
  74   *   The name of the object being removed.
  75   *
  76   * @return
  77   *   An object containing the UID and updated date if found; NULL if not.
  78   */
  79  function ctools_object_cache_test($obj, $name) {
  80  </pre>
  81  
  82  The object returned by ctools_object_cache_test can be directly used to determine whether a user should be allowed to cache their own version of an object.
  83  
  84  To allow the concept of breaking a lock, that is, clearing another users changes:
  85  
  86  <pre>
  87  /**
  88   * Remove an object from the non-volatile ctools cache for all session IDs.
  89   *
  90   * This is useful for clearing a lock.
  91   *
  92   * @param $obj
  93   *   A 32 character or less string to define what kind of object is being
  94   *   stored; primarily this is used to prevent collisions.
  95   * @param $name
  96   *   The name of the object being removed.
  97   */
  98  function ctools_object_cache_clear_all($obj, $name) {
  99  </pre>
 100  
 101  Typical best practice is to use wrapper functions such as these:
 102  
 103  <pre>
 104  /**
 105   * Get the cached changes to a given task handler.
 106   */
 107  function delegator_page_get_page_cache($name) {
 108    ctools_include('object-cache');
 109    $cache = ctools_object_cache_get('delegator_page', $name);
 110    if (!$cache) {
 111      $cache = delegator_page_load($name);
 112      $cache->locked = ctools_object_cache_test('delegator_page', $name);
 113    }
 114  
 115    return $cache;
 116  }
 117  
 118  /**
 119   * Store changes to a task handler in the object cache.
 120   */
 121  function delegator_page_set_page_cache($name, $page) {
 122    ctools_include('object-cache');
 123    $cache = ctools_object_cache_set('delegator_page', $name, $page);
 124  }
 125  
 126  /**
 127   * Remove an item from the object cache.
 128   */
 129  function delegator_page_clear_page_cache($name) {
 130    ctools_include('object-cache');
 131    ctools_object_cache_clear('delegator_page', $name);
 132  }
 133  </pre>