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