Make WordPress Core

Ticket #5511: cache.phpdoc.r6473.diff

File cache.phpdoc.r6473.diff, 11.7 KB (added by darkdragon, 16 years ago)

Incomplete documentation for cache.php based off of r6473

  • cache.php

     
    11<?php
     2/**
     3 * Object Cache API
     4 *
     5 * @package WordPress
     6 * @subpackage Cache
     7 */
     8
     9/**
     10 * wp_cache_add() - {@internal Missing Short Description}}
     11 *
     12 * {@internal Missing Long Description}}
     13 *
     14 * @since 2.0
     15 * @uses $wp_object_cache Object Cache Class
     16 *
     17 * @param unknown_type $key
     18 * @param unknown_type $data
     19 * @param unknown_type $flag
     20 * @param unknown_type $expire
     21 * @return unknown
     22 */
    223function wp_cache_add($key, $data, $flag = '', $expire = 0) {
    324        global $wp_object_cache;
    425        $data = unserialize(serialize($data));
     
    627        return $wp_object_cache->add($key, $data, $flag, $expire);
    728}
    829
     30/**
     31 * wp_cache_close() - {@internal Missing Short Description}}
     32 *
     33 * {@internal Missing Long Description}}
     34 *
     35 * @since 2.0
     36 * @uses $wp_object_cache Object Cache Class
     37 *
     38 * @return unknown
     39 */
    940function wp_cache_close() {
    1041        global $wp_object_cache;
    1142
     
    1445        return $wp_object_cache->save();
    1546}
    1647
     48/**
     49 * wp_cache_delete() - {@internal Missing Short Description}}
     50 *
     51 * {@internal Missing Long Description}}
     52 *
     53 * @since 2.0
     54 * @uses $wp_object_cache Object Cache Class
     55 *
     56 * @param unknown_type $id
     57 * @param unknown_type $flag
     58 * @return unknown
     59 */
    1760function wp_cache_delete($id, $flag = '') {
    1861        global $wp_object_cache;
    1962
    2063        return $wp_object_cache->delete($id, $flag);
    2164}
    2265
     66/**
     67 * wp_cache_flush() - {@internal Missing Short Description}}
     68 *
     69 * {@internal Missing Long Description}}
     70 *
     71 * @since 2.0
     72 * @uses $wp_object_cache Object Cache Class
     73 *
     74 * @return unknown
     75 */
    2376function wp_cache_flush() {
    2477        global $wp_object_cache;
    2578
    2679        return $wp_object_cache->flush();
    2780}
    2881
     82/**
     83 * wp_cache_get() - {@internal Missing Short Description}}
     84 *
     85 * {@internal Missing Long Description}}
     86 *
     87 * @since 2.0
     88 * @uses $wp_object_cache Object Cache Class
     89 *
     90 * @param unknown_type $id
     91 * @param unknown_type $flag
     92 * @return unknown
     93 */
    2994function wp_cache_get($id, $flag = '') {
    3095        global $wp_object_cache;
    3196
    3297        return $wp_object_cache->get($id, $flag);
    3398}
    3499
     100/**
     101 * wp_cache_init() - Sets up Object Cache Global and assigns it
     102 *
     103 * @since 2.0
     104 * @global WP_Object_Cache $wp_object_cache WordPress Object Cache
     105 */
    35106function wp_cache_init() {
    36107        $GLOBALS['wp_object_cache'] =& new WP_Object_Cache();
    37108}
    38109
     110/**
     111 * wp_cache_replace() - {@internal Missing Short Description}}
     112 *
     113 * {@internal Missing Long Description}}
     114 *
     115 * @since 2.0
     116 * @uses $wp_object_cache Object Cache Class
     117 *
     118 * @param unknown_type $key
     119 * @param unknown_type $data
     120 * @param unknown_type $flag
     121 * @param unknown_type $expire
     122 * @return unknown
     123 */
    39124function wp_cache_replace($key, $data, $flag = '', $expire = 0) {
    40125        global $wp_object_cache;
    41126        $data = unserialize(serialize($data));
     
    43128        return $wp_object_cache->replace($key, $data, $flag, $expire);
    44129}
    45130
     131/**
     132 * wp_cache_set() - {@internal Missing Short Description}}
     133 *
     134 * {@internal Missing Long Description}}
     135 *
     136 * @since 2.0
     137 * @uses $wp_object_cache Object Cache Class
     138 *
     139 * @param unknown_type $key
     140 * @param unknown_type $data
     141 * @param unknown_type $flag
     142 * @param unknown_type $expire
     143 * @return unknown
     144 */
    46145function wp_cache_set($key, $data, $flag = '', $expire = 0) {
    47146        global $wp_object_cache;
    48147        $data = unserialize(serialize($data));
     
    50149        return $wp_object_cache->set($key, $data, $flag, $expire);
    51150}
    52151
     152/**
     153 * The cache file header
     154 */
    53155define('CACHE_SERIAL_HEADER', "<?php\n/*");
     156
     157/**
     158 * The cache file footer
     159 */
    54160define('CACHE_SERIAL_FOOTER', "*/\n?".">");
    55161
     162/**
     163 * WordPress Object Cache
     164 *
     165 * {@internal Missing Long Description}}
     166 *
     167 * @package WordPress
     168 * @subpackage Cache
     169 * @since 2.0
     170 */
    56171class WP_Object_Cache {
     172
     173        /**
     174         * Cache Directory
     175         *
     176         * @var string
     177         * @access public
     178         */
    57179        var $cache_dir;
     180
     181        /**
     182         * Whether the cache is enabled
     183         *
     184         * @var bool
     185         * @access public
     186         */
    58187        var $cache_enabled = false;
     188
     189        /**
     190         * The expiration time of the cache files
     191         *
     192         * @var int
     193         * @access public
     194         */
    59195        var $expiration_time = 900;
     196
     197        /**
     198         * The filename of the 'flock' or file lock
     199         *
     200         * @var string
     201         * @access public
     202         */
    60203        var $flock_filename = 'wp_object_cache.lock';
     204
     205        /**
     206         * The resource handle for the file lock
     207         *
     208         * @var resource
     209         * @access private
     210         */
    61211        var $mutex;
     212
     213        /**
     214         * Holds the cached objects
     215         *
     216         * @var array
     217         * @access private
     218         */
    62219        var $cache = array ();
     220
     221        /**
     222         * Objects in cache that have become "dirty"
     223         *
     224         * "Dirty" refers to an cache that has since been updated
     225         * in the "live" environment, but had not yet cleared the
     226         * cache referring to that update.
     227         *
     228         * @var array
     229         * @access private
     230         */
    63231        var $dirty_objects = array ();
     232
     233        /**
     234         * {@internal Missing Description}}
     235         *
     236         * @var array
     237         * @access private
     238         */
    64239        var $non_existant_objects = array ();
     240
     241        /**
     242         * Object caches that are global
     243         *
     244         * @var array
     245         * @access private
     246         */
    65247        var $global_groups = array ('users', 'userlogins', 'usermeta');
     248
     249        /**
     250         * Object caches that don't persist
     251         *
     252         * @var array
     253         * @access private
     254         */
    66255        var $non_persistent_groups = array('comment');
     256
     257        /**
     258         * Holds the blog id that the object cache refers to
     259         *
     260         * @var int
     261         * @access public
     262         */
    67263        var $blog_id;
     264
     265        /**
     266         * {@internal Missing Description}}
     267         *
     268         * @var int
     269         * @access public
     270         */
    68271        var $cold_cache_hits = 0;
     272
     273        /**
     274         * {@internal Missing Description}}
     275         *
     276         * @var int
     277         * @access public
     278         */
    69279        var $warm_cache_hits = 0;
     280
     281        /**
     282         * {@internal Missing Description}}
     283         *
     284         * @var int
     285         */
    70286        var $cache_misses = 0;
     287
     288        /**
     289         * {@internal Missing Description}}
     290         *
     291         * @var string
     292         */
    71293        var $secret = '';
    72294
     295        /**
     296         * Creates a mutex to attempt a lock on a cached file.
     297         *
     298         * The lock will be attempted to be preformed on cached files
     299         * to prevent collisions between multiple caches/access attempts.
     300         *
     301         * @since 2.0.1
     302         *
     303         * @return bool Whether the lock could be acquired
     304         */
    73305        function acquire_lock() {
    74306                // Acquire a write lock.
    75307                $this->mutex = @fopen($this->cache_dir.$this->flock_filename, 'w');
     
    79311                return true;
    80312        }
    81313
     314        /**
     315         * {@internal Missing Short Description}}
     316         *
     317         * {@internal Missing Long Description}}
     318         *
     319         * @since unknown
     320         *
     321         * @param unknown_type $id {@internal Missing Description}}
     322         * @param unknown_type $data {@internal Missing Description}}
     323         * @param unknown_type $group {@internal Missing Description}}
     324         * @param unknown_type $expire {@internal Missing Description}}
     325         * @return bool|unknown {@internal Missing Description}}
     326         */
    82327        function add($id, $data, $group = 'default', $expire = '') {
    83328                if (empty ($group))
    84329                        $group = 'default';
     
    89334                return $this->set($id, $data, $group, $expire);
    90335        }
    91336
     337        /**
     338         * {@internal Missing Short Description}}
     339         *
     340         * {@internal Missing Long Description}}
     341         *
     342         * @since unknown
     343         *
     344         * @param unknown_type $id
     345         * @param unknown_type $group
     346         * @param unknown_type $force
     347         * @return unknown
     348         */
    92349        function delete($id, $group = 'default', $force = false) {
    93350                if (empty ($group))
    94351                        $group = 'default';
     
    102359                return true;
    103360        }
    104361
     362        /**
     363         * {@internal Missing Short Description}}
     364         *
     365         * {@internal Missing Long Description}}
     366         *
     367         * @since unknown
     368         *
     369         * @return unknown
     370         */
    105371        function flush() {
    106372                if ( !$this->cache_enabled )
    107373                        return true;
     
    119385                return true;
    120386        }
    121387
     388        /**
     389         * {@internal Missing Short Description}}
     390         *
     391         * {@internal Missing Long Description}}
     392         *
     393         * @since unknown
     394         *
     395         * @param unknown_type $id
     396         * @param unknown_type $group
     397         * @param unknown_type $count_hits
     398         * @return unknown
     399         */
    122400        function get($id, $group = 'default', $count_hits = true) {
    123401                if (empty ($group))
    124402                        $group = 'default';
     
    171449                return $this->cache[$group][$id];
    172450        }
    173451
     452        /**
     453         * {@internal Missing Short Description}}
     454         *
     455         * {@internal Missing Long Description}}
     456         *
     457         * @since unknown
     458         *
     459         * @param unknown_type $group
     460         * @return unknown
     461         */
    174462        function get_group_dir($group) {
    175463                if (false !== array_search($group, $this->global_groups))
    176464                        return $group;
     
    178466                return "{$this->blog_id}/$group";
    179467        }
    180468
     469        /**
     470         * {@internal Missing Short Description}}
     471         *
     472         * {@internal Missing Long Description}}
     473         *
     474         * @since unknown
     475         *
     476         * @param unknown_type $data
     477         * @return unknown
     478         */
    181479        function hash($data) {
    182480                if ( function_exists('hash_hmac') ) {
    183481                        return hash_hmac('md5', $data, $this->secret);
     
    186484                }
    187485        }
    188486
     487        /**
     488         * {@internal Missing Short Description}}
     489         *
     490         * {@internal Missing Long Description}}
     491         *
     492         * @since unknown
     493         *
     494         * @param unknown_type $group
     495         */
    189496        function load_group_from_db($group) {
    190497                return;
    191498        }
    192499
     500        /**
     501         * {@internal Missing Short Description}}
     502         *
     503         * {@internal Missing Long Description}}
     504         *
     505         * @since unknown
     506         *
     507         * @param unknown_type $group
     508         * @param unknown_type $perms
     509         * @return unknown
     510         */
    193511        function make_group_dir($group, $perms) {
    194512                $group_dir = $this->get_group_dir($group);
    195513                $make_dir = '';
     
    211529                return $this->cache_dir."$group_dir/";
    212530        }
    213531
     532        /**
     533         * {@internal Missing Short Description}}
     534         *
     535         * {@internal Missing Long Description}}
     536         *
     537         * @since unknown
     538         *
     539         * @return unknown
     540         */
    214541        function rm_cache_dir() {
    215542                $dir = $this->cache_dir;
    216543                $dir = rtrim($dir, DIRECTORY_SEPARATOR);
     
    247574
    248575        }
    249576
     577        /**
     578         * {@internal Missing Short Description}}
     579         *
     580         * {@internal Missing Long Description}}
     581         *
     582         * @since unknown
     583         *
     584         */
    250585        function release_lock() {
    251586                // Release write lock.
    252587                flock($this->mutex, LOCK_UN);
    253588                fclose($this->mutex);
    254589        }
    255590
     591        /**
     592         * {@internal Missing Short Description}}
     593         *
     594         * {@internal Missing Long Description}}
     595         *
     596         * @since unknown
     597         *
     598         * @param unknown_type $id
     599         * @param unknown_type $data
     600         * @param unknown_type $group
     601         * @param unknown_type $expire
     602         * @return unknown
     603         */
    256604        function replace($id, $data, $group = 'default', $expire = '') {
    257605                if (empty ($group))
    258606                        $group = 'default';
     
    263611                return $this->set($id, $data, $group, $expire);
    264612        }
    265613
     614        /**
     615         * {@internal Missing Short Description}}
     616         *
     617         * {@internal Missing Long Description}}
     618         *
     619         * @since unknown
     620         *
     621         * @param unknown_type $id
     622         * @param unknown_type $data
     623         * @param unknown_type $group
     624         * @param unknown_type $expire
     625         * @return unknown
     626         */
    266627        function set($id, $data, $group = 'default', $expire = '') {
    267628                if (empty ($group))
    268629                        $group = 'default';
     
    277638                return true;
    278639        }
    279640
     641        /**
     642         * {@internal Missing Short Description}}
     643         *
     644         * {@internal Missing Long Description}}
     645         *
     646         * @since unknown
     647         *
     648         * @return unknown
     649         */
    280650        function save() {
    281651                //$this->stats();
    282652
     
    353723                return true;
    354724        }
    355725
     726        /**
     727         * {@internal Missing Short Description}}
     728         *
     729         * {@internal Missing Long Description}}
     730         *
     731         * @since unknown
     732         */
    356733        function stats() {
    357734                echo "<p>";
    358735                echo "<strong>Cold Cache Hits:</strong> {$this->cold_cache_hits}<br />";
     
    377754                }
    378755        }
    379756
     757        /**
     758         * Calls PHP 5 style constructor and sets up PHP 4 destructor
     759         *
     760         * @since 2.0
     761         *
     762         * @return WP_Object_Cache
     763         */
    380764        function WP_Object_Cache() {
    381765                return $this->__construct();
    382766        }
    383767
     768        /**
     769         * Sets up object properties
     770         *
     771         * @since unknown
     772         */
    384773        function __construct() {
    385774                global $blog_id;
    386775
     
    421810                $this->blog_id = $this->hash($blog_id);
    422811        }
    423812
     813        /**
     814         * Will save the object cache before object is completely destroyed.
     815         *
     816         * Called upon object destruction, which should be when PHP ends.
     817         *
     818         * @return bool Won't be used by PHP
     819         */
    424820        function __destruct() {
    425821                $this->save();
    426822                return true;