d757157536c7c29a65ca9a08c6b7c8fa6b73c59d
[moodle.git] / cache / classes / store.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 store - base class
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  * Cache store interface.
33  *
34  * This interface defines the static methods that must be implemented by every cache store plugin.
35  * To ensure plugins implement this class the abstract cache_store class implements this interface.
36  *
37  * @package    core
38  * @category   cache
39  * @copyright  2012 Sam Hemelryk
40  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
41  */
42 interface cache_store_interface {
43     /**
44      * Static method to check if the store requirements are met.
45      *
46      * @return bool True if the stores software/hardware requirements have been met and it can be used. False otherwise.
47      */
48     public static function are_requirements_met();
50     /**
51      * Static method to check if a store is usable with the given mode.
52      *
53      * @param int $mode One of cache_store::MODE_*
54      */
55     public static function is_supported_mode($mode);
57     /**
58      * Returns the supported features as a binary flag.
59      *
60      * @param array $configuration The configuration of a store to consider specifically.
61      * @return int The supported features.
62      */
63     public static function get_supported_features(array $configuration = array());
65     /**
66      * Returns the supported modes as a binary flag.
67      *
68      * @param array $configuration The configuration of a store to consider specifically.
69      * @return int The supported modes.
70      */
71     public static function get_supported_modes(array $configuration = array());
73     /**
74      * Generates an instance of the cache store that can be used for testing.
75      *
76      * Returns an instance of the cache store, or false if one cannot be created.
77      *
78      * @param cache_definition $definition
79      * @return cache_store|false
80      */
81     public static function initialise_test_instance(cache_definition $definition);
82 }
84 /**
85  * Abstract cache store class.
86  *
87  * All cache store plugins must extend this base class.
88  * It lays down the foundation for what is required of a cache store plugin.
89  *
90  * @since 2.4
91  * @package    core
92  * @category   cache
93  * @copyright  2012 Sam Hemelryk
94  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
95  */
96 abstract class cache_store implements cache_store_interface {
98     // Constants for features a cache store can support
100     /**
101      * Supports multi-part keys
102      */
103     const SUPPORTS_MULTIPLE_IDENTIFIERS = 1;
104     /**
105      * Ensures data remains in the cache once set.
106      */
107     const SUPPORTS_DATA_GUARANTEE = 2;
108     /**
109      * Supports a native ttl system.
110      */
111     const SUPPORTS_NATIVE_TTL = 4;
113     /**
114      * The cache is searchable by key.
115      */
116     const IS_SEARCHABLE = 8;
118     // Constants for the modes of a cache store
120     /**
121      * Application caches. These are shared caches.
122      */
123     const MODE_APPLICATION = 1;
124     /**
125      * Session caches. Just access to the PHP session.
126      */
127     const MODE_SESSION = 2;
128     /**
129      * Request caches. Static caches really.
130      */
131     const MODE_REQUEST = 4;
133     /**
134      * Constructs an instance of the cache store.
135      *
136      * The constructor should be responsible for creating anything needed by the store that is not
137      * specific to a definition.
138      * Tasks such as opening a connection to check it is available are best done here.
139      * Tasks that are definition specific such as creating a storage area for the definition data
140      * or creating key tables and indexs are best done within the initialise method.
141      *
142      * Once a store has been constructed the cache API will check it is ready to be intialised with
143      * a definition by called $this->is_ready().
144      * If the setup of the store failed (connection could not be established for example) then
145      * that method should return false so that the store instance is not selected for use.
146      *
147      * @param string $name The name of the cache store
148      * @param array $configuration The configuration for this store instance.
149      */
150     abstract public function __construct($name, array $configuration = array());
152     /**
153      * Returns the name of this store instance.
154      * @return string
155      */
156     abstract public function my_name();
158     /**
159      * Initialises a new instance of the cache store given the definition the instance is to be used for.
160      *
161      * This function should be used to run any definition specific setup the store instance requires.
162      * Tasks such as creating storage areas, or creating indexes are best done here.
163      *
164      * Its important to note that the initialise method is expected to always succeed.
165      * If there are setup tasks that may fail they should be done within the __construct method
166      * and should they fail is_ready should return false.
167      *
168      * @param cache_definition $definition
169      */
170     abstract public function initialise(cache_definition $definition);
172     /**
173      * Returns true if this cache store instance has been initialised.
174      * @return bool
175      */
176     abstract public function is_initialised();
178     /**
179      * Returns true if this cache store instance is ready to use.
180      * @return bool
181      */
182     abstract public function is_ready();
184     /**
185      * Retrieves an item from the cache store given its key.
186      *
187      * @param string $key The key to retrieve
188      * @return mixed The data that was associated with the key, or false if the key did not exist.
189      */
190     abstract public function get($key);
192     /**
193      * Retrieves several items from the cache store in a single transaction.
194      *
195      * 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.
196      *
197      * @param array $keys The array of keys to retrieve
198      * @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
199      *      be set to false.
200      */
201     abstract public function get_many($keys);
203     /**
204      * Sets an item in the cache given its key and data value.
205      *
206      * @param string $key The key to use.
207      * @param mixed $data The data to set.
208      * @return bool True if the operation was a success false otherwise.
209      */
210     abstract public function set($key, $data);
212     /**
213      * Sets many items in the cache in a single transaction.
214      *
215      * @param array $keyvaluearray An array of key value pairs. Each item in the array will be an associative array with two
216      *      keys, 'key' and 'value'.
217      * @return int The number of items successfully set. It is up to the developer to check this matches the number of items
218      *      sent ... if they care that is.
219      */
220     abstract public function set_many(array $keyvaluearray);
222     /**
223      * Deletes an item from the cache store.
224      *
225      * @param string $key The key to delete.
226      * @return bool Returns true if the operation was a success, false otherwise.
227      */
228     abstract public function delete($key);
230     /**
231      * Deletes several keys from the cache in a single action.
232      *
233      * @param array $keys The keys to delete
234      * @return int The number of items successfully deleted.
235      */
236     abstract public function delete_many(array $keys);
238     /**
239      * Purges the cache deleting all items within it.
240      *
241      * @return boolean True on success. False otherwise.
242      */
243     abstract public function purge();
245     /**
246      * Performs any necessary clean up when the store instance is being deleted.
247      *
248      * @deprecated since 2.5
249      */
250     public function cleanup() {
251         debugging('This function has been renamed to instance_deleted. Please update your calls.', DEBUG_DEVELOPER);
252     }
254     /**
255      * Performs any necessary operation when the store instance has been created.
256      *
257      * @since 2.5
258      */
259     public function instance_created() {
260         // By default, do nothing.
261     }
263     /**
264      * Performs any necessary operation when the store instance is being deleted.
265      *
266      * This method may be called before the store has been initialised.
267      *
268      * @since 2.5
269      * @see cleanup()
270      */
271     public function instance_deleted() {
272         if (method_exists($this, 'cleanup')) {
273             // There used to be a legacy function called cleanup, it was renamed to instance delete.
274             // To be removed in 2.6.
275             $this->cleanup();
276         }
277     }
279     /**
280      * Returns true if the user can add an instance of the store plugin.
281      *
282      * @return bool
283      */
284     public static function can_add_instance() {
285         return true;
286     }
288     /**
289      * Returns true if the store instance guarantees data.
290      *
291      * @return bool
292      */
293     public function supports_data_guarantee() {
294         return $this::get_supported_features() & self::SUPPORTS_DATA_GUARANTEE;
295     }
297     /**
298      * Returns true if the store instance supports multiple identifiers.
299      *
300      * @return bool
301      */
302     public function supports_multiple_identifiers() {
303         return $this::get_supported_features() & self::SUPPORTS_MULTIPLE_IDENTIFIERS;
304     }
306     /**
307      * Returns true if the store instance supports native ttl.
308      *
309      * @return bool
310      */
311     public function supports_native_ttl() {
312         return $this::get_supported_features() & self::SUPPORTS_NATIVE_TTL;
313     }
315     /**
316      * Returns true if the store instance is searchable.
317      *
318      * @return bool
319      */
320     public function is_searchable() {
321         return in_array('cache_is_searchable', class_implements($this));
322     }
324     /**
325      * Creates a clone of this store instance ready to be initialised.
326      *
327      * This method is used so that a cache store needs only be constructed once.
328      * Future requests for an instance of the store will be given a cloned instance.
329      *
330      * If you are writing a cache store that isn't compatible with the clone operation
331      * you can override this method to handle any situations you want before cloning.
332      *
333      * @param array $details An array containing the details of the store from the cache config.
334      * @return cache_store
335      */
336     public function create_clone(array $details = array()) {
337         // By default we just run clone.
338         // Any stores that have an issue with this will need to override the create_clone method.
339         return clone($this);
340     }