MDL-40893 backup: cache question answers for performance
[moodle.git] / cache / stores / session / lib.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  * The library file for the session cache store.
19  *
20  * This file is part of the session cache store, it contains the API for interacting with an instance of the store.
21  * This is used as a default cache store within the Cache API. It should never be deleted.
22  *
23  * @package    cachestore_session
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 session data store class.
33  *
34  * @copyright  2012 Sam Hemelryk
35  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
36  */
37 abstract class session_data_store extends cache_store {
39     /**
40      * Used for the actual storage.
41      * @var array
42      */
43     private static $sessionstore = null;
45     /**
46      * Returns a static store by reference... REFERENCE SUPER IMPORTANT.
47      *
48      * @param string $id
49      * @return array
50      */
51     protected static function &register_store_id($id) {
52         if (is_null(self::$sessionstore)) {
53             global $SESSION;
54             if (!isset($SESSION->cachestore_session)) {
55                 $SESSION->cachestore_session = array();
56             }
57             self::$sessionstore =& $SESSION->cachestore_session;
58         }
59         if (!array_key_exists($id, self::$sessionstore)) {
60             self::$sessionstore[$id] = array();
61         }
62         return self::$sessionstore[$id];
63     }
65     /**
66      * Flushes the data belong to the given store id.
67      * @param string $id
68      */
69     protected static function flush_store_by_id($id) {
70         unset(self::$sessionstore[$id]);
71         self::$sessionstore[$id] = array();
72     }
74     /**
75      * Flushes the store of all data.
76      */
77     protected static function flush_store() {
78         $ids = array_keys(self::$sessionstore);
79         unset(self::$sessionstore);
80         self::$sessionstore = array();
81         foreach ($ids as $id) {
82             self::$sessionstore[$id] = array();
83         }
84     }
85 }
87 /**
88  * The Session store class.
89  *
90  * @copyright  2012 Sam Hemelryk
91  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
92  */
93 class cachestore_session extends session_data_store implements cache_is_key_aware, cache_is_searchable {
95     /**
96      * The name of the store
97      * @var store
98      */
99     protected $name;
101     /**
102      * The store id (should be unique)
103      * @var string
104      */
105     protected $storeid;
107     /**
108      * The store we use for data.
109      * @var array
110      */
111     protected $store;
113     /**
114      * The ttl if there is one. Hopefully not.
115      * @var int
116      */
117     protected $ttl = 0;
119     /**
120      * The maximum size for the store, or false if there isn't one.
121      * @var bool
122      */
123     protected $maxsize = false;
125     /**
126      * The number of items currently being stored.
127      * @var int
128      */
129     protected $storecount = 0;
131     /**
132      * Constructs the store instance.
133      *
134      * Noting that this function is not an initialisation. It is used to prepare the store for use.
135      * The store will be initialised when required and will be provided with a cache_definition at that time.
136      *
137      * @param string $name
138      * @param array $configuration
139      */
140     public function __construct($name, array $configuration = array()) {
141         $this->name = $name;
142     }
144     /**
145      * Returns the supported features as a combined int.
146      *
147      * @param array $configuration
148      * @return int
149      */
150     public static function get_supported_features(array $configuration = array()) {
151         return self::SUPPORTS_DATA_GUARANTEE +
152                self::SUPPORTS_NATIVE_TTL +
153                self::IS_SEARCHABLE;
154     }
156     /**
157      * Returns false as this store does not support multiple identifiers.
158      * (This optional function is a performance optimisation; it must be
159      * consistent with the value from get_supported_features.)
160      *
161      * @return bool False
162      */
163     public function supports_multiple_identifiers() {
164         return false;
165     }
167     /**
168      * Returns the supported modes as a combined int.
169      *
170      * @param array $configuration
171      * @return int
172      */
173     public static function get_supported_modes(array $configuration = array()) {
174         return self::MODE_SESSION;
175     }
177     /**
178      * Returns true if the store requirements are met.
179      *
180      * @return bool
181      */
182     public static function are_requirements_met() {
183         return true;
184     }
186     /**
187      * Returns true if the given mode is supported by this store.
188      *
189      * @param int $mode One of cache_store::MODE_*
190      * @return bool
191      */
192     public static function is_supported_mode($mode) {
193         return ($mode === self::MODE_SESSION);
194     }
196     /**
197      * Initialises the cache.
198      *
199      * Once this has been done the cache is all set to be used.
200      *
201      * @param cache_definition $definition
202      */
203     public function initialise(cache_definition $definition) {
204         $this->storeid = $definition->generate_definition_hash();
205         $this->store = &self::register_store_id($definition->get_id());
206         $this->ttl = $definition->get_ttl();
207         $maxsize = $definition->get_maxsize();
208         if ($maxsize !== null) {
209             // Must be a positive int.
210             $this->maxsize = abs((int)$maxsize);
211             $this->storecount = count($this->store);
212         }
213     }
215     /**
216      * Returns true once this instance has been initialised.
217      *
218      * @return bool
219      */
220     public function is_initialised() {
221         return (is_array($this->store));
222     }
224     /**
225      * Returns true if this store instance is ready to be used.
226      * @return bool
227      */
228     public function is_ready() {
229         return true;
230     }
232     /**
233      * Retrieves an item from the cache store given its key.
234      *
235      * @param string $key The key to retrieve
236      * @return mixed The data that was associated with the key, or false if the key did not exist.
237      */
238     public function get($key) {
239         if (isset($this->store[$key])) {
240             if ($this->ttl == 0) {
241                 return $this->store[$key][0];
242             } else if ($this->store[$key][1] >= (cache::now() - $this->ttl)) {
243                 return $this->store[$key][0];
244             }
245         }
246         return false;
247     }
249     /**
250      * Retrieves several items from the cache store in a single transaction.
251      *
252      * If not all of the items are available in the cache then the data value for those that are missing will be set to false.
253      *
254      * @param array $keys The array of keys to retrieve
255      * @return array An array of items from the cache. There will be an item for each key, those that were not in the store will
256      *      be set to false.
257      */
258     public function get_many($keys) {
259         $return = array();
260         if ($this->ttl != 0) {
261             $maxtime = cache::now() - $this->ttl;
262         }
264         foreach ($keys as $key) {
265             $return[$key] = false;
266             if (isset($this->store[$key])) {
267                 if ($this->ttl == 0) {
268                     $return[$key] = $this->store[$key][0];
269                 } else if ($this->store[$key][1] >= $maxtime) {
270                     $return[$key] = $this->store[$key][0];
271                 }
272             }
273         }
274         return $return;
275     }
277     /**
278      * Sets an item in the cache given its key and data value.
279      *
280      * @param string $key The key to use.
281      * @param mixed $data The data to set.
282      * @param bool $testmaxsize If set to true then we test the maxsize arg and reduce if required.
283      * @return bool True if the operation was a success false otherwise.
284      */
285     public function set($key, $data, $testmaxsize = true) {
286         $testmaxsize = ($testmaxsize && $this->maxsize !== false);
287         if ($testmaxsize) {
288             $increment = (!isset($this->store[$key]));
289         }
290         if ($this->ttl == 0) {
291             $this->store[$key][0] = $data;
292         } else {
293             $this->store[$key] = array($data, cache::now());
294         }
295         if ($testmaxsize && $increment) {
296             $this->storecount++;
297             if ($this->storecount > $this->maxsize) {
298                 $this->reduce_for_maxsize();
299             }
300         }
301         return true;
302     }
304     /**
305      * Sets many items in the cache in a single transaction.
306      *
307      * @param array $keyvaluearray An array of key value pairs. Each item in the array will be an associative array with two
308      *      keys, 'key' and 'value'.
309      * @return int The number of items successfully set. It is up to the developer to check this matches the number of items
310      *      sent ... if they care that is.
311      */
312     public function set_many(array $keyvaluearray) {
313         $count = 0;
314         foreach ($keyvaluearray as $pair) {
315             $this->set($pair['key'], $pair['value'], false);
316             $count++;
317         }
318         if ($this->maxsize !== false) {
319             $this->storecount += $count;
320             if ($this->storecount > $this->maxsize) {
321                 $this->reduce_for_maxsize();
322             }
323         }
324         return $count;
325     }
327     /**
328      * Checks if the store has a record for the given key and returns true if so.
329      *
330      * @param string $key
331      * @return bool
332      */
333     public function has($key) {
334         if (isset($this->store[$key])) {
335             if ($this->ttl == 0) {
336                 return true;
337             } else if ($this->store[$key][1] >= (cache::now() - $this->ttl)) {
338                 return true;
339             }
340         }
341         return false;
342     }
344     /**
345      * Returns true if the store contains records for all of the given keys.
346      *
347      * @param array $keys
348      * @return bool
349      */
350     public function has_all(array $keys) {
351         if ($this->ttl != 0) {
352             $maxtime = cache::now() - $this->ttl;
353         }
355         foreach ($keys as $key) {
356             if (!isset($this->store[$key])) {
357                 return false;
358             }
359             if ($this->ttl != 0 && $this->store[$key][1] < $maxtime) {
360                 return false;
361             }
362         }
363         return true;
364     }
366     /**
367      * Returns true if the store contains records for any of the given keys.
368      *
369      * @param array $keys
370      * @return bool
371      */
372     public function has_any(array $keys) {
373         if ($this->ttl != 0) {
374             $maxtime = cache::now() - $this->ttl;
375         }
377         foreach ($keys as $key) {
378             if (isset($this->store[$key]) && ($this->ttl == 0 || $this->store[$key][1] >= $maxtime)) {
379                 return true;
380             }
381         }
382         return false;
383     }
385     /**
386      * Deletes an item from the cache store.
387      *
388      * @param string $key The key to delete.
389      * @return bool Returns true if the operation was a success, false otherwise.
390      */
391     public function delete($key) {
392         $result = isset($this->store[$key]);
393         unset($this->store[$key]);
394         if ($this->maxsize !== false) {
395             $this->storecount--;
396         }
397         return $result;
398     }
400     /**
401      * Deletes several keys from the cache in a single action.
402      *
403      * @param array $keys The keys to delete
404      * @return int The number of items successfully deleted.
405      */
406     public function delete_many(array $keys) {
407         $count = 0;
408         foreach ($keys as $key) {
409             if (isset($this->store[$key])) {
410                 $count++;
411             }
412             unset($this->store[$key]);
413         }
414         if ($this->maxsize !== false) {
415             $this->storecount -= $count;
416         }
417         return $count;
418     }
420     /**
421      * Purges the cache deleting all items within it.
422      *
423      * @return boolean True on success. False otherwise.
424      */
425     public function purge() {
426         $this->store = array();
427         // Don't worry about checking if we're using max size just set it as thats as fast as the check.
428         $this->storecount = 0;
429         return true;
430     }
432     /**
433      * Reduces the size of the array if maxsize has been hit.
434      *
435      * This function reduces the size of the store reducing it by 10% of its maxsize.
436      * It removes the oldest items in the store when doing this.
437      * The reason it does this an doesn't use a least recently used system is purely the overhead such a system
438      * requires. The current approach is focused on speed, MUC already adds enough overhead to static/session caches
439      * and avoiding more is of benefit.
440      *
441      * @return int
442      */
443     protected function reduce_for_maxsize() {
444         $diff = $this->storecount - $this->maxsize;
445         if ($diff < 1) {
446             return 0;
447         }
448         // Reduce it by an extra 10% to avoid calling this repetitively if we are in a loop.
449         $diff += floor($this->maxsize / 10);
450         $this->store = array_slice($this->store, $diff, null, true);
451         $this->storecount -= $diff;
452         return $diff;
453     }
455     /**
456      * Returns true if the user can add an instance of the store plugin.
457      *
458      * @return bool
459      */
460     public static function can_add_instance() {
461         return false;
462     }
464     /**
465      * Performs any necessary clean up when the store instance is being deleted.
466      */
467     public function instance_deleted() {
468         $this->purge();
469     }
471     /**
472      * Generates an instance of the cache store that can be used for testing.
473      *
474      * @param cache_definition $definition
475      * @return cachestore_session
476      */
477     public static function initialise_test_instance(cache_definition $definition) {
478         // Do something here perhaps.
479         $cache = new cachestore_session('Session test');
480         $cache->initialise($definition);
481         return $cache;
482     }
484     /**
485      * Returns the name of this instance.
486      * @return string
487      */
488     public function my_name() {
489         return $this->name;
490     }
492     /**
493      * Finds all of the keys being stored in the cache store instance.
494      *
495      * @return array
496      */
497     public function find_all() {
498         return array_keys($this->store);
499     }
501     /**
502      * Finds all of the keys whose keys start with the given prefix.
503      *
504      * @param string $prefix
505      */
506     public function find_by_prefix($prefix) {
507         $return = array();
508         foreach ($this->find_all() as $key) {
509             if (strpos($key, $prefix) === 0) {
510                 $return[] = $key;
511             }
512         }
513         return $return;
514     }