Index: includes/cache.inc =================================================================== RCS file: /cvs/drupal/drupal/includes/cache.inc,v retrieving revision 1.40 diff -u -p -r1.40 cache.inc --- includes/cache.inc 13 Sep 2009 17:49:51 -0000 1.40 +++ includes/cache.inc 5 Oct 2009 12:51:11 -0000 @@ -2,16 +2,66 @@ // $Id: cache.inc,v 1.40 2009/09/13 17:49:51 dries Exp $ /** - * Get the cache object for a cache bin. + * @file + * Cache API functions. + */ + +/** + * @defgroup cache Persistent cache functions + * @{ + * The persistent cache is split up into several cache bins. In the default + * cache implementation, each cache bin corresponds to a database table by the + * same name. Other implementations might want to store several bins in data + * structures that get flushed together. While it is not a problem for most + * cache bins if the entries in them are flushed before their expire time, some + * might break functionality or are extremely expensive to recalculate. These + * will be marked with a (*). The other bins are expired automatically by core. + * + * Contributed modules can add additional bins and get them expired + * automatically by implementing hook_flush_caches(). * - * By default, this returns an instance of the DrupalDatabaseCache class. - * Classes implementing DrupalCacheInterface can register themselves both as a - * default implementation and for specific bins. + * - cache: Generic cache storage bin (used for variables, theme registry, + * locale date, list of simpletest tests etc). + * - cache_block: Stores the content of various blocks. + * - cache field: Stores the field data belonging to a given object. + * - cache_filter: Stores filtered pieces of content. + * - cache_form(*): Stores multistep forms. Flushing this bin means that some + * forms displayed to users lose their state and the data already submitted + * to them. + * - cache_menu: Stores the structure of visible navigation menus per page. + * - cache_page: Stores generated pages for anonymous users. It is flushed + * very often, whenever a page changes, at least for every ode and comment + * submission. This is the only bin affected by the page cache setting on + * the administrator panel. + * - cache path: Stores the system paths that have an alias. + * - cache_registry: Stores class information parsed from files. + * - cache update(*): Stores available releases. The update server (for + * example, drupal.org) needs to produce the relevant XML for every project + * installed on the current site. As this is different for (almost) every + * site, it's very expensive to recalculate for the update server. * - * @see DrupalCacheInterface + * The reasons for having several bins are as follows: + * + * - Smaller bins mean smaller database tables and allow for faster selects and + * inserts. + * - We try to put fast changing cache items and rather static ones into + * different bins. The effect is that only the fast changing bins will need a + * lot of writes to disk. The more static bins will also be better cacheable + * with MySQL's query cache. + */ + +/** + * Get the cache object for a cache bin. * * @param $bin * The cache bin for which the cache object should be returned. + * + * @return + * By default, this returns an instance of the DrupalDatabaseCache class. + * Classes implementing DrupalCacheInterface can register themselves both as a + * default implementation and for specific bins. + * + * @see DrupalCacheInterface */ function _cache_get_object($bin) { // We do not use drupal_static() here because we do not want to change the @@ -28,18 +78,18 @@ function _cache_get_object($bin) { } /** - * Return data from the persistent cache. Data may be stored as either plain - * text or as serialized data. cache_get will automatically return - * unserialized objects and arrays. + * Return data from the persistent cache. + * + * Data may be stored as either plain text or as serialized data. cache_get() + * will automatically return unserialized objects and arrays. * * @param $cid * The cache ID of the data to retrieve. * @param $bin - * The cache bin to store the data in. Valid core values are 'cache_block', - * 'cache_field', 'cache_filter', 'cache_form', 'cache_menu', 'cache_page', - * 'cache_path', 'cache_registry', 'cache_update' or 'cache' for the default - * cache. - * @return The cache or FALSE on failure. + * The cache bin where the data is stored. + * + * @return + * The cache or FALSE on failure. */ function cache_get($cid, $bin = 'cache') { return _cache_get_object($bin)->get($cid); @@ -49,10 +99,11 @@ function cache_get($cid, $bin = 'cache') * Return data from the persistent cache when given an array of cache IDs. * * @param $cids - * An array of cache IDs for the data to retrieve. This is passed by - * reference, and will have the IDs successfully returned from cache removed. + * A list of cache IDs for the data to retrieve. This is passed by reference + * and will contain the cache IDs successfully returned from cache removed. * @param $bin * The cache bin where the data is stored. + * * @return * An array of the items successfully returned from cache indexed by cid. */ @@ -63,63 +114,14 @@ function cache_get_multiple(array &$cids /** * Store data in the persistent cache. * - * The persistent cache is split up into several cache bins. In the default - * cache implementation, each cache bin corresponds to a database table by the - * same name. Other implementations might want to store several bins in data - * structures that get flushed together. While it is not a problem for most - * cache bins if the entries in them are flushed before their expire time, some - * might break functionality or are extremely expensive to recalculate. These - * will be marked with a (*). The other bins expired automatically by core. - * Contributed modules can add additional bins and get them expired - * automatically by implementing hook_flush_caches(). - * - * - cache: Generic cache storage bin (used for variables, theme registry, - * locale date, list of simpletest tests etc). - * - * - cache_block: Stores the content of various blocks. - * - * - cache field: Stores the field data belonging to a given object. - * - * - cache_filter: Stores filtered pieces of content. - * - * - cache_form(*): Stores multistep forms. Flushing this bin means that some - * forms displayed to users lose their state and the data already submitted - * to them. - * - * - cache_menu: Stores the structure of visible navigation menus per page. - * - * - cache_page: Stores generated pages for anonymous users. It is flushed - * very often, whenever a page changes, at least for every ode and comment - * submission. This is the only bin affected by the page cache setting on - * the administrator panel. - * - * - cache path: Stores the system paths that have an alias. - * - * - cache update(*): Stores available releases. The update server (for - * example, drupal.org) needs to produce the relevant XML for every project - * installed on the current site. As this is different for (almost) every - * site, it's very expensive to recalculate for the update server. - * - * The reasons for having several bins are as follows: - * - * - smaller bins mean smaller database tables and allow for faster selects and - * inserts - * - we try to put fast changing cache items and rather static ones into different - * bins. The effect is that only the fast changing bins will need a lot of - * writes to disk. The more static bins will also be better cacheable with - * MySQL's query cache. - * * @param $cid * The cache ID of the data to store. * @param $data * The data to store in the cache. Complex data types will be automatically - * serialized before insertion. - * Strings will be stored as plain text and not serialized. + * serialized before insertion. Strings will be stored as plain text and not + * serialized. * @param $bin - * The cache bin to store the data in. Valid core values are 'cache_block', - * 'cache_field', 'cache_filter', 'cache_form', 'cache_menu', 'cache_page', - * 'cache_path', 'cache_registry', 'cache_update' or 'cache' for the default - * cache. + * The cache bin to store the data in. * @param $expire * One of the following values: * - CACHE_PERMANENT: Indicates that the item should never be removed unless @@ -132,27 +134,24 @@ function cache_get_multiple(array &$cids * A string containing HTTP header information for cached pages. */ function cache_set($cid, $data, $bin = 'cache', $expire = CACHE_PERMANENT, array $headers = NULL) { - return _cache_get_object($bin)->set($cid, $data, $expire, $headers); + _cache_get_object($bin)->set($cid, $data, $expire, $headers); } /** * Expire data from the cache. * * If called without arguments, expirable entries will be cleared from the - * cache_page and cache_block bins. + * 'cache_page' and 'cache_block' bins. * * @param $cid * If set, the cache ID to delete. Otherwise, all cache entries that can * expire are deleted. - * * @param $bin - * If set, the bin $bin to delete from. Mandatory - * argument if $cid is set. - * + * If set, the bin $bin to delete from. Mandatory argument if $cid is set. * @param $wildcard - * If $wildcard is TRUE, cache IDs starting with $cid are deleted in - * addition to the exact cache ID specified by $cid. If $wildcard is - * TRUE and $cid is '*' then the entire table $table is emptied. + * If $wildcard is TRUE, cache IDs starting with $cid are deleted in addition + * to the exact cache ID specified by $cid. If $wildcard is TRUE and $cid is + * '*' then the entire bin $bin is emptied. */ function cache_clear_all($cid = NULL, $bin = NULL, $wildcard = FALSE) { if (!isset($cid) && !isset($bin)) { @@ -175,6 +174,7 @@ function cache_clear_all($cid = NULL, $b * * @param $bin * The cache bin to check. + * * @return * TRUE if the cache bin specified is empty. */ @@ -185,23 +185,24 @@ function cache_is_empty($bin) { /** * Interface for cache implementations. * - * All cache implementations have to implement this interface. DrupalDatabaseCache - * provides the default implementation, which can be consulted as an example. + * All cache implementations have to implement this interface. + * DrupalDatabaseCache provides the default implementation, which can be + * consulted as an example. * * To make Drupal use your implementation for a certain cache bin, you have to * set a variable with the name of the cache bin as its key and the name of your - * class as its value. For example, if your implementation of DrupalCacheInterface - * was called MyCustomCache, the following line would make Drupal use it for the - * 'cache_page' bin: + * class as its value. For example, if your implementation of + * DrupalCacheInterface was called MyCustomCache, the following line would make + * Drupal use it for the 'cache_page' bin: * @code - * variable_set('cache_page', 'MyCustomCache'); + * variable_set('cache_page', 'MyCustomCache'); * @endcode * - * Additionally, you can register your cache implementation to be used by default - * for all cache bins by setting the variable 'cache_default_class' to the name - * of your implementation of the DrupalCacheInterface, e.g. + * Additionally, you can register your cache implementation to be used by + * default for all cache bins by setting the variable 'cache_default_class' to + * the name of your implementation of the DrupalCacheInterface, e.g. * @code - * variable_set('cache_default_class', 'MyCustomCache'); + * variable_set('cache_default_class', 'MyCustomCache'); * @endcode * * @see _cache_get_object() @@ -217,13 +218,16 @@ interface DrupalCacheInterface { function __construct($bin); /** - * Return data from the persistent cache. Data may be stored as either plain - * text or as serialized data. cache_get will automatically return - * unserialized objects and arrays. + * Return data from the persistent cache. + * + * Data may be stored as either plain text or as serialized data. cache_get() + * will automatically return unserialized objects and arrays. * * @param $cid * The cache ID of the data to retrieve. - * @return The cache or FALSE on failure. + * + * @return + * The cache or FALSE on failure. */ function get($cid); @@ -231,11 +235,11 @@ interface DrupalCacheInterface { * Return data from the persistent cache when given an array of cache IDs. * * @param $cids - * An array of cache IDs for the data to retrieve. This is passed by - * reference, and will have the IDs successfully returned from cache - * removed. + * A list of cache IDs for the data to retrieve. This is passed by + * reference and will have the IDs successfully returned from cache removed. + * * @return - * An array of the items successfully returned from cache indexed by cid. + * An array of the items successfully returned from cache keyed by cid. */ function getMultiple(&$cids); @@ -246,8 +250,8 @@ interface DrupalCacheInterface { * The cache ID of the data to store. * @param $data * The data to store in the cache. Complex data types will be automatically - * serialized before insertion. - * Strings will be stored as plain text and not serialized. + * serialized before insertion. Strings will be stored as plain text and not + * serialized. * @param $expire * One of the following values: * - CACHE_PERMANENT: Indicates that the item should never be removed unless @@ -261,18 +265,19 @@ interface DrupalCacheInterface { */ function set($cid, $data, $expire = CACHE_PERMANENT, array $headers = NULL); - /** - * Expire data from the cache. If called without arguments, expirable - * entries will be cleared from the cache_page and cache_block bins. + * Expire data from the cache. + * + * If called without arguments, expirable entries will be cleared from the + * 'cache_page' and 'cache_block' bins. * * @param $cid * If set, the cache ID to delete. Otherwise, all cache entries that can * expire are deleted. * @param $wildcard - * If set to TRUE, the $cid is treated as a substring - * to match rather than a complete ID. The match is a right hand - * match. If '*' is given as $cid, the bin $bin will be emptied. + * If set to TRUE, the $cid is treated as a substring to match rather than a + * complete ID. The match is a right hand match. If '*' is given as $cid, + * the bin $bin will be emptied. */ function clear($cid = NULL, $wildcard = FALSE); @@ -289,6 +294,10 @@ interface DrupalCacheInterface { } /** + * @} End of "defgroup cache". + */ + +/** * Default cache implementation. * * This is Drupal's default cache implementation. It uses the database to store @@ -357,6 +366,7 @@ class DrupalDatabaseCache implements Dru * * @param $cache * An item loaded from cache_get() or cache_get_multiple(). + * * @return * The item with data unserialized as appropriate or FALSE if there is no * valid item to load. @@ -375,11 +385,11 @@ class DrupalDatabaseCache implements Dru } } // If enforcing a minimum cache lifetime, validate that the data is - // currently valid for this user before we return it by making sure the cache - // entry was created before the timestamp in the current session's cache - // timer. The cache variable is loaded into the $user object by _drupal_session_read() - // in session.inc. If the data is permanent or we're not enforcing a minimum - // cache lifetime always return the cached data. + // currently valid for this user before we return it by making sure the + // cache entry was created before the timestamp in the current session's + // cache timer. The cache variable is loaded into the $user object by + // _drupal_session_read() in session.inc. If the data is permanent or we're + // not enforcing a minimum cache lifetime always return the cached data. if ($cache->expire != CACHE_PERMANENT && variable_get('cache_lifetime', 0) && $user->cache > $cache->created) { // This cache data is too old and thus not valid for us, ignore it. return FALSE; @@ -420,9 +430,9 @@ class DrupalDatabaseCache implements Dru if (empty($cid)) { if (variable_get('cache_lifetime', 0)) { // We store the time in the current user's $user->cache variable which - // will be saved into the sessions bin by _drupal_session_write(). We then - // simulate that the cache was flushed for this user by not returning - // cached data that was cached before the timestamp. + // will be saved into the sessions bin by _drupal_session_write(). We + // then simulate that the cache was flushed for this user by not + // returning cached data that was cached before the timestamp. $user->cache = REQUEST_TIME; $cache_flush = variable_get('cache_flush_' . $this->bin, 0);