MDL-25290 cache: Fixed up redirect loop with admin settings for cache stores
[moodle.git] / cache / stores / memcached / lib.php
CommitLineData
47d89ccf
SH
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/>.
16
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 cache_memcached
23 * @copyright 2012 Sam Hemelryk
24 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
25 */
26
27defined('MOODLE_INTERNAL') || die();
28
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 */
46class cache_store_memcached implements cache_store {
47
48 /**
49 * The name of the store
50 * @var store
51 */
52 protected $name;
53
54 /**
55 * The memcached connection
56 * @var Memcached
57 */
58 protected $connection;
59
60 /**
61 * An array of servers to use during connection
62 * @var array
63 */
64 protected $servers = array();
65
66 /**
67 * The options used when establishing the connection
68 * @var array
69 */
70 protected $options = array();
71
72 /**
73 * True when this instance is ready to be initialised.
74 * @var bool
75 */
76 protected $isready = false;
77
78 /**
79 * The cache definition this store was initialised with.
80 * @var cache_definition
81 */
82 protected $definition;
83
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
100 $compression = array_key_exists('compression', $configuration) ? (bool)$configuration['compression'] : true;
101 $serialiser = (array_key_exists('serialiser', $configuration)) ? (int)$configuration['serialiser'] : Memcached::SERIALIZER_PHP;
102 $prefix = (!empty($configuration['prefix'])) ? (string)$configuration['prefix'] : crc32($name);
103 $hashmethod = (array_key_exists('hash', $configuration)) ? (int)$configuration['hash'] : Memcached::HASH_DEFAULT;
104 $bufferwrites = array_key_exists('bufferwrites', $configuration) ? (bool)$configuration['bufferwrites'] : false;
105
106 foreach ($configuration['servers'] as $server) {
107 if (!is_array($server)) {
108 $server = explode(':', $server, 3);
109 }
110 if (!array_key_exists(1, $server)) {
111 $server[1] = 11211;
112 $server[2] = 100;
113 } else if (!array_key_exists(2, $server)) {
114 $server[2] = 100;
115 }
116 $this->servers[] = $server;
117 }
118 $this->options[Memcached::OPT_COMPRESSION] = $compression;
119 $this->options[Memcached::OPT_SERIALIZER] = $serialiser;
120 $this->options[Memcached::OPT_PREFIX_KEY] = $prefix;
121 $this->options[Memcached::OPT_HASH] = $hashmethod;
122 $this->options[Memcached::OPT_BUFFER_WRITES] = $bufferwrites;
123
124 $this->isready = true;
125 }
126
127 /**
128 * Initialises the cache.
129 *
130 * Once this has been done the cache is all set to be used.
131 *
132 * @param cache_definition $definition
133 */
134 public function initialise(cache_definition $definition) {
135 if ($this->is_initialised()) {
136 throw new coding_exception('This memcached instance has already been initialised.');
137 }
138 $this->definition = $definition;
139 $this->connection = new Memcached(crc32($this->name));
140 $servers = $this->connection->getServerList();
141 if (empty($servers)) {
142 foreach ($this->options as $key => $value) {
143 $this->connection->setOption($key, $value);
144 }
145 $this->connection->addServers($this->servers);
146 }
147 }
148
149 /**
150 * Returns true once this instance has been initialised.
151 *
152 * @return bool
153 */
154 public function is_initialised() {
155 return ($this->connection !== null);
156 }
157
158 /**
159 * Returns true if this store instance is ready to be used.
160 * @return bool
161 */
162 public function is_ready() {
163 return $this->isready;
164 }
165
166 /**
167 * Returns true if the store requirements are met.
168 *
169 * @return bool
170 */
171 public static function are_requirements_met() {
172 return class_exists('Memcached');
173 }
174
175 /**
176 * Returns true if the given mode is supported by this store.
177 *
178 * @param int $mode One of cache_store::MODE_*
179 * @return bool
180 */
181 public static function is_supported_mode($mode) {
182 return ($mode === self::MODE_APPLICATION || $mode === self::MODE_SESSION);
183 }
184
185 /**
186 * Returns the supported features as a combined int.
187 *
188 * @param array $configuration
189 * @return int
190 */
191 public static function get_supported_features(array $configuration = array()) {
192 return self::SUPPORTS_NATIVE_TTL;
193 }
194
195 /**
196 * Returns true if the store instance supports multiple identifiers.
197 *
198 * @return bool
199 */
200 public function supports_multiple_indentifiers() {
201 return false;
202 }
203
204 /**
205 * Returns true if the store instance guarantees data.
206 *
207 * @return bool
208 */
209 public function supports_data_guarantee() {
210 return false;
211 }
212
213 /**
214 * Returns true if the store instance supports native ttl.
215 *
216 * @return bool
217 */
218 public function supports_native_ttl() {
219 return true;
220 }
221
222 /**
223 * Returns the supported modes as a combined int.
224 *
225 * @param array $configuration
226 * @return int
227 */
228 public static function get_supported_modes(array $configuration = array()) {
229 return self::MODE_APPLICATION + self::MODE_SESSION;
230 }
231
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 return $this->connection->get($key);
240 }
241
242 /**
243 * Retrieves several items from the cache store in a single transaction.
244 *
245 * 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.
246 *
247 * @param array $keys The array of keys to retrieve
248 * @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
249 * be set to false.
250 */
251 public function get_many($keys) {
252 $result = $this->connection->getMulti($keys);
253 if (!is_array($result)) {
254 $result = array();
255 }
256 foreach ($keys as $key) {
257 if (!array_key_exists($key, $result)) {
258 $result[$key] = false;
259 }
260 }
261 return $result;
262 }
263
264 /**
265 * Sets an item in the cache given its key and data value.
266 *
267 * @param string $key The key to use.
268 * @param mixed $data The data to set.
269 * @return bool True if the operation was a success false otherwise.
270 */
271 public function set($key, $data) {
272 return $this->connection->set($key, $data, $this->definition->get_ttl());
273 }
274
275 /**
276 * Sets many items in the cache in a single transaction.
277 *
278 * @param array $keyvaluearray An array of key value pairs. Each item in the array will be an associative array with two
279 * keys, 'key' and 'value'.
280 * @return int The number of items successfully set. It is up to the developer to check this matches the number of items
281 * sent ... if they care that is.
282 */
283 public function set_many(array $keyvaluearray) {
284 $pairs = array();
285 foreach ($keyvaluearray as $pair) {
286 $pairs[$pair['key']] = $pair['value'];
287 }
288 if ($this->connection->setMulti($pairs, $this->definition->get_ttl())) {
289 return count($keyvaluearray);
290 }
291 return 0;
292 }
293
294 /**
295 * Deletes an item from the cache store.
296 *
297 * @param string $key The key to delete.
298 * @return bool Returns true if the operation was a success, false otherwise.
299 */
300 public function delete($key) {
301 return $this->connection->delete($key);
302 }
303
304 /**
305 * Deletes several keys from the cache in a single action.
306 *
307 * @param array $keys The keys to delete
308 * @return int The number of items successfully deleted.
309 */
310 public function delete_many(array $keys) {
311 $count = 0;
312 foreach ($keys as $key) {
313 if ($this->connection->delete($key)) {
314 $count++;
315 }
316 }
317 return $count;
318 }
319
320 /**
321 * Purges the cache deleting all items within it.
322 *
323 * @return boolean True on success. False otherwise.
324 */
325 public function purge() {
326 $this->connection->flush();
327 return true;
328 }
329
330 /**
331 * Gets an array of options to use as the serialiser.
332 * @return array
333 */
334 public static function config_get_serialiser_options() {
335 $options = array(
336 Memcached::SERIALIZER_PHP => get_string('serialiser_php', 'cache_memcached')
337 );
338 if (Memcached::HAVE_JSON) {
339 $options[Memcached::SERIALIZER_JSON] = get_string('serialiser_json', 'cache_memcached');
340 }
341 if (Memcached::HAVE_IGBINARY) {
342 $options[Memcached::SERIALIZER_IGBINARY] = get_string('serialiser_php', 'cache_memcached');
343 }
344 return $options;
345 }
346
347 /**
348 * Gets an array of hash options available during configuration.
349 * @return array
350 */
351 public static function config_get_hash_options() {
352 $options = array(
353 Memcached::HASH_DEFAULT => get_string('hash_default', 'cache_memcached'),
354 Memcached::HASH_MD5 => get_string('hash_md5', 'cache_memcached'),
355 Memcached::HASH_CRC => get_string('hash_crc', 'cache_memcached'),
356 Memcached::HASH_FNV1_64 => get_string('hash_fnv1_64', 'cache_memcached'),
357 Memcached::HASH_FNV1A_64 => get_string('hash_fnv1a_64', 'cache_memcached'),
358 Memcached::HASH_FNV1_32 => get_string('hash_fnv1_32', 'cache_memcached'),
359 Memcached::HASH_FNV1A_32 => get_string('hash_fnv1a_32', 'cache_memcached'),
360 Memcached::HASH_HSIEH => get_string('hash_hsieh', 'cache_memcached'),
361 Memcached::HASH_MURMUR => get_string('hash_murmur', 'cache_memcached'),
362 );
363 return $options;
364 }
365
366 /**
367 * Given the data from the add instance form this function creates a configuration array.
368 *
369 * @param stdClass $data
370 * @return array
371 */
372 public static function config_get_configuration_array($data) {
373 $lines = explode("\n", $data->servers);
374 $servers = array();
375 foreach ($lines as $line) {
376 $line = trim($line, ':');
377 $servers[] = explode(':', $line, 3);
378 }
379 return array(
380 'servers' => $servers,
381 'compression' => $data->compression,
382 'serialiser' => $data->serialiser,
383 'prefix' => $data->prefix,
384 'hash' => $data->hash,
385 'bufferwrites' => $data->bufferwrites,
386 );
387 }
388
389 /**
390 * Returns true if the user can add an instance of the store plugin.
391 *
392 * @return bool
393 */
394 public static function can_add_instance() {
395 return true;
396 }
397
398 /**
399 * Performs any necessary clean up when the store instance is being deleted.
400 */
401 public function cleanup() {
402 $this->purge();
403 }
404
405 /**
406 * Generates an instance of the cache store that can be used for testing.
407 *
408 * @param cache_definition $definition
409 * @return false
410 */
411 public static function initialise_test_instance(cache_definition $definition) {
412
413 if (!self::are_requirements_met()) {
414 return false;
415 }
416
417 $config = get_config('cache_memcached');
418 if (empty($config->testservers)) {
419 return false;
420 }
421
422 $configuration = array();
423 $configuration['servers'] = $config->testservers;
424 if (!empty($config->testcompression)) {
425 $configuration['compression'] = $config->testcompression;
426 }
427 if (!empty($config->testserialiser)) {
428 $configuration['serialiser'] = $config->testserialiser;
429 }
430 if (!empty($config->testprefix)) {
431 $configuration['prefix'] = $config->testprefix;
432 }
433 if (!empty($config->testhash)) {
434 $configuration['hash'] = $config->testhash;
435 }
436 if (!empty($config->testbufferwrites)) {
437 $configuration['bufferwrites'] = $config->testbufferwrites;
438 }
439
440 $store = new cache_store_memcached('Test memcached', $configuration);
441 $store->initialise($definition);
442
443 return $store;
444 }
445}