WordPress.org
Get WordPress

Make WordPress Core


Ignore:
Timestamp:
01/03/2008 04:35:47 AM (17 years ago)
Author:
ryan
Message:

phpdoc for cache.php from darkdragon. fixes #5511

File:
1 edited

Legend:

Unmodified
Added
Removed

  • trunk/wp-includes/cache.php

    r6540 r6543  
    11<?php
     2/**
     3 * Object Cache API
     4 *
     5 * @package WordPress
     6 * @subpackage Cache
     7 */
     8
     9/**
     10 * wp_cache_add() - Adds data to the cache, if the cache key doesn't aleady exist
     11 *
     12 * @since 2.0
     13 * @uses $wp_object_cache Object Cache Class
     14 * @see WP_Object_Cache::add()
     15 *
     16 * @param int|string $key The cache ID to use for retrieval later
     17 * @param mixed $data The data to add to the cache store
     18 * @param string $flag The group to add the cache to
     19 * @param int $expire When the cache data should be expired
     20 * @return unknown
     21 */
    222function wp_cache_add($key, $data, $flag = '', $expire = 0) {
    323    global $wp_object_cache;
    … …  
    626}
    727
     28/**
     29 * wp_cache_close() - Closes the cache
     30 *
     31 * This function has ceased to do anything since WordPress 2.5.
     32 * The functionality was removed along with the rest of the
     33 * persistant cache.
     34 *
     35 * @since 2.0
     36 *
     37 * @return bool Always returns True
     38 */
    839function wp_cache_close() {
    940    return true;
    1041}
    1142
     43/**
     44 * wp_cache_delete() - Removes the cache contents matching ID and flag
     45 *
     46 * @since 2.0
     47 * @uses $wp_object_cache Object Cache Class
     48 * @see WP_Object_Cache::delete()
     49 *
     50 * @param int|string $id What the contents in the cache are called
     51 * @param string $flag Where the cache contents are grouped
     52 * @return bool True on successful removal, false on failure
     53 */
    1254function wp_cache_delete($id, $flag = '') {
    1355    global $wp_object_cache;
    … …  
    1658}
    1759
     60/**
     61 * wp_cache_flush() - Removes all cache items
     62 *
     63 * @since 2.0
     64 * @uses $wp_object_cache Object Cache Class
     65 * @see WP_Object_Cache::flush()
     66 *
     67 * @return bool Always returns true
     68 */
    1869function wp_cache_flush() {
    1970    global $wp_object_cache;
    … …  
    2273}
    2374
     75/**
     76 * wp_cache_get() - Retrieves the cache contents from the cache by ID and flag
     77 *
     78 * @since 2.0
     79 * @uses $wp_object_cache Object Cache Class
     80 * @see WP_Object_Cache::get()
     81 *
     82 * @param int|string $id What the contents in the cache are called
     83 * @param string $flag Where the cache contents are grouped
     84 * @return bool|mixed False on failure to retrieve contents or the cache contents on success
     85 */
    2486function wp_cache_get($id, $flag = '') {
    2587    global $wp_object_cache;
    … …  
    2890}
    2991
     92/**
     93 * wp_cache_init() - Sets up Object Cache Global and assigns it
     94 *
     95 * @since 2.0
     96 * @global WP_Object_Cache $wp_object_cache WordPress Object Cache
     97 */
    3098function wp_cache_init() {
    3199    $GLOBALS['wp_object_cache'] =& new WP_Object_Cache();
    32100}
    33101
     102/**
     103 * wp_cache_replace() - Replaces the contents of the cache with new data
     104 *
     105 * @since 2.0
     106 * @uses $wp_object_cache Object Cache Class
     107 * @see WP_Object_Cache::replace()
     108 *
     109 * @param int|string $id What to call the contents in the cache
     110 * @param mixed $data The contents to store in the cache
     111 * @param string $flag Where to group the cache contents
     112 * @param int $expire When to expire the cache contents
     113 * @return bool False if cache ID and group already exists, true on success
     114 */
    34115function wp_cache_replace($key, $data, $flag = '', $expire = 0) {
    35116    global $wp_object_cache;
    … …  
    38119}
    39120
     121/**
     122 * wp_cache_set() - Saves the data to the cache
     123 *
     124 * @since 2.0
     125 * @uses $wp_object_cache Object Cache Class
     126 * @see WP_Object_Cache::set()
     127 *
     128 * @param int|string $id What to call the contents in the cache
     129 * @param mixed $data The contents to store in the cache
     130 * @param string $flag Where to group the cache contents
     131 * @param int $expire When to expire the cache contents
     132 * @return bool False if cache ID and group already exists, true on success
     133 */
    40134function wp_cache_set($key, $data, $flag = '', $expire = 0) {
    41135    global $wp_object_cache;
    … …  
    44138}
    45139
     140/**
     141 * WordPress Object Cache
     142 *
     143 * The WordPress Object Cache is used to save on trips to the database.
     144 * The Object Cache stores all of the cache data to memory and makes the
     145 * cache contents available by using a key, which is used to name and
     146 * later retrieve the cache contents.
     147 *
     148 * The Object Cache can be replaced by other caching mechanisms by placing
     149 * files in the wp-content folder which is looked at in wp-settings. If
     150 * that file exists, then this file will not be included.
     151 *
     152 * @package WordPress
     153 * @subpackage Cache
     154 * @since 2.0
     155 */
    46156class WP_Object_Cache {
     157
     158    /**
     159     * Holds the cached objects
     160     *
     161     * @var array
     162     * @access private
     163     * @since 2.0
     164     */
    47165    var $cache = array ();
     166
     167    /**
     168     * Cache objects that do not exist in the cache
     169     *
     170     * @var array
     171     * @access private
     172     * @since 2.0
     173     */
    48174    var $non_existant_objects = array ();
     175
     176    /**
     177     * Object caches that are global
     178     *
     179     * @var array
     180     * @access private
     181     * @since 2.0
     182     */
    49183    var $global_groups = array ('users', 'userlogins', 'usermeta');
     184
     185    /**
     186     * The amount of times the cache data was already stored in the cache.
     187     *
     188     * @since 2.5
     189     * @access private
     190     * @var int
     191     */
    50192    var $cache_hits = 0;
     193
     194    /**
     195     * Amount of times the cache did not have the request in cache
     196     *
     197     * @var int
     198     * @access public
     199     * @since 2.0
     200     */
    51201    var $cache_misses = 0;
    52202
     203    /**
     204     * Adds data to the cache if it doesn't already exist.
     205     *
     206     * @uses WP_Object_Cache::get Checks to see if the cache already has data.
     207     * @uses WP_Object_Cache::set Sets the data after the checking the cache contents existance.
     208     *
     209     * @since 2.0
     210     *
     211     * @param int|string $id What to call the contents in the cache
     212     * @param mixed $data The contents to store in the cache
     213     * @param string $group Where to group the cache contents
     214     * @param int $expire When to expire the cache contents
     215     * @return bool False if cache ID and group already exists, true on success
     216     */
    53217    function add($id, $data, $group = 'default', $expire = '') {
    54218        if (empty ($group))
    … …  
    61225    }
    62226
     227    /**
     228     * Remove the contents of the cache ID in the group
     229     *
     230     * If the cache ID does not exist in the group and $force parameter
     231     * is set to false, then nothing will happen. The $force parameter
     232     * is set to false by default.
     233     *
     234     * On success the group and the id will be added to the
     235     * $non_existant_objects property in the class.
     236     *
     237     * @since 2.0
     238     *
     239     * @param int|string $id What the contents in the cache are called
     240     * @param string $group Where the cache contents are grouped
     241     * @param bool $force Optional. Whether to force the unsetting of the cache ID in the group
     242     * @return bool False if the contents weren't deleted and true on success
     243     */
    63244    function delete($id, $group = 'default', $force = false) {
    64245        if (empty ($group))
    … …  
    73254    }
    74255
     256    /**
     257     * Clears the object cache of all data
     258     *
     259     * @since 2.0
     260     *
     261     * @return bool Always returns true
     262     */
    75263    function flush() {
    76264        $this->cache = array ();
    … …  
    79267    }
    80268
     269    /**
     270     * Retrieves the cache contents, if it exists
     271     *
     272     * The contents will be first attempted to be retrieved by searching
     273     * by the ID in the cache group. If the cache is hit (success) then
     274     * the contents are returned.
     275     *
     276     * On failure, the $non_existant_objects property is checked and if
     277     * the cache group and ID exist in there the cache misses will not be
     278     * incremented. If not in the nonexistant objects property, then the
     279     * cache misses will be incremented and the cache group and ID will
     280     * be added to the nonexistant objects.
     281     *
     282     * @since 2.0
     283     *
     284     * @param int|string $id What the contents in the cache are called
     285     * @param string $group Where the cache contents are grouped
     286     * @return bool|mixed False on failure to retrieve contents or the cache contents on success
     287     */
    81288    function get($id, $group = 'default') {
    82289        if (empty ($group))
    … …  
    96303    }
    97304
     305    /**
     306     * Replace the contents in the cache, if contents already exist
     307     *
     308     * @since 2.0
     309     * @see WP_Object_Cache::set()
     310     *
     311     * @param int|string $id What to call the contents in the cache
     312     * @param mixed $data The contents to store in the cache
     313     * @param string $group Where to group the cache contents
     314     * @param int $expire When to expire the cache contents
     315     * @return bool False if not exists, true if contents were replaced
     316     */
    98317    function replace($id, $data, $group = 'default', $expire = '') {
    99318        if (empty ($group))
    … …  
    106325    }
    107326
     327    /**
     328     * Sets the data contents into the cache
     329     *
     330     * The cache contents is grouped by the $group parameter followed
     331     * by the $id. This allows for duplicate ids in unique groups.
     332     * Therefore, naming of the group should be used with care and
     333     * should follow normal function naming guidelines outside of
     334     * core WordPress usage.
     335     *
     336     * The $expire parameter is not used, because the cache will
     337     * automatically expire for each time a page is accessed and PHP
     338     * finishes. The method is more for cache plugins which use files.
     339     *
     340     * @since 2.0
     341     *
     342     * @param int|string $id What to call the contents in the cache
     343     * @param mixed $data The contents to store in the cache
     344     * @param string $group Where to group the cache contents
     345     * @param int $expire Not Used
     346     * @return bool Always returns true
     347     */
    108348    function set($id, $data, $group = 'default', $expire = '') {
    109349        if (empty ($group))
    … …  
    119359    }
    120360
     361    /**
     362     * Echos the stats of the caching.
     363     *
     364     * Gives the cache hits, and cache misses. Also prints every cached
     365     * group, key and the data.
     366     *
     367     * @since 2.0
     368     */
    121369    function stats() {
    122370        echo "<p>";
    … …  
    135383    }
    136384
     385    /**
     386     * PHP4 constructor; Calls PHP 5 style constructor
     387     *
     388     * @since 2.0
     389     *
     390     * @return WP_Object_Cache
     391     */
    137392    function WP_Object_Cache() {
    138393        return $this->__construct();
    139394    }
    140395
     396    /**
     397     * Sets up object properties; PHP 5 style constructor
     398     *
     399     * @since 2.0.8
     400     * @return null|WP_Object_Cache If cache is disabled, returns null.
     401     */
    141402    function __construct() {
    142         register_shutdown_function(array(&$this, "__destruct"));
    143     }
    144 
     403        register_shutdown_function(array(&$this, "__destruct")); /** @todo This should be moved to the PHP4 style constructor, PHP5 already calls __destruct() */
     404    }
     405
     406    /**
     407     * Will save the object cache before object is completely destroyed.
     408     *
     409     * Called upon object destruction, which should be when PHP ends.
     410     *
     411     * @since  2.0.8
     412     *
     413     * @return bool True value. Won't be used by PHP
     414     */
    145415    function __destruct() {
    146416        return true;
Note: See TracChangeset for help on using the changeset viewer.