Ticket #5511: cache.phpdoc.r6473.diff

File cache.phpdoc.r6473.diff, 11.7 kB (added by darkdragon, 10 months ago)

Incomplete documentation for cache.php based off of r6473

  • cache.php

    old new  
    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;