419e640c8c7fc1c6be6de63967f8ce874c473566
[moodle.git] / cache / stores / memcached / 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 memcached cache store.
19  *
20  * This file is part of the memcached cache store, it contains the API for interacting with an instance of the store.
21  *
22  * @package    cachestore_memcached
23  * @copyright  2012 Sam Hemelryk
24  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
25  */
27 defined('MOODLE_INTERNAL') || die();
29 /**
30  * The memcached store.
31  *
32  * (Not to be confused with the memcache store)
33  *
34  * Configuration options:
35  *      servers:        string: host:port:weight , ...
36  *      compression:    true, false
37  *      serialiser:     SERIALIZER_PHP, SERIALIZER_JSON, SERIALIZER_IGBINARY
38  *      prefix:         string: defaults to instance name
39  *      hashmethod:     HASH_DEFAULT, HASH_MD5, HASH_CRC, HASH_FNV1_64, HASH_FNV1A_64, HASH_FNV1_32,
40  *                      HASH_FNV1A_32, HASH_HSIEH, HASH_MURMUR
41  *      bufferwrites:   true, false
42  *
43  * @copyright  2012 Sam Hemelryk
44  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
45  */
46 class cachestore_memcached implements cache_store {
48     /**
49      * The name of the store
50      * @var store
51      */
52     protected $name;
54     /**
55      * The memcached connection
56      * @var Memcached
57      */
58     protected $connection;
60     /**
61      * An array of servers to use during connection
62      * @var array
63      */
64     protected $servers = array();
66     /**
67      * The options used when establishing the connection
68      * @var array
69      */
70     protected $options = array();
72     /**
73      * True when this instance is ready to be initialised.
74      * @var bool
75      */
76     protected $isready = false;
78     /**
79      * The cache definition this store was initialised with.
80      * @var cache_definition
81      */
82     protected $definition;
84     /**
85      * Constructs the store instance.
86      *
87      * Noting that this function is not an initialisation. It is used to prepare the store for use.
88      * The store will be initialised when required and will be provided with a cache_definition at that time.
89      *
90      * @param string $name
91      * @param array $configuration
92      */
93     public function __construct($name, array $configuration = array()) {
94         $this->name = $name;
95         if (!array_key_exists('servers', $configuration) || empty($configuration['servers'])) {
96             // Nothing configured.
97             return;
98         }
99         if (!is_array($configuration['servers'])) {
100             $configuration['servers'] = array($configuration['servers']);
101         }
103         $compression = array_key_exists('compression', $configuration) ? (bool)$configuration['compression'] : true;
104         if (array_key_exists('serialiser', $configuration)) {
105             $serialiser = (int)$configuration['serialiser'];
106         } else {
107             $serialiser = Memcached::SERIALIZER_PHP;
108         }
109         $prefix = (!empty($configuration['prefix'])) ? (string)$configuration['prefix'] : crc32($name);
110         $hashmethod = (array_key_exists('hash', $configuration)) ? (int)$configuration['hash'] : Memcached::HASH_DEFAULT;
111         $bufferwrites = array_key_exists('bufferwrites', $configuration) ? (bool)$configuration['bufferwrites'] : false;
113         foreach ($configuration['servers'] as $server) {
114             if (!is_array($server)) {
115                 $server = explode(':', $server, 3);
116             }
117             if (!array_key_exists(1, $server)) {
118                 $server[1] = 11211;
119                 $server[2] = 100;
120             } else if (!array_key_exists(2, $server)) {
121                 $server[2] = 100;
122             }
123             $this->servers[] = $server;
124         }
125         $this->options[Memcached::OPT_COMPRESSION] = $compression;
126         $this->options[Memcached::OPT_SERIALIZER] = $serialiser;
127         $this->options[Memcached::OPT_PREFIX_KEY] = $prefix;
128         $this->options[Memcached::OPT_HASH] = $hashmethod;
129         $this->options[Memcached::OPT_BUFFER_WRITES] = $bufferwrites;
131         $this->isready = true;
132     }
134     /**
135      * Initialises the cache.
136      *
137      * Once this has been done the cache is all set to be used.
138      *
139      * @param cache_definition $definition
140      */
141     public function initialise(cache_definition $definition) {
142         if ($this->is_initialised()) {
143             throw new coding_exception('This memcached instance has already been initialised.');
144         }
145         $this->definition = $definition;
146         $this->connection = new Memcached(crc32($this->name));
147         $servers = $this->connection->getServerList();
148         if (empty($servers)) {
149             foreach ($this->options as $key => $value) {
150                 $this->connection->setOption($key, $value);
151             }
152             $this->connection->addServers($this->servers);
153         }
154     }
156     /**
157      * Returns true once this instance has been initialised.
158      *
159      * @return bool
160      */
161     public function is_initialised() {
162         return ($this->connection !== null);
163     }
165     /**
166      * Returns true if this store instance is ready to be used.
167      * @return bool
168      */
169     public function is_ready() {
170         return $this->isready;
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 class_exists('Memcached');
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_APPLICATION || $mode === self::MODE_SESSION);
190     }
192     /**
193      * Returns the supported features as a combined int.
194      *
195      * @param array $configuration
196      * @return int
197      */
198     public static function get_supported_features(array $configuration = array()) {
199         return self::SUPPORTS_NATIVE_TTL;
200     }
202     /**
203      * Returns true if the store instance supports multiple identifiers.
204      *
205      * @return bool
206      */
207     public function supports_multiple_identifiers() {
208         return false;
209     }
211     /**
212      * Returns true if the store instance guarantees data.
213      *
214      * @return bool
215      */
216     public function supports_data_guarantee() {
217         return false;
218     }
220     /**
221      * Returns true if the store instance supports native ttl.
222      *
223      * @return bool
224      */
225     public function supports_native_ttl() {
226         return true;
227     }
229     /**
230      * Returns the supported modes as a combined int.
231      *
232      * @param array $configuration
233      * @return int
234      */
235     public static function get_supported_modes(array $configuration = array()) {
236         return self::MODE_APPLICATION + self::MODE_SESSION;
237     }
239     /**
240      * Retrieves an item from the cache store given its key.
241      *
242      * @param string $key The key to retrieve
243      * @return mixed The data that was associated with the key, or false if the key did not exist.
244      */
245     public function get($key) {
246         return $this->connection->get($key);
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         $result = $this->connection->getMulti($keys);
260         if (!is_array($result)) {
261             $result = array();
262         }
263         foreach ($keys as $key) {
264             if (!array_key_exists($key, $result)) {
265                 $result[$key] = false;
266             }
267         }
268         return $result;
269     }
271     /**
272      * Sets an item in the cache given its key and data value.
273      *
274      * @param string $key The key to use.
275      * @param mixed $data The data to set.
276      * @return bool True if the operation was a success false otherwise.
277      */
278     public function set($key, $data) {
279         return $this->connection->set($key, $data, $this->definition->get_ttl());
280     }
282     /**
283      * Sets many items in the cache in a single transaction.
284      *
285      * @param array $keyvaluearray An array of key value pairs. Each item in the array will be an associative array with two
286      *      keys, 'key' and 'value'.
287      * @return int The number of items successfully set. It is up to the developer to check this matches the number of items
288      *      sent ... if they care that is.
289      */
290     public function set_many(array $keyvaluearray) {
291         $pairs = array();
292         foreach ($keyvaluearray as $pair) {
293             $pairs[$pair['key']] = $pair['value'];
294         }
295         if ($this->connection->setMulti($pairs, $this->definition->get_ttl())) {
296             return count($keyvaluearray);
297         }
298         return 0;
299     }
301     /**
302      * Deletes an item from the cache store.
303      *
304      * @param string $key The key to delete.
305      * @return bool Returns true if the operation was a success, false otherwise.
306      */
307     public function delete($key) {
308         return $this->connection->delete($key);
309     }
311     /**
312      * Deletes several keys from the cache in a single action.
313      *
314      * @param array $keys The keys to delete
315      * @return int The number of items successfully deleted.
316      */
317     public function delete_many(array $keys) {
318         $count = 0;
319         foreach ($keys as $key) {
320             if ($this->connection->delete($key)) {
321                 $count++;
322             }
323         }
324         return $count;
325     }
327     /**
328      * Purges the cache deleting all items within it.
329      *
330      * @return boolean True on success. False otherwise.
331      */
332     public function purge() {
333         $this->connection->flush();
334         return true;
335     }
337     /**
338      * Gets an array of options to use as the serialiser.
339      * @return array
340      */
341     public static function config_get_serialiser_options() {
342         $options = array(
343             Memcached::SERIALIZER_PHP => get_string('serialiser_php', 'cachestore_memcached')
344         );
345         if (Memcached::HAVE_JSON) {
346             $options[Memcached::SERIALIZER_JSON] = get_string('serialiser_json', 'cachestore_memcached');
347         }
348         if (Memcached::HAVE_IGBINARY) {
349             $options[Memcached::SERIALIZER_IGBINARY] = get_string('serialiser_php', 'cachestore_memcached');
350         }
351         return $options;
352     }
354     /**
355      * Gets an array of hash options available during configuration.
356      * @return array
357      */
358     public static function config_get_hash_options() {
359         $options = array(
360             Memcached::HASH_DEFAULT => get_string('hash_default', 'cachestore_memcached'),
361             Memcached::HASH_MD5 => get_string('hash_md5', 'cachestore_memcached'),
362             Memcached::HASH_CRC => get_string('hash_crc', 'cachestore_memcached'),
363             Memcached::HASH_FNV1_64 => get_string('hash_fnv1_64', 'cachestore_memcached'),
364             Memcached::HASH_FNV1A_64 => get_string('hash_fnv1a_64', 'cachestore_memcached'),
365             Memcached::HASH_FNV1_32 => get_string('hash_fnv1_32', 'cachestore_memcached'),
366             Memcached::HASH_FNV1A_32 => get_string('hash_fnv1a_32', 'cachestore_memcached'),
367             Memcached::HASH_HSIEH => get_string('hash_hsieh', 'cachestore_memcached'),
368             Memcached::HASH_MURMUR => get_string('hash_murmur', 'cachestore_memcached'),
369         );
370         return $options;
371     }
373     /**
374      * Given the data from the add instance form this function creates a configuration array.
375      *
376      * @param stdClass $data
377      * @return array
378      */
379     public static function config_get_configuration_array($data) {
380         $lines = explode("\n", $data->servers);
381         $servers = array();
382         foreach ($lines as $line) {
383             $line = trim($line, ':');
384             $servers[] = explode(':', $line, 3);
385         }
386         return array(
387             'servers' => $servers,
388             'compression' => $data->compression,
389             'serialiser' => $data->serialiser,
390             'prefix' => $data->prefix,
391             'hash' => $data->hash,
392             'bufferwrites' => $data->bufferwrites,
393         );
394     }
396     /**
397      * Allows the cache store to set its data against the edit form before it is shown to the user.
398      *
399      * @param moodleform $editform
400      * @param array $config
401      */
402     public static function config_set_edit_form_data(moodleform $editform, array $config) {
403         $data = array();
404         if (!empty($config['servers'])) {
405             $servers = array();
406             foreach ($config['servers'] as $server) {
407                 $servers[] = join(":", $server);
408             }
409             $data['servers'] = join("\n", $servers);
410         }
411         if (isset($config['compression'])) {
412             $data['compression'] = (bool)$config['compression'];
413         }
414         if (!empty($config['serialiser'])) {
415             $data['serialiser'] = $config['serialiser'];
416         }
417         if (!empty($config['prefix'])) {
418             $data['prefix'] = $config['prefix'];
419         }
420         if (!empty($config['hash'])) {
421             $data['hash'] = $config['hash'];
422         }
423         if (isset($config['bufferwrites'])) {
424             $data['bufferwrites'] = (bool)$config['bufferwrites'];
425         }
426         $editform->set_data($data);
427     }
429     /**
430      * Returns true if the user can add an instance of the store plugin.
431      *
432      * @return bool
433      */
434     public static function can_add_instance() {
435         return true;
436     }
438     /**
439      * Performs any necessary clean up when the store instance is being deleted.
440      */
441     public function cleanup() {
442         $this->purge();
443     }
445     /**
446      * Generates an instance of the cache store that can be used for testing.
447      *
448      * @param cache_definition $definition
449      * @return false
450      */
451     public static function initialise_test_instance(cache_definition $definition) {
453         if (!self::are_requirements_met()) {
454             return false;
455         }
457         $config = get_config('cachestore_memcached');
458         if (empty($config->testservers)) {
459             return false;
460         }
462         $configuration = array();
463         $configuration['servers'] = $config->testservers;
464         if (!empty($config->testcompression)) {
465             $configuration['compression'] = $config->testcompression;
466         }
467         if (!empty($config->testserialiser)) {
468             $configuration['serialiser'] = $config->testserialiser;
469         }
470         if (!empty($config->testprefix)) {
471             $configuration['prefix'] = $config->testprefix;
472         }
473         if (!empty($config->testhash)) {
474             $configuration['hash'] = $config->testhash;
475         }
476         if (!empty($config->testbufferwrites)) {
477             $configuration['bufferwrites'] = $config->testbufferwrites;
478         }
480         $store = new cachestore_memcached('Test memcached', $configuration);
481         $store->initialise($definition);
483         return $store;
484     }
486     /**
487      * Returns the name of this instance.
488      * @return string
489      */
490     public function my_name() {
491         return $this->name;
492     }