Merge branch 'MDL-39472-master' of git://github.com/sammarshallou/moodle
[moodle.git] / cache / classes / loaders.php
1 <?php
2 // This file is part of Moodle - http://moodle.org/
3 //
4 // Moodle is free software: you can redistribute it and/or modify
5 // it under the terms of the GNU General Public License as published by
6 // the Free Software Foundation, either version 3 of the License, or
7 // (at your option) any later version.
8 //
9 // Moodle is distributed in the hope that it will be useful,
10 // but WITHOUT ANY WARRANTY; without even the implied warranty of
11 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
12 // GNU General Public License for more details.
13 //
14 // You should have received a copy of the GNU General Public License
15 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
17 /**
18  * Cache loaders
19  *
20  * This file is part of Moodle's cache API, affectionately called MUC.
21  * It contains the components that are required in order to use caching.
22  *
23  * @package    core
24  * @category   cache
25  * @copyright  2012 Sam Hemelryk
26  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
27  */
29 defined('MOODLE_INTERNAL') || die();
31 /**
32  * The main cache class.
33  *
34  * This class if the first class that any end developer will interact with.
35  * In order to create an instance of a cache that they can work with they must call one of the static make methods belonging
36  * to this class.
37  *
38  * @package    core
39  * @category   cache
40  * @copyright  2012 Sam Hemelryk
41  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
42  */
43 class cache implements cache_loader {
45     /**
46      * We need a timestamp to use within the cache API.
47      * This stamp needs to be used for all ttl and time based operations to ensure that we don't end up with
48      * timing issues.
49      * @var int
50      */
51     protected static $now;
53     /**
54      * The definition used when loading this cache if there was one.
55      * @var cache_definition
56      */
57     private $definition = false;
59     /**
60      * The cache store that this loader will make use of.
61      * @var cache_store
62      */
63     private $store;
65     /**
66      * The next cache loader in the chain if there is one.
67      * If a cache request misses for the store belonging to this loader then the loader
68      * stored here will be checked next.
69      * If there is a loader here then $datasource must be false.
70      * @var cache_loader|false
71      */
72     private $loader = false;
74     /**
75      * The data source to use if we need to load data (because if doesn't exist in the cache store).
76      * If there is a data source here then $loader above must be false.
77      * @var cache_data_source|false
78      */
79     private $datasource = false;
81     /**
82      * Used to quickly check if the store supports key awareness.
83      * This is set when the cache is initialised and is used to speed up processing.
84      * @var bool
85      */
86     private $supportskeyawareness = null;
88     /**
89      * Used to quickly check if the store supports ttl natively.
90      * This is set when the cache is initialised and is used to speed up processing.
91      * @var bool
92      */
93     private $supportsnativettl = null;
95     /**
96      * Gets set to true if the cache is going to be using the build in static "persist" cache.
97      * The persist cache statically caches items used during the lifetime of the request. This greatly speeds up interaction
98      * with the cache in areas where it will be repetitively hit for the same information such as with strings.
99      * There are several other variables to control how this persist cache works.
100      * @var bool
101      */
102     private $persist = false;
104     /**
105      * The persist cache itself.
106      * Items will be stored in this cache as they were provided. This ensure there is no unnecessary processing taking place.
107      * @var array
108      */
109     private $persistcache = array();
111     /**
112      * The number of items in the persist cache. Avoids count calls like you wouldn't believe.
113      * @var int
114      */
115     private $persistcount = 0;
117     /**
118      * An array containing just the keys being used in the persist cache.
119      * This seems redundant perhaps but is used when managing the size of the persist cache.
120      * @var array
121      */
122     private $persistkeys = array();
124     /**
125      * The maximum size of the persist cache. If set to false there is no max size.
126      * Caches that make use of the persist cache should seriously consider setting this to something reasonably small, but
127      * still large enough to offset repetitive calls.
128      * @var int|false
129      */
130     private $persistmaxsize = false;
132     /**
133      * Gets set to true during initialisation if the definition is making use of a ttl.
134      * Used to speed up processing.
135      * @var bool
136      */
137     private $hasattl = false;
139     /**
140      * Gets set to the class name of the store during initialisation. This is used several times in the cache class internally
141      * and having it here helps speed up processing.
142      * @var strubg
143      */
144     protected $storetype = 'unknown';
146     /**
147      * Gets set to true if we want to collect performance information about the cache API.
148      * @var bool
149      */
150     protected $perfdebug = false;
152     /**
153      * Determines if this loader is a sub loader, not the top of the chain.
154      * @var bool
155      */
156     protected $subloader = false;
158     /**
159      * Creates a new cache instance for a pre-defined definition.
160      *
161      * @param string $component The component for the definition
162      * @param string $area The area for the definition
163      * @param array $identifiers Any additional identifiers that should be provided to the definition.
164      * @param string $aggregate Super advanced feature. More docs later.
165      * @return cache_application|cache_session|cache_store
166      */
167     public static function make($component, $area, array $identifiers = array(), $aggregate = null) {
168         $factory = cache_factory::instance();
169         return $factory->create_cache_from_definition($component, $area, $identifiers, $aggregate);
170     }
172     /**
173      * Creates a new cache instance based upon the given params.
174      *
175      * @param int $mode One of cache_store::MODE_*
176      * @param string $component The component this cache relates to.
177      * @param string $area The area this cache relates to.
178      * @param array $identifiers Any additional identifiers that should be provided to the definition.
179      * @param array $options An array of options, available options are:
180      *   - simplekeys : Set to true if the keys you will use are a-zA-Z0-9_
181      *   - simpledata : Set to true if the type of the data you are going to store is scalar, or an array of scalar vars
182      *   - persistent : If set to true the cache will persist construction requests.
183      * @return cache_application|cache_session|cache_store
184      */
185     public static function make_from_params($mode, $component, $area, array $identifiers = array(), array $options = array()) {
186         $factory = cache_factory::instance();
187         return $factory->create_cache_from_params($mode, $component, $area, $identifiers, $options);
188     }
190     /**
191      * Constructs a new cache instance.
192      *
193      * You should not call this method from your code, instead you should use the cache::make methods.
194      *
195      * This method is public so that the cache_factory is able to instantiate cache instances.
196      * Ideally we would make this method protected and expose its construction to the factory method internally somehow.
197      * The factory class is responsible for this in order to centralise the storage of instances once created. This way if needed
198      * we can force a reset of the cache API (used during unit testing).
199      *
200      * @param cache_definition $definition The definition for the cache instance.
201      * @param cache_store $store The store that cache should use.
202      * @param cache_loader|cache_data_source $loader The next loader in the chain or the data source if there is one and there
203      *      are no other cache_loaders in the chain.
204      */
205     public function __construct(cache_definition $definition, cache_store $store, $loader = null) {
206         global $CFG;
207         $this->definition = $definition;
208         $this->store = $store;
209         $this->storetype = get_class($store);
210         $this->perfdebug = !empty($CFG->perfdebug);
211         if ($loader instanceof cache_loader) {
212             $this->loader = $loader;
213             // Mark the loader as a sub (chained) loader.
214             $this->loader->set_is_sub_loader(true);
215         } else if ($loader instanceof cache_data_source) {
216             $this->datasource = $loader;
217         }
218         $this->definition->generate_definition_hash();
219         $this->persist = $this->definition->should_be_persistent();
220         if ($this->persist) {
221             $this->persistmaxsize = $this->definition->get_persistent_max_size();
222         }
223         $this->hasattl = ($this->definition->get_ttl() > 0);
224     }
226     /**
227      * Used to inform the loader of its state as a sub loader, or as the top of the chain.
228      *
229      * This is important as it ensures that we do not have more than one loader keeping persistent data.
230      * Subloaders need to be "pure" loaders in the sense that they are used to store and retrieve information from stores or the
231      * next loader/data source in the chain.
232      * Nothing fancy, nothing flash.
233      *
234      * @param bool $setting
235      */
236     protected function set_is_sub_loader($setting = true) {
237         if ($setting) {
238             $this->subloader = true;
239             // Subloaders should not keep persistent data.
240             $this->persist = false;
241             $this->persistmaxsize = false;
242         } else {
243             $this->subloader = true;
244             $this->persist = $this->definition->should_be_persistent();
245             if ($this->persist) {
246                 $this->persistmaxsize = $this->definition->get_persistent_max_size();
247             }
248         }
249     }
251     /**
252      * Alters the identifiers that have been provided to the definition.
253      *
254      * This is an advanced method and should not be used unless really needed.
255      * It allows the developer to slightly alter the definition without having to re-establish the cache.
256      * It will cause more processing as the definition will need to clear and reprepare some of its properties.
257      *
258      * @param array $identifiers
259      */
260     public function set_identifiers(array $identifiers) {
261         $this->definition->set_identifiers($identifiers);
262     }
264     /**
265      * Retrieves the value for the given key from the cache.
266      *
267      * @param string|int $key The key for the data being requested.
268      *      It can be any structure although using a scalar string or int is recommended in the interests of performance.
269      *      In advanced cases an array may be useful such as in situations requiring the multi-key functionality.
270      * @param int $strictness One of IGNORE_MISSING | MUST_EXIST
271      * @return mixed|false The data from the cache or false if the key did not exist within the cache.
272      * @throws moodle_exception
273      */
274     public function get($key, $strictness = IGNORE_MISSING) {
275         // 1. Parse the key.
276         $parsedkey = $this->parse_key($key);
277         // 2. Get it from the persist cache if we can (only when persist is enabled and it has already been requested/set).
278         $result = false;
279         if ($this->is_using_persist_cache()) {
280             $result = $this->get_from_persist_cache($parsedkey);
281         }
282         if ($result !== false) {
283             if (!is_scalar($result)) {
284                 // If data is an object it will be a reference.
285                 // If data is an array if may contain references.
286                 // We want to break references so that the cache cannot be modified outside of itself.
287                 // Call the function to unreference it (in the best way possible).
288                 $result = $this->unref($result);
289             }
290             return $result;
291         }
292         // 3. Get it from the store. Obviously wasn't in the persist cache.
293         $result = $this->store->get($parsedkey);
294         if ($result !== false) {
295             if ($result instanceof cache_ttl_wrapper) {
296                 if ($result->has_expired()) {
297                     $this->store->delete($parsedkey);
298                     $result = false;
299                 } else {
300                     $result = $result->data;
301                 }
302             }
303             if ($result instanceof cache_cached_object) {
304                 $result = $result->restore_object();
305             }
306             if ($this->is_using_persist_cache()) {
307                 $this->set_in_persist_cache($parsedkey, $result);
308             }
309         }
310         // 4. Load if from the loader/datasource if we don't already have it.
311         $setaftervalidation = false;
312         if ($result === false) {
313             if ($this->perfdebug) {
314                 cache_helper::record_cache_miss($this->storetype, $this->definition->get_id());
315             }
316             if ($this->loader !== false) {
317                 // We must pass the original (unparsed) key to the next loader in the chain.
318                 // The next loader will parse the key as it sees fit. It may be parsed differently
319                 // depending upon the capabilities of the store associated with the loader.
320                 $result = $this->loader->get($key);
321             } else if ($this->datasource !== false) {
322                 $result = $this->datasource->load_for_cache($key);
323             }
324             $setaftervalidation = ($result !== false);
325         } else if ($this->perfdebug) {
326             cache_helper::record_cache_hit($this->storetype, $this->definition->get_id());
327         }
328         // 5. Validate strictness.
329         if ($strictness === MUST_EXIST && $result === false) {
330             throw new moodle_exception('Requested key did not exist in any cache stores and could not be loaded.');
331         }
332         // 6. Set it to the store if we got it from the loader/datasource.
333         if ($setaftervalidation) {
334             $this->set($key, $result);
335         }
336         // 7. Make sure we don't pass back anything that could be a reference.
337         //    We don't want people modifying the data in the cache.
338         if (!is_scalar($result)) {
339             // If data is an object it will be a reference.
340             // If data is an array if may contain references.
341             // We want to break references so that the cache cannot be modified outside of itself.
342             // Call the function to unreference it (in the best way possible).
343             $result = $this->unref($result);
344         }
345         return $result;
346     }
348     /**
349      * Retrieves an array of values for an array of keys.
350      *
351      * Using this function comes with potential performance implications.
352      * Not all cache stores will support get_many/set_many operations and in order to replicate this functionality will call
353      * the equivalent singular method for each item provided.
354      * This should not deter you from using this function as there is a performance benefit in situations where the cache store
355      * does support it, but you should be aware of this fact.
356      *
357      * @param array $keys The keys of the data being requested.
358      *      Each key can be any structure although using a scalar string or int is recommended in the interests of performance.
359      *      In advanced cases an array may be useful such as in situations requiring the multi-key functionality.
360      * @param int $strictness One of IGNORE_MISSING or MUST_EXIST.
361      * @return array An array of key value pairs for the items that could be retrieved from the cache.
362      *      If MUST_EXIST was used and not all keys existed within the cache then an exception will be thrown.
363      *      Otherwise any key that did not exist will have a data value of false within the results.
364      * @throws moodle_exception
365      */
366     public function get_many(array $keys, $strictness = IGNORE_MISSING) {
368         $keysparsed = array();
369         $parsedkeys = array();
370         $resultpersist = array();
371         $resultstore = array();
372         $keystofind = array();
374         // First up check the persist cache for each key.
375         $isusingpersist = $this->is_using_persist_cache();
376         foreach ($keys as $key) {
377             $pkey = $this->parse_key($key);
378             $keysparsed[$key] = $pkey;
379             $parsedkeys[$pkey] = $key;
380             $keystofind[$pkey] = $key;
381             if ($isusingpersist) {
382                 $value = $this->get_from_persist_cache($pkey);
383                 if ($value !== false) {
384                     $resultpersist[$pkey] = $value;
385                     unset($keystofind[$pkey]);
386                 }
387             }
388         }
390         // Next assuming we didn't find all of the keys in the persist cache try loading them from the store.
391         if (count($keystofind)) {
392             $resultstore = $this->store->get_many(array_keys($keystofind));
393             // Process each item in the result to "unwrap" it.
394             foreach ($resultstore as $key => $value) {
395                 if ($value instanceof cache_ttl_wrapper) {
396                     if ($value->has_expired()) {
397                         $value = false;
398                     } else {
399                         $value = $value->data;
400                     }
401                 }
402                 if ($value instanceof cache_cached_object) {
403                     $value = $value->restore_object();
404                 }
405                 $resultstore[$key] = $value;
406             }
407         }
409         // Merge the result from the persis cache with the results from the store load.
410         $result = $resultpersist + $resultstore;
411         unset($resultpersist);
412         unset($resultstore);
414         // Next we need to find any missing values and load them from the loader/datasource next in the chain.
415         $usingloader = ($this->loader !== false);
416         $usingsource = (!$usingloader && ($this->datasource !== false));
417         if ($usingloader || $usingsource) {
418             $missingkeys = array();
419             foreach ($result as $key => $value) {
420                 if ($value === false) {
421                     $missingkeys[] = ($usingloader) ? $key : $parsedkeys[$key];
422                 }
423             }
424             if (!empty($missingkeys)) {
425                 if ($usingloader) {
426                     $resultmissing = $this->loader->get_many($missingkeys);
427                 } else {
428                     $resultmissing = $this->datasource->load_many_for_cache($missingkeys);
429                 }
430                 foreach ($resultmissing as $key => $value) {
431                     $pkey = ($usingloader) ? $key : $keysparsed[$key];
432                     $realkey = ($usingloader) ? $parsedkeys[$key] : $key;
433                     $result[$pkey] = $value;
434                     if ($value !== false) {
435                         $this->set($realkey, $value);
436                     }
437                 }
438                 unset($resultmissing);
439             }
440             unset($missingkeys);
441         }
443         // Create an array with the original keys and the found values. This will be what we return.
444         $fullresult = array();
445         foreach ($result as $key => $value) {
446             $fullresult[$parsedkeys[$key]] = $value;
447         }
448         unset($result);
450         // Final step is to check strictness.
451         if ($strictness === MUST_EXIST) {
452             foreach ($keys as $key) {
453                 if (!array_key_exists($key, $fullresult)) {
454                     throw new moodle_exception('Not all the requested keys existed within the cache stores.');
455                 }
456             }
457         }
459         // Return the result. Phew!
460         return $fullresult;
461     }
463     /**
464      * Sends a key => value pair to the cache.
465      *
466      * <code>
467      * // This code will add four entries to the cache, one for each url.
468      * $cache->set('main', 'http://moodle.org');
469      * $cache->set('docs', 'http://docs.moodle.org');
470      * $cache->set('tracker', 'http://tracker.moodle.org');
471      * $cache->set('qa', 'http://qa.moodle.net');
472      * </code>
473      *
474      * @param string|int $key The key for the data being requested.
475      *      It can be any structure although using a scalar string or int is recommended in the interests of performance.
476      *      In advanced cases an array may be useful such as in situations requiring the multi-key functionality.
477      * @param mixed $data The data to set against the key.
478      * @return bool True on success, false otherwise.
479      */
480     public function set($key, $data) {
481         if ($this->perfdebug) {
482             cache_helper::record_cache_set($this->storetype, $this->definition->get_id());
483         }
484         if (is_object($data) && $data instanceof cacheable_object) {
485             $data = new cache_cached_object($data);
486         } else if (!is_scalar($data)) {
487             // If data is an object it will be a reference.
488             // If data is an array if may contain references.
489             // We want to break references so that the cache cannot be modified outside of itself.
490             // Call the function to unreference it (in the best way possible).
491             $data = $this->unref($data);
492         }
493         if ($this->has_a_ttl() && !$this->store_supports_native_ttl()) {
494             $data = new cache_ttl_wrapper($data, $this->definition->get_ttl());
495         }
496         $parsedkey = $this->parse_key($key);
497         if ($this->is_using_persist_cache()) {
498             $this->set_in_persist_cache($parsedkey, $data);
499         }
500         return $this->store->set($parsedkey, $data);
501     }
503     /**
504      * Removes references where required.
505      *
506      * @param stdClass|array $data
507      */
508     protected function unref($data) {
509         if ($this->definition->uses_simple_data()) {
510             return $data;
511         }
512         // Check if it requires serialisation in order to produce a reference free copy.
513         if ($this->requires_serialisation($data)) {
514             // Damn, its going to have to be serialise.
515             $data = serialize($data);
516             // We unserialise immediately so that we don't have to do it every time on get.
517             $data = unserialize($data);
518         } else if (!is_scalar($data)) {
519             // Its safe to clone, lets do it, its going to beat the pants of serialisation.
520             $data = $this->deep_clone($data);
521         }
522         return $data;
523     }
525     /**
526      * Checks to see if a var requires serialisation.
527      *
528      * @param mixed $value The value to check.
529      * @param int $depth Used to ensure we don't enter an endless loop (think recursion).
530      * @return bool Returns true if the value is going to require serialisation in order to ensure a reference free copy
531      *      or false if its safe to clone.
532      */
533     protected function requires_serialisation($value, $depth = 1) {
534         if (is_scalar($value)) {
535             return false;
536         } else if (is_array($value) || $value instanceof stdClass || $value instanceof Traversable) {
537             if ($depth > 5) {
538                 // Skrew it, mega-deep object, developer you suck, we're just going to serialise.
539                 return true;
540             }
541             foreach ($value as $key => $subvalue) {
542                 if ($this->requires_serialisation($subvalue, $depth++)) {
543                     return true;
544                 }
545             }
546         }
547         // Its not scalar, array, or stdClass so we'll need to serialise.
548         return true;
549     }
551     /**
552      * Creates a reference free clone of the given value.
553      *
554      * @param mixed $value
555      * @return mixed
556      */
557     protected function deep_clone($value) {
558         if (is_object($value)) {
559             // Objects must be cloned to begin with.
560             $value = clone $value;
561         }
562         if (is_array($value) || is_object($value)) {
563             foreach ($value as $key => $subvalue) {
564                 $value[$key] = $this->deep_clone($subvalue);
565             }
566         }
567         return $value;
568     }
570     /**
571      * Sends several key => value pairs to the cache.
572      *
573      * Using this function comes with potential performance implications.
574      * Not all cache stores will support get_many/set_many operations and in order to replicate this functionality will call
575      * the equivalent singular method for each item provided.
576      * This should not deter you from using this function as there is a performance benefit in situations where the cache store
577      * does support it, but you should be aware of this fact.
578      *
579      * <code>
580      * // This code will add four entries to the cache, one for each url.
581      * $cache->set_many(array(
582      *     'main' => 'http://moodle.org',
583      *     'docs' => 'http://docs.moodle.org',
584      *     'tracker' => 'http://tracker.moodle.org',
585      *     'qa' => ''http://qa.moodle.net'
586      * ));
587      * </code>
588      *
589      * @param array $keyvaluearray An array of key => value pairs to send to the cache.
590      * @return int The number of items successfully set. It is up to the developer to check this matches the number of items.
591      *      ... if they care that is.
592      */
593     public function set_many(array $keyvaluearray) {
594         $data = array();
595         $simulatettl = $this->has_a_ttl() && !$this->store_supports_native_ttl();
596         $usepersistcache = $this->is_using_persist_cache();
597         foreach ($keyvaluearray as $key => $value) {
598             if (is_object($value) && $value instanceof cacheable_object) {
599                 $value = new cache_cached_object($value);
600             } else if (!is_scalar($value)) {
601                 // If data is an object it will be a reference.
602                 // If data is an array if may contain references.
603                 // We want to break references so that the cache cannot be modified outside of itself.
604                 // Call the function to unreference it (in the best way possible).
605                 $value = $this->unref($value);
606             }
607             if ($simulatettl) {
608                 $value = new cache_ttl_wrapper($value, $this->definition->get_ttl());
609             }
610             $data[$key] = array(
611                 'key' => $this->parse_key($key),
612                 'value' => $value
613             );
614             if ($usepersistcache) {
615                 $this->set_in_persist_cache($data[$key]['key'], $value);
616             }
617         }
618         if ($this->perfdebug) {
619             cache_helper::record_cache_set($this->storetype, $this->definition->get_id());
620         }
621         return $this->store->set_many($data);
622     }
624     /**
625      * Test is a cache has a key.
626      *
627      * The use of the has methods is strongly discouraged. In a high load environment the cache may well change between the
628      * test and any subsequent action (get, set, delete etc).
629      * Instead it is recommended to write your code in such a way they it performs the following steps:
630      * <ol>
631      * <li>Attempt to retrieve the information.</li>
632      * <li>Generate the information.</li>
633      * <li>Attempt to set the information</li>
634      * </ol>
635      *
636      * Its also worth mentioning that not all stores support key tests.
637      * For stores that don't support key tests this functionality is mimicked by using the equivalent get method.
638      * Just one more reason you should not use these methods unless you have a very good reason to do so.
639      *
640      * @param string|int $key
641      * @param bool $tryloadifpossible If set to true, the cache doesn't contain the key, and there is another cache loader or
642      *      data source then the code will try load the key value from the next item in the chain.
643      * @return bool True if the cache has the requested key, false otherwise.
644      */
645     public function has($key, $tryloadifpossible = false) {
646         $parsedkey = $this->parse_key($key);
647         if ($this->is_in_persist_cache($parsedkey)) {
648             // Hoorah, that was easy. It exists in the persist cache so we definitely have it.
649             return true;
650         }
651         if ($this->has_a_ttl() && !$this->store_supports_native_ttl()) {
652             // The data has a TTL and the store doesn't support it natively.
653             // We must fetch the data and expect a ttl wrapper.
654             $data = $this->store->get($parsedkey);
655             $has = ($data instanceof cache_ttl_wrapper && !$data->has_expired());
656         } else if (!$this->store_supports_key_awareness()) {
657             // The store doesn't support key awareness, get the data and check it manually... puke.
658             // Either no TTL is set of the store supports its handling natively.
659             $data = $this->store->get($parsedkey);
660             $has = ($data !== false);
661         } else {
662             // The store supports key awareness, this is easy!
663             // Either no TTL is set of the store supports its handling natively.
664             $has = $this->store->has($parsedkey);
665         }
666         if (!$has && $tryloadifpossible) {
667             if ($this->loader !== false) {
668                 $result = $this->loader->get($parsedkey);
669             } else if ($this->datasource !== null) {
670                 $result = $this->datasource->load_for_cache($key);
671             }
672             $has = ($result !== null);
673             if ($has) {
674                 $this->set($key, $result);
675             }
676         }
677         return $has;
678     }
680     /**
681      * Test is a cache has all of the given keys.
682      *
683      * It is strongly recommended to avoid the use of this function if not absolutely required.
684      * In a high load environment the cache may well change between the test and any subsequent action (get, set, delete etc).
685      *
686      * Its also worth mentioning that not all stores support key tests.
687      * For stores that don't support key tests this functionality is mimicked by using the equivalent get method.
688      * Just one more reason you should not use these methods unless you have a very good reason to do so.
689      *
690      * @param array $keys
691      * @return bool True if the cache has all of the given keys, false otherwise.
692      */
693     public function has_all(array $keys) {
694         if (($this->has_a_ttl() && !$this->store_supports_native_ttl()) || !$this->store_supports_key_awareness()) {
695             foreach ($keys as $key) {
696                 if (!$this->has($key)) {
697                     return false;
698                 }
699             }
700             return true;
701         }
702         $parsedkeys = array_map(array($this, 'parse_key'), $keys);
703         return $this->store->has_all($parsedkeys);
704     }
706     /**
707      * Test if a cache has at least one of the given keys.
708      *
709      * It is strongly recommended to avoid the use of this function if not absolutely required.
710      * In a high load environment the cache may well change between the test and any subsequent action (get, set, delete etc).
711      *
712      * Its also worth mentioning that not all stores support key tests.
713      * For stores that don't support key tests this functionality is mimicked by using the equivalent get method.
714      * Just one more reason you should not use these methods unless you have a very good reason to do so.
715      *
716      * @param array $keys
717      * @return bool True if the cache has at least one of the given keys
718      */
719     public function has_any(array $keys) {
720         if (($this->has_a_ttl() && !$this->store_supports_native_ttl()) || !$this->store_supports_key_awareness()) {
721             foreach ($keys as $key) {
722                 if ($this->has($key)) {
723                     return true;
724                 }
725             }
726             return false;
727         }
729         if ($this->is_using_persist_cache()) {
730             $parsedkeys = array();
731             foreach ($keys as $id => $key) {
732                 $parsedkey = $this->parse_key($key);
733                 if ($this->is_in_persist_cache($parsedkey)) {
734                     return true;
735                 }
736                 $parsedkeys[] = $parsedkey;
737             }
738         } else {
739             $parsedkeys = array_map(array($this, 'parse_key'), $keys);
740         }
741         return $this->store->has_any($parsedkeys);
742     }
744     /**
745      * Delete the given key from the cache.
746      *
747      * @param string|int $key The key to delete.
748      * @param bool $recurse When set to true the key will also be deleted from all stacked cache loaders and their stores.
749      *     This happens by default and ensure that all the caches are consistent. It is NOT recommended to change this.
750      * @return bool True of success, false otherwise.
751      */
752     public function delete($key, $recurse = true) {
753         $parsedkey = $this->parse_key($key);
754         $this->delete_from_persist_cache($parsedkey);
755         if ($recurse && $this->loader !== false) {
756             // Delete from the bottom of the stack first.
757             $this->loader->delete($key, $recurse);
758         }
759         return $this->store->delete($parsedkey);
760     }
762     /**
763      * Delete all of the given keys from the cache.
764      *
765      * @param array $keys The key to delete.
766      * @param bool $recurse When set to true the key will also be deleted from all stacked cache loaders and their stores.
767      *     This happens by default and ensure that all the caches are consistent. It is NOT recommended to change this.
768      * @return int The number of items successfully deleted.
769      */
770     public function delete_many(array $keys, $recurse = true) {
771         $parsedkeys = array_map(array($this, 'parse_key'), $keys);
772         if ($this->is_using_persist_cache()) {
773             foreach ($parsedkeys as $parsedkey) {
774                 $this->delete_from_persist_cache($parsedkey);
775             }
776         }
777         if ($recurse && $this->loader !== false) {
778             // Delete from the bottom of the stack first.
779             $this->loader->delete_many($keys, $recurse);
780         }
781         return $this->store->delete_many($parsedkeys);
782     }
784     /**
785      * Purges the cache store, and loader if there is one.
786      *
787      * @return bool True on success, false otherwise
788      */
789     public function purge() {
790         // 1. Purge the persist cache.
791         $this->persistcache = array();
792         // 2. Purge the store.
793         $this->store->purge();
794         // 3. Optionally pruge any stacked loaders.
795         if ($this->loader) {
796             $this->loader->purge();
797         }
798         return true;
799     }
801     /**
802      * Parses the key turning it into a string (or array is required) suitable to be passed to the cache store.
803      *
804      * @param string|int $key As passed to get|set|delete etc.
805      * @return string|array String unless the store supports multi-identifiers in which case an array if returned.
806      */
807     protected function parse_key($key) {
808         // First up if the store supports multiple keys we'll go with that.
809         if ($this->store->supports_multiple_identifiers()) {
810             $result = $this->definition->generate_multi_key_parts();
811             $result['key'] = $key;
812             return $result;
813         }
814         // If not we need to generate a hash and to for that we use the cache_helper.
815         return cache_helper::hash_key($key, $this->definition);
816     }
818     /**
819      * Returns true if the cache is making use of a ttl.
820      * @return bool
821      */
822     protected function has_a_ttl() {
823         return $this->hasattl;
824     }
826     /**
827      * Returns true if the cache store supports native ttl.
828      * @return bool
829      */
830     protected function store_supports_native_ttl() {
831         if ($this->supportsnativettl === null) {
832             $this->supportsnativettl = ($this->store->supports_native_ttl());
833         }
834         return $this->supportsnativettl;
835     }
837     /**
838      * Returns the cache definition.
839      *
840      * @return cache_definition
841      */
842     protected function get_definition() {
843         return $this->definition;
844     }
846     /**
847      * Returns the cache store
848      *
849      * @return cache_store
850      */
851     protected function get_store() {
852         return $this->store;
853     }
855     /**
856      * Returns the loader associated with this instance.
857      *
858      * @since 2.4.4
859      * @return cache_loader|false
860      */
861     protected function get_loader() {
862         return $this->loader;
863     }
865     /**
866      * Returns the data source associated with this cache.
867      *
868      * @since 2.4.4
869      * @return cache_data_source|false
870      */
871     protected function get_datasource() {
872         return $this->datasource;
873     }
875     /**
876      * Returns true if the store supports key awareness.
877      *
878      * @return bool
879      */
880     protected function store_supports_key_awareness() {
881         if ($this->supportskeyawareness === null) {
882             $this->supportskeyawareness = ($this->store instanceof cache_is_key_aware);
883         }
884         return $this->supportskeyawareness;
885     }
887     /**
888      * Returns true if the store natively supports locking.
889      *
890      * @return bool
891      */
892     protected function store_supports_native_locking() {
893         if ($this->nativelocking === null) {
894             $this->nativelocking = ($this->store instanceof cache_is_lockable);
895         }
896         return $this->nativelocking;
897     }
899     /**
900      * Returns true if this cache is making use of the persist cache.
901      *
902      * @return bool
903      */
904     protected function is_using_persist_cache() {
905         return $this->persist;
906     }
908     /**
909      * Returns true if the requested key exists within the persist cache.
910      *
911      * @param string $key The parsed key
912      * @return bool
913      */
914     protected function is_in_persist_cache($key) {
915         // This method of checking if an array was supplied is faster than is_array.
916         if ($key === (array)$key) {
917             $key = $key['key'];
918         }
919         // This could be written as a single line, however it has been split because the ttl check is faster than the instanceof
920         // and has_expired calls.
921         if (!$this->persist || !array_key_exists($key, $this->persistcache)) {
922             return false;
923         }
924         if ($this->has_a_ttl() && $this->store_supports_native_ttl()) {
925              return !($this->persistcache[$key] instanceof cache_ttl_wrapper && $this->persistcache[$key]->has_expired());
926         }
927         return true;
928     }
930     /**
931      * Returns the item from the persist cache if it exists there.
932      *
933      * @param string $key The parsed key
934      * @return mixed|false The data from the persist cache or false if it wasn't there.
935      */
936     protected function get_from_persist_cache($key) {
937         // This method of checking if an array was supplied is faster than is_array.
938         if ($key === (array)$key) {
939             $key = $key['key'];
940         }
941         // This isset check is faster than array_key_exists but will return false
942         // for null values, meaning null values will come from backing store not
943         // the persist cache. We think this okay because null usage should be
944         // very rare (see comment in MDL-39472).
945         if (!$this->persist || !isset($this->persistcache[$key])) {
946             $result = false;
947         } else {
948             $data = $this->persistcache[$key];
949             if (!$this->has_a_ttl() || !$data instanceof cache_ttl_wrapper) {
950                 if ($data instanceof cache_cached_object) {
951                     $data = $data->restore_object();
952                 }
953                 $result = $data;
954             } else if ($data->has_expired()) {
955                 $this->delete_from_persist_cache($key);
956                 $result = false;
957             } else {
958                 if ($data instanceof cache_cached_object) {
959                     $data = $data->restore_object();
960                 }
961                 $result = $data->data;
962             }
963         }
964         if ($result) {
965             if ($this->perfdebug) {
966                 cache_helper::record_cache_hit('** static persist **', $this->definition->get_id());
967             }
968             return $result;
969         } else {
970             if ($this->perfdebug) {
971                 cache_helper::record_cache_miss('** static persist **', $this->definition->get_id());
972             }
973             return false;
974         }
975     }
977     /**
978      * Sets a key value pair into the persist cache.
979      *
980      * @param string $key The parsed key
981      * @param mixed $data
982      * @return bool
983      */
984     protected function set_in_persist_cache($key, $data) {
985         // This method of checking if an array was supplied is faster than is_array.
986         if ($key === (array)$key) {
987             $key = $key['key'];
988         }
989         $this->persistcache[$key] = $data;
990         if ($this->persistmaxsize !== false) {
991             $this->persistcount++;
992             if ($this->persistcount > $this->persistmaxsize) {
993                 $dropkey = array_shift($this->persistkeys);
994                 unset($this->persistcache[$dropkey]);
995                 $this->persistcount--;
996             }
997         }
998         return true;
999     }
1001     /**
1002      * Deletes an item from the persist cache.
1003      *
1004      * @param string|int $key As given to get|set|delete
1005      * @return bool True on success, false otherwise.
1006      */
1007     protected function delete_from_persist_cache($key) {
1008         unset($this->persistcache[$key]);
1009         if ($this->persistmaxsize !== false) {
1010             $dropkey = array_search($key, $this->persistkeys);
1011             if ($dropkey) {
1012                 unset($this->persistkeys[$dropkey]);
1013                 $this->persistcount--;
1014             }
1015         }
1016         return true;
1017     }
1019     /**
1020      * Returns the timestamp from the first request for the time from the cache API.
1021      *
1022      * This stamp needs to be used for all ttl and time based operations to ensure that we don't end up with
1023      * timing issues.
1024      *
1025      * @return int
1026      */
1027     public static function now() {
1028         if (self::$now === null) {
1029             self::$now = time();
1030         }
1031         return self::$now;
1032     }
1035 /**
1036  * An application cache.
1037  *
1038  * This class is used for application caches returned by the cache::make methods.
1039  * On top of the standard functionality it also allows locking to be required and or manually operated.
1040  *
1041  * This cache class should never be interacted with directly. Instead you should always use the cache::make methods.
1042  * It is technically possible to call those methods through this class however there is no guarantee that you will get an
1043  * instance of this class back again.
1044  *
1045  * @internal don't use me directly.
1046  *
1047  * @package    core
1048  * @category   cache
1049  * @copyright  2012 Sam Hemelryk
1050  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
1051  */
1052 class cache_application extends cache implements cache_loader_with_locking {
1054     /**
1055      * Lock identifier.
1056      * This is used to ensure the lock belongs to the cache instance + definition + user.
1057      * @var string
1058      */
1059     protected $lockidentifier;
1061     /**
1062      * Gets set to true if the cache's primary store natively supports locking.
1063      * If it does then we use that, otherwise we need to instantiate a second store to use for locking.
1064      * @var cache_store
1065      */
1066     protected $nativelocking = null;
1068     /**
1069      * Gets set to true if the cache is going to be using locking.
1070      * This isn't a requirement, it doesn't need to use locking (most won't) and this bool is used to quickly check things.
1071      * If required then locking will be forced for the get|set|delete operation.
1072      * @var bool
1073      */
1074     protected $requirelocking = false;
1076     /**
1077      * Gets set to true if the cache must use read locking (get|has).
1078      * @var bool
1079      */
1080     protected $requirelockingread = false;
1082     /**
1083      * Gets set to true if the cache must use write locking (set|delete)
1084      * @var bool
1085      */
1086     protected $requirelockingwrite = false;
1088     /**
1089      * Gets set to a cache_store to use for locking if the caches primary store doesn't support locking natively.
1090      * @var cache_lock_interface
1091      */
1092     protected $cachelockinstance;
1094     /**
1095      * Overrides the cache construct method.
1096      *
1097      * You should not call this method from your code, instead you should use the cache::make methods.
1098      *
1099      * @param cache_definition $definition
1100      * @param cache_store $store
1101      * @param cache_loader|cache_data_source $loader
1102      */
1103     public function __construct(cache_definition $definition, cache_store $store, $loader = null) {
1104         parent::__construct($definition, $store, $loader);
1105         $this->nativelocking = $this->store_supports_native_locking();
1106         if ($definition->require_locking()) {
1107             $this->requirelocking = true;
1108             $this->requirelockingread = $definition->require_locking_read();
1109             $this->requirelockingwrite = $definition->require_locking_write();
1110         }
1112         if ($definition->has_invalidation_events()) {
1113             $lastinvalidation = $this->get('lastinvalidation');
1114             if ($lastinvalidation === false) {
1115                 // This is a new session, there won't be anything to invalidate. Set the time of the last invalidation and
1116                 // move on.
1117                 $this->set('lastinvalidation', cache::now());
1118                 return;
1119             } else if ($lastinvalidation == cache::now()) {
1120                 // We've already invalidated during this request.
1121                 return;
1122             }
1124             // Get the event invalidation cache.
1125             $cache = cache::make('core', 'eventinvalidation');
1126             $events = $cache->get_many($definition->get_invalidation_events());
1127             $todelete = array();
1128             $purgeall = false;
1129             // Iterate the returned data for the events.
1130             foreach ($events as $event => $keys) {
1131                 if ($keys === false) {
1132                     // No data to be invalidated yet.
1133                     continue;
1134                 }
1135                 // Look at each key and check the timestamp.
1136                 foreach ($keys as $key => $timestamp) {
1137                     // If the timestamp of the event is more than or equal to the last invalidation (happened between the last
1138                     // invalidation and now)then we need to invaliate the key.
1139                     if ($timestamp >= $lastinvalidation) {
1140                         if ($key === 'purged') {
1141                             $purgeall = true;
1142                             break;
1143                         } else {
1144                             $todelete[] = $key;
1145                         }
1146                     }
1147                 }
1148             }
1149             if ($purgeall) {
1150                 $this->purge();
1151             } else if (!empty($todelete)) {
1152                 $todelete = array_unique($todelete);
1153                 $this->delete_many($todelete);
1154             }
1155             // Set the time of the last invalidation.
1156             $this->set('lastinvalidation', cache::now());
1157         }
1158     }
1160     /**
1161      * Returns the identifier to use
1162      *
1163      * @staticvar int $instances Counts the number of instances. Used as part of the lock identifier.
1164      * @return string
1165      */
1166     public function get_identifier() {
1167         static $instances = 0;
1168         if ($this->lockidentifier === null) {
1169             $this->lockidentifier = md5(
1170                 $this->get_definition()->generate_definition_hash() .
1171                 sesskey() .
1172                 $instances++ .
1173                 'cache_application'
1174             );
1175         }
1176         return $this->lockidentifier;
1177     }
1179     /**
1180      * Fixes the instance up after a clone.
1181      */
1182     public function __clone() {
1183         // Force a new idenfitier.
1184         $this->lockidentifier = null;
1185     }
1187     /**
1188      * Acquires a lock on the given key.
1189      *
1190      * This is done automatically if the definition requires it.
1191      * It is recommended to use a definition if you want to have locking although it is possible to do locking without having
1192      * it required by the definition.
1193      * The problem with such an approach is that you cannot ensure that code will consistently use locking. You will need to
1194      * rely on the integrators review skills.
1195      *
1196      * @param string|int $key The key as given to get|set|delete
1197      * @return bool Returns true if the lock could be acquired, false otherwise.
1198      */
1199     public function acquire_lock($key) {
1200         $key = $this->parse_key($key);
1201         if ($this->nativelocking) {
1202             return $this->get_store()->acquire_lock($key, $this->get_identifier());
1203         } else {
1204             $this->ensure_cachelock_available();
1205             return $this->cachelockinstance->lock($key, $this->get_identifier());
1206         }
1207     }
1209     /**
1210      * Checks if this cache has a lock on the given key.
1211      *
1212      * @param string|int $key The key as given to get|set|delete
1213      * @return bool|null Returns true if there is a lock and this cache has it, null if no one has a lock on that key, false if
1214      *      someone else has the lock.
1215      */
1216     public function check_lock_state($key) {
1217         $key = $this->parse_key($key);
1218         if ($this->nativelocking) {
1219             return $this->get_store()->check_lock_state($key, $this->get_identifier());
1220         } else {
1221             $this->ensure_cachelock_available();
1222             return $this->cachelockinstance->check_state($key, $this->get_identifier());
1223         }
1224     }
1226     /**
1227      * Releases the lock this cache has on the given key
1228      *
1229      * @param string|int $key
1230      * @return bool True if the operation succeeded, false otherwise.
1231      */
1232     public function release_lock($key) {
1233         $key = $this->parse_key($key);
1234         if ($this->nativelocking) {
1235             return $this->get_store()->release_lock($key, $this->get_identifier());
1236         } else {
1237             $this->ensure_cachelock_available();
1238             return $this->cachelockinstance->unlock($key, $this->get_identifier());
1239         }
1240     }
1242     /**
1243      * Ensure that the dedicated lock store is ready to go.
1244      *
1245      * This should only happen if the cache store doesn't natively support it.
1246      */
1247     protected function ensure_cachelock_available() {
1248         if ($this->cachelockinstance === null) {
1249             $this->cachelockinstance = cache_helper::get_cachelock_for_store($this->get_store());
1250         }
1251     }
1253     /**
1254      * Sends a key => value pair to the cache.
1255      *
1256      * <code>
1257      * // This code will add four entries to the cache, one for each url.
1258      * $cache->set('main', 'http://moodle.org');
1259      * $cache->set('docs', 'http://docs.moodle.org');
1260      * $cache->set('tracker', 'http://tracker.moodle.org');
1261      * $cache->set('qa', 'http://qa.moodle.net');
1262      * </code>
1263      *
1264      * @param string|int $key The key for the data being requested.
1265      * @param mixed $data The data to set against the key.
1266      * @return bool True on success, false otherwise.
1267      */
1268     public function set($key, $data) {
1269         if ($this->requirelockingwrite && !$this->acquire_lock($key)) {
1270             return false;
1271         }
1272         $result = parent::set($key, $data);
1273         if ($this->requirelockingwrite && !$this->release_lock($key)) {
1274             debugging('Failed to release cache lock on set operation... this should not happen.', DEBUG_DEVELOPER);
1275         }
1276         return $result;
1277     }
1279     /**
1280      * Sends several key => value pairs to the cache.
1281      *
1282      * Using this function comes with potential performance implications.
1283      * Not all cache stores will support get_many/set_many operations and in order to replicate this functionality will call
1284      * the equivalent singular method for each item provided.
1285      * This should not deter you from using this function as there is a performance benefit in situations where the cache store
1286      * does support it, but you should be aware of this fact.
1287      *
1288      * <code>
1289      * // This code will add four entries to the cache, one for each url.
1290      * $cache->set_many(array(
1291      *     'main' => 'http://moodle.org',
1292      *     'docs' => 'http://docs.moodle.org',
1293      *     'tracker' => 'http://tracker.moodle.org',
1294      *     'qa' => ''http://qa.moodle.net'
1295      * ));
1296      * </code>
1297      *
1298      * @param array $keyvaluearray An array of key => value pairs to send to the cache.
1299      * @return int The number of items successfully set. It is up to the developer to check this matches the number of items.
1300      *      ... if they care that is.
1301      */
1302     public function set_many(array $keyvaluearray) {
1303         if ($this->requirelockingwrite) {
1304             $locks = array();
1305             foreach ($keyvaluearray as $id => $pair) {
1306                 $key = $pair['key'];
1307                 if ($this->acquire_lock($key)) {
1308                     $locks[] = $key;
1309                 } else {
1310                     unset($keyvaluearray[$id]);
1311                 }
1312             }
1313         }
1314         $result = parent::set_many($keyvaluearray);
1315         if ($this->requirelockingwrite) {
1316             foreach ($locks as $key) {
1317                 if ($this->release_lock($key)) {
1318                     debugging('Failed to release cache lock on set_many operation... this should not happen.', DEBUG_DEVELOPER);
1319                 }
1320             }
1321         }
1322         return $result;
1323     }
1325     /**
1326      * Retrieves the value for the given key from the cache.
1327      *
1328      * @param string|int $key The key for the data being requested.
1329      * @param int $strictness One of IGNORE_MISSING | MUST_EXIST
1330      * @return mixed|false The data from the cache or false if the key did not exist within the cache.
1331      * @throws moodle_exception
1332      */
1333     public function get($key, $strictness = IGNORE_MISSING) {
1334         if ($this->requirelockingread && $this->check_lock_state($key) === false) {
1335             // Read locking required and someone else has the read lock.
1336             return false;
1337         }
1338         return parent::get($key, $strictness);
1339     }
1341     /**
1342      * Retrieves an array of values for an array of keys.
1343      *
1344      * Using this function comes with potential performance implications.
1345      * Not all cache stores will support get_many/set_many operations and in order to replicate this functionality will call
1346      * the equivalent singular method for each item provided.
1347      * This should not deter you from using this function as there is a performance benefit in situations where the cache store
1348      * does support it, but you should be aware of this fact.
1349      *
1350      * @param array $keys The keys of the data being requested.
1351      * @param int $strictness One of IGNORE_MISSING or MUST_EXIST.
1352      * @return array An array of key value pairs for the items that could be retrieved from the cache.
1353      *      If MUST_EXIST was used and not all keys existed within the cache then an exception will be thrown.
1354      *      Otherwise any key that did not exist will have a data value of false within the results.
1355      * @throws moodle_exception
1356      */
1357     public function get_many(array $keys, $strictness = IGNORE_MISSING) {
1358         if ($this->requirelockingread) {
1359             foreach ($keys as $id => $key) {
1360                 $lock =$this->acquire_lock($key);
1361                 if (!$lock) {
1362                     if ($strictness === MUST_EXIST) {
1363                         throw new coding_exception('Could not acquire read locks for all of the items being requested.');
1364                     } else {
1365                         // Can't return this as we couldn't get a read lock.
1366                         unset($keys[$id]);
1367                     }
1368                 }
1370             }
1371         }
1372         return parent::get_many($keys, $strictness);
1373     }
1375     /**
1376      * Delete the given key from the cache.
1377      *
1378      * @param string|int $key The key to delete.
1379      * @param bool $recurse When set to true the key will also be deleted from all stacked cache loaders and their stores.
1380      *     This happens by default and ensure that all the caches are consistent. It is NOT recommended to change this.
1381      * @return bool True of success, false otherwise.
1382      */
1383     public function delete($key, $recurse = true) {
1384         if ($this->requirelockingwrite && !$this->acquire_lock($key)) {
1385             return false;
1386         }
1387         $result = parent::delete($key, $recurse);
1388         if ($this->requirelockingwrite && !$this->release_lock($key)) {
1389             debugging('Failed to release cache lock on delete operation... this should not happen.', DEBUG_DEVELOPER);
1390         }
1391         return $result;
1392     }
1394     /**
1395      * Delete all of the given keys from the cache.
1396      *
1397      * @param array $keys The key to delete.
1398      * @param bool $recurse When set to true the key will also be deleted from all stacked cache loaders and their stores.
1399      *     This happens by default and ensure that all the caches are consistent. It is NOT recommended to change this.
1400      * @return int The number of items successfully deleted.
1401      */
1402     public function delete_many(array $keys, $recurse = true) {
1403         if ($this->requirelockingwrite) {
1404             $locks = array();
1405             foreach ($keys as $id => $key) {
1406                 if ($this->acquire_lock($key)) {
1407                     $locks[] = $key;
1408                 } else {
1409                     unset($keys[$id]);
1410                 }
1411             }
1412         }
1413         $result = parent::delete_many($keys, $recurse);
1414         if ($this->requirelockingwrite) {
1415             foreach ($locks as $key) {
1416                 if ($this->release_lock($key)) {
1417                     debugging('Failed to release cache lock on delete_many operation... this should not happen.', DEBUG_DEVELOPER);
1418                 }
1419             }
1420         }
1421         return $result;
1422     }
1425 /**
1426  * A session cache.
1427  *
1428  * This class is used for session caches returned by the cache::make methods.
1429  *
1430  * It differs from the application loader in a couple of noteable ways:
1431  *    1. Sessions are always expected to be persistent.
1432  *       Because of this we don't ever use the persist cache and instead a session array
1433  *       containing all of the data is maintained by this object.
1434  *    2. Session data for a loader instance (store + definition) is consolidate into a
1435  *       single array for storage within the store.
1436  *       Along with this we embed a lastaccessed time with the data. This way we can
1437  *       check sessions for a last access time.
1438  *    3. Session stores are required to support key searching and must
1439  *       implement cache_is_searchable. This ensures stores used for the cache can be
1440  *       targetted for garbage collection of session data.
1441  *
1442  * This cache class should never be interacted with directly. Instead you should always use the cache::make methods.
1443  * It is technically possible to call those methods through this class however there is no guarantee that you will get an
1444  * instance of this class back again.
1445  *
1446  * @todo we should support locking in the session as well. Should be pretty simple to set up.
1447  *
1448  * @internal don't use me directly.
1449  *
1450  * @package    core
1451  * @category   cache
1452  * @copyright  2012 Sam Hemelryk
1453  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
1454  */
1455 class cache_session extends cache {
1456     /**
1457      * The user the session has been established for.
1458      * @var int
1459      */
1460     protected static $loadeduserid = null;
1462     /**
1463      * The userid this cache is currently using.
1464      * @var int
1465      */
1466     protected $currentuserid = null;
1468     /**
1469      * The session id we are currently using.
1470      * @var array
1471      */
1472     protected $sessionid = null;
1474     /**
1475      * The session data for the above session id.
1476      * @var array
1477      */
1478     protected $session = null;
1480     /**
1481      * Constant used to prefix keys.
1482      */
1483     const KEY_PREFIX = 'sess_';
1485     /**
1486      * Override the cache::construct method.
1487      *
1488      * This function gets overriden so that we can process any invalidation events if need be.
1489      * If the definition doesn't have any invalidation events then this occurs exactly as it would for the cache class.
1490      * Otherwise we look at the last invalidation time and then check the invalidation data for events that have occured
1491      * between then now.
1492      *
1493      * You should not call this method from your code, instead you should use the cache::make methods.
1494      *
1495      * @param cache_definition $definition
1496      * @param cache_store $store
1497      * @param cache_loader|cache_data_source $loader
1498      * @return void
1499      */
1500     public function __construct(cache_definition $definition, cache_store $store, $loader = null) {
1501         // First up copy the loadeduserid to the current user id.
1502         $this->currentuserid = self::$loadeduserid;
1503         parent::__construct($definition, $store, $loader);
1504         if ($definition->has_invalidation_events()) {
1505             $lastinvalidation = $this->get('lastsessioninvalidation');
1506             if ($lastinvalidation === false) {
1507                 // This is a new session, there won't be anything to invalidate. Set the time of the last invalidation and
1508                 // move on.
1509                 $this->set('lastsessioninvalidation', cache::now());
1510                 return;
1511             } else if ($lastinvalidation == cache::now()) {
1512                 // We've already invalidated during this request.
1513                 return;
1514             }
1516             // Get the event invalidation cache.
1517             $cache = cache::make('core', 'eventinvalidation');
1518             $events = $cache->get_many($definition->get_invalidation_events());
1519             $todelete = array();
1520             $purgeall = false;
1521             // Iterate the returned data for the events.
1522             foreach ($events as $event => $keys) {
1523                 if ($keys === false) {
1524                     // No data to be invalidated yet.
1525                     continue;
1526                 }
1527                 // Look at each key and check the timestamp.
1528                 foreach ($keys as $key => $timestamp) {
1529                     // If the timestamp of the event is more than or equal to the last invalidation (happened between the last
1530                     // invalidation and now)then we need to invaliate the key.
1531                     if ($timestamp >= $lastinvalidation) {
1532                         if ($key === 'purged') {
1533                             $purgeall = true;
1534                             break;
1535                         } else {
1536                             $todelete[] = $key;
1537                         }
1538                     }
1539                 }
1540             }
1541             if ($purgeall) {
1542                 $this->purge();
1543             } else if (!empty($todelete)) {
1544                 $todelete = array_unique($todelete);
1545                 $this->delete_many($todelete);
1546             }
1547             // Set the time of the last invalidation.
1548             $this->set('lastsessioninvalidation', cache::now());
1549         }
1550     }
1552     /**
1553      * Parses the key turning it into a string (or array is required) suitable to be passed to the cache store.
1554      *
1555      * This function is called for every operation that uses keys. For this reason we use this function to also check
1556      * that the current user is the same as the user who last used this cache.
1557      *
1558      * On top of that if prepends the string 'sess_' to the start of all keys. The _ ensures things are easily identifiable.
1559      *
1560      * @param string|int $key As passed to get|set|delete etc.
1561      * @return string|array String unless the store supports multi-identifiers in which case an array if returned.
1562      */
1563     protected function parse_key($key) {
1564         if ($key === 'lastaccess') {
1565             $key = '__lastaccess__';
1566         }
1567         return 'sess_'.parent::parse_key($key);
1568     }
1570     /**
1571      * Check that this cache instance is tracking the current user.
1572      */
1573     protected function check_tracked_user() {
1574         if (isset($_SESSION['USER']->id)) {
1575             // Get the id of the current user.
1576             $new = $_SESSION['USER']->id;
1577         } else {
1578             // No user set up yet.
1579             $new = 0;
1580         }
1581         if ($new !== self::$loadeduserid) {
1582             // The current user doesn't match the tracked userid for this request.
1583             if (!is_null(self::$loadeduserid)) {
1584                 // Purge the data we have for the old user.
1585                 // This way we don't bloat the session.
1586                 $this->purge();
1587                 // Update the session id just in case!
1588                 $this->sessionid = session_id();
1589             }
1590             self::$loadeduserid = $new;
1591             $this->currentuserid = $new;
1592         } else if ($new !== $this->currentuserid) {
1593             // The current user matches the loaded user but not the user last used by this cache.
1594             $this->purge();
1595             $this->currentuserid = $new;
1596             // Update the session id just in case!
1597             $this->sessionid = session_id();
1598         }
1599     }
1601     /**
1602      * Gets the session data.
1603      *
1604      * @param bool $force If true the session data will be loaded from the store again.
1605      * @return array An array of session data.
1606      */
1607     protected function get_session_data($force = false) {
1608         if ($this->sessionid === null) {
1609             $this->sessionid = session_id();
1610         }
1611         if (is_array($this->session) && !$force) {
1612             return $this->session;
1613         }
1614         $session = parent::get($this->sessionid);
1615         if ($session === false) {
1616             $session = array();
1617         }
1618         // We have to write here to ensure that the lastaccess time is recorded.
1619         // And also in order to ensure the session entry exists as when we save it on __destruct
1620         // $CFG is likely to have already been destroyed.
1621         $this->save_session($session);
1622         return $this->session;
1623     }
1625     /**
1626      * Saves the session data.
1627      *
1628      * This function also updates the last access time.
1629      *
1630      * @param array $session
1631      * @return bool
1632      */
1633     protected function save_session(array $session) {
1634         $session['lastaccess'] = time();
1635         $this->session = $session;
1636         return parent::set($this->sessionid, $this->session);
1637     }
1639     /**
1640      * Retrieves the value for the given key from the cache.
1641      *
1642      * @param string|int $key The key for the data being requested.
1643      *      It can be any structure although using a scalar string or int is recommended in the interests of performance.
1644      *      In advanced cases an array may be useful such as in situations requiring the multi-key functionality.
1645      * @param int $strictness One of IGNORE_MISSING | MUST_EXIST
1646      * @return mixed|false The data from the cache or false if the key did not exist within the cache.
1647      * @throws moodle_exception
1648      */
1649     public function get($key, $strictness = IGNORE_MISSING) {
1650         // Check the tracked user.
1651         $this->check_tracked_user();
1652         // 2. Parse the key.
1653         $parsedkey = $this->parse_key($key);
1654         // 3. Get it from the store.
1655         $result = false;
1656         $session = $this->get_session_data();
1657         if (array_key_exists($parsedkey, $session)) {
1658             $result = $session[$parsedkey];
1659             if ($result instanceof cache_ttl_wrapper) {
1660                 if ($result->has_expired()) {
1661                     $this->get_store()->delete($parsedkey);
1662                     $result = false;
1663                 } else {
1664                     $result = $result->data;
1665                 }
1666             }
1667             if ($result instanceof cache_cached_object) {
1668                 $result = $result->restore_object();
1669             }
1670         }
1671         // 4. Load if from the loader/datasource if we don't already have it.
1672         $setaftervalidation = false;
1673         if ($result === false) {
1674             if ($this->perfdebug) {
1675                 cache_helper::record_cache_miss('**static session**', $this->get_definition()->get_id());
1676             }
1677             if ($this->get_loader() !== false) {
1678                 // We must pass the original (unparsed) key to the next loader in the chain.
1679                 // The next loader will parse the key as it sees fit. It may be parsed differently
1680                 // depending upon the capabilities of the store associated with the loader.
1681                 $result = $this->get_loader()->get($key);
1682             } else if ($this->get_datasource() !== false) {
1683                 $result = $this->get_datasource()->load_for_cache($key);
1684             }
1685             $setaftervalidation = ($result !== false);
1686         } else if ($this->perfdebug) {
1687             cache_helper::record_cache_hit('**static session**', $this->get_definition()->get_id());
1688         }
1689         // 5. Validate strictness.
1690         if ($strictness === MUST_EXIST && $result === false) {
1691             throw new moodle_exception('Requested key did not exist in any cache stores and could not be loaded.');
1692         }
1693         // 6. Set it to the store if we got it from the loader/datasource.
1694         if ($setaftervalidation) {
1695             $this->set($key, $result);
1696         }
1697         // 7. Make sure we don't pass back anything that could be a reference.
1698         //    We don't want people modifying the data in the cache.
1699         if (!is_scalar($result)) {
1700             // If data is an object it will be a reference.
1701             // If data is an array if may contain references.
1702             // We want to break references so that the cache cannot be modified outside of itself.
1703             // Call the function to unreference it (in the best way possible).
1704             $result = $this->unref($result);
1705         }
1706         return $result;
1707     }
1709     /**
1710      * Sends a key => value pair to the cache.
1711      *
1712      * <code>
1713      * // This code will add four entries to the cache, one for each url.
1714      * $cache->set('main', 'http://moodle.org');
1715      * $cache->set('docs', 'http://docs.moodle.org');
1716      * $cache->set('tracker', 'http://tracker.moodle.org');
1717      * $cache->set('qa', 'http://qa.moodle.net');
1718      * </code>
1719      *
1720      * @param string|int $key The key for the data being requested.
1721      *      It can be any structure although using a scalar string or int is recommended in the interests of performance.
1722      *      In advanced cases an array may be useful such as in situations requiring the multi-key functionality.
1723      * @param mixed $data The data to set against the key.
1724      * @return bool True on success, false otherwise.
1725      */
1726     public function set($key, $data) {
1727         $this->check_tracked_user();
1728         if ($this->perfdebug) {
1729             cache_helper::record_cache_set('**static session**', $this->get_definition()->get_id());
1730         }
1731         if (is_object($data) && $data instanceof cacheable_object) {
1732             $data = new cache_cached_object($data);
1733         } else if (!is_scalar($data)) {
1734             // If data is an object it will be a reference.
1735             // If data is an array if may contain references.
1736             // We want to break references so that the cache cannot be modified outside of itself.
1737             // Call the function to unreference it (in the best way possible).
1738             $data = $this->unref($data);
1739         }
1740         // We dont' support native TTL here as we consolidate data for sessions.
1741         if ($this->has_a_ttl()) {
1742             $data = new cache_ttl_wrapper($data, $this->get_definition()->get_ttl());
1743         }
1744         $session = $this->get_session_data();
1745         $session[$this->parse_key($key)] = $data;
1746         return $this->save_session($session);
1747     }
1749     /**
1750      * Delete the given key from the cache.
1751      *
1752      * @param string|int $key The key to delete.
1753      * @param bool $recurse When set to true the key will also be deleted from all stacked cache loaders and their stores.
1754      *     This happens by default and ensure that all the caches are consistent. It is NOT recommended to change this.
1755      * @return bool True of success, false otherwise.
1756      */
1757     public function delete($key, $recurse = true) {
1758         $this->check_tracked_user();
1759         $parsedkey = $this->parse_key($key);
1760         if ($recurse && $this->get_loader() !== false) {
1761             // Delete from the bottom of the stack first.
1762             $this->get_loader()->delete($key, $recurse);
1763         }
1764         $session = $this->get_session_data();
1765         unset($session[$parsedkey]);
1766         return $this->save_session($session);
1767     }
1769     /**
1770      * Retrieves an array of values for an array of keys.
1771      *
1772      * Using this function comes with potential performance implications.
1773      * Not all cache stores will support get_many/set_many operations and in order to replicate this functionality will call
1774      * the equivalent singular method for each item provided.
1775      * This should not deter you from using this function as there is a performance benefit in situations where the cache store
1776      * does support it, but you should be aware of this fact.
1777      *
1778      * @param array $keys The keys of the data being requested.
1779      *      Each key can be any structure although using a scalar string or int is recommended in the interests of performance.
1780      *      In advanced cases an array may be useful such as in situations requiring the multi-key functionality.
1781      * @param int $strictness One of IGNORE_MISSING or MUST_EXIST.
1782      * @return array An array of key value pairs for the items that could be retrieved from the cache.
1783      *      If MUST_EXIST was used and not all keys existed within the cache then an exception will be thrown.
1784      *      Otherwise any key that did not exist will have a data value of false within the results.
1785      * @throws moodle_exception
1786      */
1787     public function get_many(array $keys, $strictness = IGNORE_MISSING) {
1788         $this->check_tracked_user();
1789         $return = array();
1790         foreach ($keys as $key) {
1791             $return[$key] = $this->get($key, $strictness);
1792         }
1793         return $return;
1794     }
1796     /**
1797      * Delete all of the given keys from the cache.
1798      *
1799      * @param array $keys The key to delete.
1800      * @param bool $recurse When set to true the key will also be deleted from all stacked cache loaders and their stores.
1801      *     This happens by default and ensure that all the caches are consistent. It is NOT recommended to change this.
1802      * @return int The number of items successfully deleted.
1803      */
1804     public function delete_many(array $keys, $recurse = true) {
1805         $this->check_tracked_user();
1806         $parsedkeys = array_map(array($this, 'parse_key'), $keys);
1807         if ($recurse && $this->get_loader() !== false) {
1808             // Delete from the bottom of the stack first.
1809             $this->get_loader()->delete_many($keys, $recurse);
1810         }
1811         $session = $this->get_session_data();
1812         foreach ($parsedkeys as $parsedkey) {
1813             unset($session[$parsedkey]);
1814         }
1815         $this->save_session($session);
1816         return count($keys);
1817     }
1819     /**
1820      * Sends several key => value pairs to the cache.
1821      *
1822      * Using this function comes with potential performance implications.
1823      * Not all cache stores will support get_many/set_many operations and in order to replicate this functionality will call
1824      * the equivalent singular method for each item provided.
1825      * This should not deter you from using this function as there is a performance benefit in situations where the cache store
1826      * does support it, but you should be aware of this fact.
1827      *
1828      * <code>
1829      * // This code will add four entries to the cache, one for each url.
1830      * $cache->set_many(array(
1831      *     'main' => 'http://moodle.org',
1832      *     'docs' => 'http://docs.moodle.org',
1833      *     'tracker' => 'http://tracker.moodle.org',
1834      *     'qa' => ''http://qa.moodle.net'
1835      * ));
1836      * </code>
1837      *
1838      * @param array $keyvaluearray An array of key => value pairs to send to the cache.
1839      * @return int The number of items successfully set. It is up to the developer to check this matches the number of items.
1840      *      ... if they care that is.
1841      */
1842     public function set_many(array $keyvaluearray) {
1843         $this->check_tracked_user();
1844         $session = $this->get_session_data();
1845         $simulatettl = $this->has_a_ttl();
1846         foreach ($keyvaluearray as $key => $value) {
1847             if (is_object($value) && $value instanceof cacheable_object) {
1848                 $value = new cache_cached_object($value);
1849             } else if (!is_scalar($value)) {
1850                 // If data is an object it will be a reference.
1851                 // If data is an array if may contain references.
1852                 // We want to break references so that the cache cannot be modified outside of itself.
1853                 // Call the function to unreference it (in the best way possible).
1854                 $value = $this->unref($value);
1855             }
1856             if ($simulatettl) {
1857                 $value = new cache_ttl_wrapper($value, $this->get_definition()->get_ttl());
1858             }
1859             $parsedkey = $this->parse_key($key);
1860             $session[$parsedkey] = $value;
1861         }
1862         if ($this->perfdebug) {
1863             cache_helper::record_cache_set($this->storetype, $this->get_definition()->get_id());
1864         }
1865         $this->save_session($session);
1866         return count($keyvaluearray);
1867     }
1869     /**
1870      * Purges the cache store, and loader if there is one.
1871      *
1872      * @return bool True on success, false otherwise
1873      */
1874     public function purge() {
1875         // 1. Purge the session object.
1876         $this->session = array();
1877         // 2. Delete the record for this users session from the store.
1878         $this->get_store()->delete($this->sessionid);
1879         // 3. Optionally purge any stacked loaders in the same way.
1880         if ($this->get_loader()) {
1881             $this->get_loader()->delete($this->sessionid);
1882         }
1883         return true;
1884     }
1886     /**
1887      * Test is a cache has a key.
1888      *
1889      * The use of the has methods is strongly discouraged. In a high load environment the cache may well change between the
1890      * test and any subsequent action (get, set, delete etc).
1891      * Instead it is recommended to write your code in such a way they it performs the following steps:
1892      * <ol>
1893      * <li>Attempt to retrieve the information.</li>
1894      * <li>Generate the information.</li>
1895      * <li>Attempt to set the information</li>
1896      * </ol>
1897      *
1898      * Its also worth mentioning that not all stores support key tests.
1899      * For stores that don't support key tests this functionality is mimicked by using the equivalent get method.
1900      * Just one more reason you should not use these methods unless you have a very good reason to do so.
1901      *
1902      * @param string|int $key
1903      * @param bool $tryloadifpossible If set to true, the cache doesn't contain the key, and there is another cache loader or
1904      *      data source then the code will try load the key value from the next item in the chain.
1905      * @return bool True if the cache has the requested key, false otherwise.
1906      */
1907     public function has($key, $tryloadifpossible = false) {
1908         $this->check_tracked_user();
1909         $parsedkey = $this->parse_key($key);
1910         $session = $this->get_session_data();
1911         $has = false;
1912         if ($this->has_a_ttl()) {
1913             // The data has a TTL and the store doesn't support it natively.
1914             // We must fetch the data and expect a ttl wrapper.
1915             if (array_key_exists($parsedkey, $session)) {
1916                 $data = $session[$parsedkey];
1917                 $has = ($data instanceof cache_ttl_wrapper && !$data->has_expired());
1918             }
1919         } else {
1920             $has = array_key_exists($parsedkey, $session);
1921         }
1922         if (!$has && $tryloadifpossible) {
1923             if ($this->get_loader() !== false) {
1924                 $result = $this->get_loader()->get($key);
1925             } else if ($this->get_datasource() !== null) {
1926                 $result = $this->get_datasource()->load_for_cache($key);
1927             }
1928             $has = ($result !== null);
1929             if ($has) {
1930                 $this->set($key, $result);
1931             }
1932         }
1933         return $has;
1934     }
1936     /**
1937      * Test is a cache has all of the given keys.
1938      *
1939      * It is strongly recommended to avoid the use of this function if not absolutely required.
1940      * In a high load environment the cache may well change between the test and any subsequent action (get, set, delete etc).
1941      *
1942      * Its also worth mentioning that not all stores support key tests.
1943      * For stores that don't support key tests this functionality is mimicked by using the equivalent get method.
1944      * Just one more reason you should not use these methods unless you have a very good reason to do so.
1945      *
1946      * @param array $keys
1947      * @return bool True if the cache has all of the given keys, false otherwise.
1948      */
1949     public function has_all(array $keys) {
1950         $this->check_tracked_user();
1951         $session = $this->get_session_data();
1952         foreach ($keys as $key) {
1953             $has = false;
1954             $parsedkey = $this->parse_key($key);
1955             if ($this->has_a_ttl()) {
1956                 // The data has a TTL and the store doesn't support it natively.
1957                 // We must fetch the data and expect a ttl wrapper.
1958                 if (array_key_exists($parsedkey, $session)) {
1959                     $data = $session[$parsedkey];
1960                     $has = ($data instanceof cache_ttl_wrapper && !$data->has_expired());
1961                 }
1962             } else {
1963                 $has = array_key_exists($parsedkey, $session);
1964             }
1965             if (!$has) {
1966                 return false;
1967             }
1968         }
1969         return true;
1970     }
1972     /**
1973      * Test if a cache has at least one of the given keys.
1974      *
1975      * It is strongly recommended to avoid the use of this function if not absolutely required.
1976      * In a high load environment the cache may well change between the test and any subsequent action (get, set, delete etc).
1977      *
1978      * Its also worth mentioning that not all stores support key tests.
1979      * For stores that don't support key tests this functionality is mimicked by using the equivalent get method.
1980      * Just one more reason you should not use these methods unless you have a very good reason to do so.
1981      *
1982      * @param array $keys
1983      * @return bool True if the cache has at least one of the given keys
1984      */
1985     public function has_any(array $keys) {
1986         $this->check_tracked_user();
1987         $session = $this->get_session_data();
1988         foreach ($keys as $key) {
1989             $has = false;
1990             $parsedkey = $this->parse_key($key);
1991             if ($this->has_a_ttl()) {
1992                 // The data has a TTL and the store doesn't support it natively.
1993                 // We must fetch the data and expect a ttl wrapper.
1994                 if (array_key_exists($parsedkey, $session)) {
1995                     $data = $session[$parsedkey];
1996                     $has = ($data instanceof cache_ttl_wrapper && !$data->has_expired());
1997                 }
1998             } else {
1999                 $has = array_key_exists($parsedkey, $session);
2000             }
2001             if ($has) {
2002                 return true;
2003             }
2004         }
2005         return false;
2006     }
2008     /**
2009      * The session loader never uses the persist cache.
2010      * Instead it stores things in the static $session variable. Shared between all session loaders.
2011      *
2012      * @return bool
2013      */
2014     protected function is_using_persist_cache() {
2015         return false;
2016     }
2019 /**
2020  * An request cache.
2021  *
2022  * This class is used for request caches returned by the cache::make methods.
2023  *
2024  * This cache class should never be interacted with directly. Instead you should always use the cache::make methods.
2025  * It is technically possible to call those methods through this class however there is no guarantee that you will get an
2026  * instance of this class back again.
2027  *
2028  * @internal don't use me directly.
2029  *
2030  * @package    core
2031  * @category   cache
2032  * @copyright  2012 Sam Hemelryk
2033  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
2034  */
2035 class cache_request extends cache {
2036     // This comment appeases code pre-checker ;) !