on-demand release 2.6beta+
[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 extends cache_store implements cache_is_configurable {
47     /**
48      * The name of the store
49      * @var store
50      */
51     protected $name;
53     /**
54      * The memcached connection
55      * @var Memcached
56      */
57     protected $connection;
59     /**
60      * An array of servers to use during connection
61      * @var array
62      */
63     protected $servers = array();
65     /**
66      * The options used when establishing the connection
67      * @var array
68      */
69     protected $options = array();
71     /**
72      * True when this instance is ready to be initialised.
73      * @var bool
74      */
75     protected $isready = false;
77     /**
78      * Set to true when this store instance has been initialised.
79      * @var bool
80      */
81     protected $isinitialised = false;
83     /**
84      * The cache definition this store was initialised with.
85      * @var cache_definition
86      */
87     protected $definition;
89     /**
90      * Constructs the store instance.
91      *
92      * Noting that this function is not an initialisation. It is used to prepare the store for use.
93      * The store will be initialised when required and will be provided with a cache_definition at that time.
94      *
95      * @param string $name
96      * @param array $configuration
97      */
98     public function __construct($name, array $configuration = array()) {
99         $this->name = $name;
100         if (!array_key_exists('servers', $configuration) || empty($configuration['servers'])) {
101             // Nothing configured.
102             return;
103         }
104         if (!is_array($configuration['servers'])) {
105             $configuration['servers'] = array($configuration['servers']);
106         }
108         $compression = array_key_exists('compression', $configuration) ? (bool)$configuration['compression'] : true;
109         if (array_key_exists('serialiser', $configuration)) {
110             $serialiser = (int)$configuration['serialiser'];
111         } else {
112             $serialiser = Memcached::SERIALIZER_PHP;
113         }
114         $prefix = (!empty($configuration['prefix'])) ? (string)$configuration['prefix'] : crc32($name);
115         $hashmethod = (array_key_exists('hash', $configuration)) ? (int)$configuration['hash'] : Memcached::HASH_DEFAULT;
116         $bufferwrites = array_key_exists('bufferwrites', $configuration) ? (bool)$configuration['bufferwrites'] : false;
118         foreach ($configuration['servers'] as $server) {
119             if (!is_array($server)) {
120                 $server = explode(':', $server, 3);
121             }
122             if (!array_key_exists(1, $server)) {
123                 $server[1] = 11211;
124                 $server[2] = 100;
125             } else if (!array_key_exists(2, $server)) {
126                 $server[2] = 100;
127             }
128             $this->servers[] = $server;
129         }
130         $this->options[Memcached::OPT_COMPRESSION] = $compression;
131         $this->options[Memcached::OPT_SERIALIZER] = $serialiser;
132         $this->options[Memcached::OPT_PREFIX_KEY] = $prefix;
133         $this->options[Memcached::OPT_HASH] = $hashmethod;
134         $this->options[Memcached::OPT_BUFFER_WRITES] = $bufferwrites;
136         $this->connection = new Memcached(crc32($this->name));
137         $servers = $this->connection->getServerList();
138         if (empty($servers)) {
139             foreach ($this->options as $key => $value) {
140                 $this->connection->setOption($key, $value);
141             }
142             $this->connection->addServers($this->servers);
143         }
144         // Test the connection to the pool of servers.
145         $this->isready = @$this->connection->set("ping", 'ping', 1);
146     }
148     /**
149      * Initialises the cache.
150      *
151      * Once this has been done the cache is all set to be used.
152      *
153      * @param cache_definition $definition
154      */
155     public function initialise(cache_definition $definition) {
156         if ($this->is_initialised()) {
157             throw new coding_exception('This memcached instance has already been initialised.');
158         }
159         $this->definition = $definition;
160         $this->isinitialised = true;
161     }
163     /**
164      * Returns true once this instance has been initialised.
165      *
166      * @return bool
167      */
168     public function is_initialised() {
169         return ($this->isinitialised);
170     }
172     /**
173      * Returns true if this store instance is ready to be used.
174      * @return bool
175      */
176     public function is_ready() {
177         return $this->isready;
178     }
180     /**
181      * Returns true if the store requirements are met.
182      *
183      * @return bool
184      */
185     public static function are_requirements_met() {
186         return class_exists('Memcached');
187     }
189     /**
190      * Returns true if the given mode is supported by this store.
191      *
192      * @param int $mode One of cache_store::MODE_*
193      * @return bool
194      */
195     public static function is_supported_mode($mode) {
196         return ($mode === self::MODE_APPLICATION || $mode === self::MODE_SESSION);
197     }
199     /**
200      * Returns the supported features as a combined int.
201      *
202      * @param array $configuration
203      * @return int
204      */
205     public static function get_supported_features(array $configuration = array()) {
206         return self::SUPPORTS_NATIVE_TTL;
207     }
209     /**
210      * Returns false as this store does not support multiple identifiers.
211      * (This optional function is a performance optimisation; it must be
212      * consistent with the value from get_supported_features.)
213      *
214      * @return bool False
215      */
216     public function supports_multiple_identifiers() {
217         return false;
218     }
220     /**
221      * Returns the supported modes as a combined int.
222      *
223      * @param array $configuration
224      * @return int
225      */
226     public static function get_supported_modes(array $configuration = array()) {
227         return self::MODE_APPLICATION + self::MODE_SESSION;
228     }
230     /**
231      * Retrieves an item from the cache store given its key.
232      *
233      * @param string $key The key to retrieve
234      * @return mixed The data that was associated with the key, or false if the key did not exist.
235      */
236     public function get($key) {
237         return $this->connection->get($key);
238     }
240     /**
241      * Retrieves several items from the cache store in a single transaction.
242      *
243      * 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.
244      *
245      * @param array $keys The array of keys to retrieve
246      * @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
247      *      be set to false.
248      */
249     public function get_many($keys) {
250         $result = $this->connection->getMulti($keys);
251         if (!is_array($result)) {
252             $result = array();
253         }
254         foreach ($keys as $key) {
255             if (!array_key_exists($key, $result)) {
256                 $result[$key] = false;
257             }
258         }
259         return $result;
260     }
262     /**
263      * Sets an item in the cache given its key and data value.
264      *
265      * @param string $key The key to use.
266      * @param mixed $data The data to set.
267      * @return bool True if the operation was a success false otherwise.
268      */
269     public function set($key, $data) {
270         return $this->connection->set($key, $data, $this->definition->get_ttl());
271     }
273     /**
274      * Sets many items in the cache in a single transaction.
275      *
276      * @param array $keyvaluearray An array of key value pairs. Each item in the array will be an associative array with two
277      *      keys, 'key' and 'value'.
278      * @return int The number of items successfully set. It is up to the developer to check this matches the number of items
279      *      sent ... if they care that is.
280      */
281     public function set_many(array $keyvaluearray) {
282         $pairs = array();
283         foreach ($keyvaluearray as $pair) {
284             $pairs[$pair['key']] = $pair['value'];
285         }
286         if ($this->connection->setMulti($pairs, $this->definition->get_ttl())) {
287             return count($keyvaluearray);
288         }
289         return 0;
290     }
292     /**
293      * Deletes an item from the cache store.
294      *
295      * @param string $key The key to delete.
296      * @return bool Returns true if the operation was a success, false otherwise.
297      */
298     public function delete($key) {
299         return $this->connection->delete($key);
300     }
302     /**
303      * Deletes several keys from the cache in a single action.
304      *
305      * @param array $keys The keys to delete
306      * @return int The number of items successfully deleted.
307      */
308     public function delete_many(array $keys) {
309         $count = 0;
310         foreach ($keys as $key) {
311             if ($this->connection->delete($key)) {
312                 $count++;
313             }
314         }
315         return $count;
316     }
318     /**
319      * Purges the cache deleting all items within it.
320      *
321      * @return boolean True on success. False otherwise.
322      */
323     public function purge() {
324         if ($this->isready) {
325             $this->connection->flush();
326         }
328         return true;
329     }
331     /**
332      * Gets an array of options to use as the serialiser.
333      * @return array
334      */
335     public static function config_get_serialiser_options() {
336         $options = array(
337             Memcached::SERIALIZER_PHP => get_string('serialiser_php', 'cachestore_memcached')
338         );
339         if (Memcached::HAVE_JSON) {
340             $options[Memcached::SERIALIZER_JSON] = get_string('serialiser_json', 'cachestore_memcached');
341         }
342         if (Memcached::HAVE_IGBINARY) {
343             $options[Memcached::SERIALIZER_IGBINARY] = get_string('serialiser_igbinary', 'cachestore_memcached');
344         }
345         return $options;
346     }
348     /**
349      * Gets an array of hash options available during configuration.
350      * @return array
351      */
352     public static function config_get_hash_options() {
353         $options = array(
354             Memcached::HASH_DEFAULT => get_string('hash_default', 'cachestore_memcached'),
355             Memcached::HASH_MD5 => get_string('hash_md5', 'cachestore_memcached'),
356             Memcached::HASH_CRC => get_string('hash_crc', 'cachestore_memcached'),
357             Memcached::HASH_FNV1_64 => get_string('hash_fnv1_64', 'cachestore_memcached'),
358             Memcached::HASH_FNV1A_64 => get_string('hash_fnv1a_64', 'cachestore_memcached'),
359             Memcached::HASH_FNV1_32 => get_string('hash_fnv1_32', 'cachestore_memcached'),
360             Memcached::HASH_FNV1A_32 => get_string('hash_fnv1a_32', 'cachestore_memcached'),
361             Memcached::HASH_HSIEH => get_string('hash_hsieh', 'cachestore_memcached'),
362             Memcached::HASH_MURMUR => get_string('hash_murmur', 'cachestore_memcached'),
363         );
364         return $options;
365     }
367     /**
368      * Given the data from the add instance form this function creates a configuration array.
369      *
370      * @param stdClass $data
371      * @return array
372      */
373     public static function config_get_configuration_array($data) {
374         $lines = explode("\n", $data->servers);
375         $servers = array();
376         foreach ($lines as $line) {
377             $line = trim($line, ':');
378             $servers[] = explode(':', $line, 3);
379         }
380         return array(
381             'servers' => $servers,
382             'compression' => $data->compression,
383             'serialiser' => $data->serialiser,
384             'prefix' => $data->prefix,
385             'hash' => $data->hash,
386             'bufferwrites' => $data->bufferwrites,
387         );
388     }
390     /**
391      * Allows the cache store to set its data against the edit form before it is shown to the user.
392      *
393      * @param moodleform $editform
394      * @param array $config
395      */
396     public static function config_set_edit_form_data(moodleform $editform, array $config) {
397         $data = array();
398         if (!empty($config['servers'])) {
399             $servers = array();
400             foreach ($config['servers'] as $server) {
401                 $servers[] = join(":", $server);
402             }
403             $data['servers'] = join("\n", $servers);
404         }
405         if (isset($config['compression'])) {
406             $data['compression'] = (bool)$config['compression'];
407         }
408         if (!empty($config['serialiser'])) {
409             $data['serialiser'] = $config['serialiser'];
410         }
411         if (!empty($config['prefix'])) {
412             $data['prefix'] = $config['prefix'];
413         }
414         if (!empty($config['hash'])) {
415             $data['hash'] = $config['hash'];
416         }
417         if (isset($config['bufferwrites'])) {
418             $data['bufferwrites'] = (bool)$config['bufferwrites'];
419         }
420         $editform->set_data($data);
421     }
423     /**
424      * Performs any necessary clean up when the store instance is being deleted.
425      */
426     public function instance_deleted() {
427         if ($this->connection) {
428             $connection = $this->connection;
429         } else {
430             $connection = new Memcached(crc32($this->name));
431             $servers = $connection->getServerList();
432             if (empty($servers)) {
433                 foreach ($this->options as $key => $value) {
434                     $connection->setOption($key, $value);
435                 }
436                 $connection->addServers($this->servers);
437             }
438         }
439         @$connection->flush();
440         unset($connection);
441         unset($this->connection);
442     }
444     /**
445      * Generates an instance of the cache store that can be used for testing.
446      *
447      * @param cache_definition $definition
448      * @return cachestore_memcached|false
449      */
450     public static function initialise_test_instance(cache_definition $definition) {
452         if (!self::are_requirements_met()) {
453             return false;
454         }
456         $config = get_config('cachestore_memcached');
457         if (empty($config->testservers)) {
458             return false;
459         }
461         $configuration = array();
462         $configuration['servers'] = $config->testservers;
463         if (!empty($config->testcompression)) {
464             $configuration['compression'] = $config->testcompression;
465         }
466         if (!empty($config->testserialiser)) {
467             $configuration['serialiser'] = $config->testserialiser;
468         }
469         if (!empty($config->testprefix)) {
470             $configuration['prefix'] = $config->testprefix;
471         }
472         if (!empty($config->testhash)) {
473             $configuration['hash'] = $config->testhash;
474         }
475         if (!empty($config->testbufferwrites)) {
476             $configuration['bufferwrites'] = $config->testbufferwrites;
477         }
479         $store = new cachestore_memcached('Test memcached', $configuration);
480         $store->initialise($definition);
482         return $store;
483     }
485     /**
486      * Returns the name of this instance.
487      * @return string
488      */
489     public function my_name() {
490         return $this->name;
491     }