cache/stores/memcache/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/>.
  16
  17 /**
  18  * The library file for the memcache cache store.
  19  *
  20  * This file is part of the memcache cache store, it contains the API for interacting with an instance of the store.
  21  *
  22  * @package    cachestore_memcache
  23  * @copyright  2012 Sam Hemelryk
  24  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  25  */
  26
  27 defined('MOODLE_INTERNAL') || die();
  28
  29 /**
  30  * The memcache store class.
  31  *
  32  * (Not to be confused with memcached store)
  33  *
  34  * Configuration options:
  35  *      servers:        string: host:port:weight , ...
  36  *
  37  * @copyright  2012 Sam Hemelryk
  38  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  39  */
  40 class cachestore_memcache extends cache_store implements cache_is_configurable {
  41
  42     /**
  43      * The name of the store
  44      * @var store
  45      */
  46     protected $name;
  47
  48     /**
  49      * The memcache connection once established.
  50      * @var Memcache
  51      */
  52     protected $connection;
  53
  54     /**
  55      * Key prefix for this memcache.
  56      * @var string
  57      */
  58     protected $prefix;
  59
  60     /**
  61      * An array of servers to use in the connection args.
  62      * @var array
  63      */
  64     protected $servers = array();
  65
  66     /**
  67      * An array of options used when establishing the connection.
  68      * @var array
  69      */
  70     protected $options = array();
  71
  72     /**
  73      * Set to true when things are ready to be initialised.
  74      * @var bool
  75      */
  76     protected $isready = false;
  77
  78     /**
  79      * Set to true once this store instance has been initialised.
  80      * @var bool
  81      */
  82     protected $isinitialised = false;
  83
  84     /**
  85      * The cache definition this store was initialised for.
  86      * @var cache_definition
  87      */
  88     protected $definition;
  89
  90     /**
  91      * Set to true when this store is clustered.
  92      * @var bool
  93      */
  94     protected $clustered = false;
  95
  96     /**
  97      * Array of servers to set when in clustered mode.
  98      * @var array
  99      */
 100     protected $setservers = array();
 101
 102     /**
 103      * The an array of memcache connections for the set servers, once established.
 104      * @var array
 105      */
 106     protected $setconnections = array();
 107
 108     /**
 109      * Default prefix for key names.
 110      * @var string
 111      */
 112     const DEFAULT_PREFIX = 'mdl_';
 113
 114     /**
 115      * Constructs the store instance.
 116      *
 117      * Noting that this function is not an initialisation. It is used to prepare the store for use.
 118      * The store will be initialised when required and will be provided with a cache_definition at that time.
 119      *
 120      * @param string $name
 121      * @param array $configuration
 122      */
 123     public function __construct($name, array $configuration = array()) {
 124         $this->name = $name;
 125         if (!array_key_exists('servers', $configuration) || empty($configuration['servers'])) {
 126             // Nothing configured.
 127             return;
 128         }
 129         if (!is_array($configuration['servers'])) {
 130             $configuration['servers'] = array($configuration['servers']);
 131         }
 132         foreach ($configuration['servers'] as $server) {
 133             if (!is_array($server)) {
 134                 $server = explode(':', $server, 3);
 135             }
 136             if (!array_key_exists(1, $server)) {
 137                 $server[1] = 11211;
 138                 $server[2] = 100;
 139             } else if (!array_key_exists(2, $server)) {
 140                 $server[2] = 100;
 141             }
 142             $this->servers[] = $server;
 143         }
 144
 145         $this->clustered = array_key_exists('clustered', $configuration) ? (bool)$configuration['clustered'] : false;
 146
 147         if ($this->clustered) {
 148             if (!array_key_exists('setservers', $configuration) || (count($configuration['setservers']) < 1)) {
 149                 // Can't setup clustering without set servers.
 150                 return;
 151             }
 152             if (count($this->servers) !== 1) {
 153                 // Can only setup cluster with exactly 1 get server.
 154                 return;
 155             }
 156             foreach ($configuration['setservers'] as $server) {
 157                 // We do not use weights (3rd part) on these servers.
 158                 if (!is_array($server)) {
 159                     $server = explode(':', $server, 3);
 160                 }
 161                 if (!array_key_exists(1, $server)) {
 162                     $server[1] = 11211;
 163                 }
 164                 $this->setservers[] = $server;
 165             }
 166         }
 167
 168         if (empty($configuration['prefix'])) {
 169             $this->prefix = self::DEFAULT_PREFIX;
 170         } else {
 171             $this->prefix = $configuration['prefix'];
 172         }
 173
 174         $this->connection = new Memcache;
 175         foreach ($this->servers as $server) {
 176             $this->connection->addServer($server[0], (int) $server[1], true, (int) $server[2]);
 177         }
 178
 179         if ($this->clustered) {
 180             foreach ($this->setservers as $setserver) {
 181                 // Since we will have a number of them with the same name, append server and port.
 182                 $connection = new Memcache;
 183                 $connection->addServer($setserver[0], $setserver[1]);
 184                 $this->setconnections[] = $connection;
 185             }
 186         }
 187
 188         // Test the connection to the pool of servers.
 189         $this->isready = @$this->connection->set($this->parse_key('ping'), 'ping', MEMCACHE_COMPRESSED, 1);
 190     }
 191
 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         if ($this->is_initialised()) {
 201             throw new coding_exception('This memcache instance has already been initialised.');
 202         }
 203         $this->definition = $definition;
 204         $this->isinitialised = true;
 205     }
 206
 207     /**
 208      * Returns true once this instance has been initialised.
 209      *
 210      * @return bool
 211      */
 212     public function is_initialised() {
 213         return ($this->isinitialised);
 214     }
 215
 216     /**
 217      * Returns true if this store instance is ready to be used.
 218      * @return bool
 219      */
 220     public function is_ready() {
 221         return $this->isready;
 222     }
 223
 224     /**
 225      * Returns true if the store requirements are met.
 226      *
 227      * @return bool
 228      */
 229     public static function are_requirements_met() {
 230         return class_exists('Memcache');
 231     }
 232
 233     /**
 234      * Returns true if the given mode is supported by this store.
 235      *
 236      * @param int $mode One of cache_store::MODE_*
 237      * @return bool
 238      */
 239     public static function is_supported_mode($mode) {
 240         return ($mode === self::MODE_APPLICATION || $mode === self::MODE_SESSION);
 241     }
 242
 243     /**
 244      * Returns the supported features as a combined int.
 245      *
 246      * @param array $configuration
 247      * @return int
 248      */
 249     public static function get_supported_features(array $configuration = array()) {
 250         return self::SUPPORTS_NATIVE_TTL;
 251     }
 252
 253     /**
 254      * Returns false as this store does not support multiple identifiers.
 255      * (This optional function is a performance optimisation; it must be
 256      * consistent with the value from get_supported_features.)
 257      *
 258      * @return bool False
 259      */
 260     public function supports_multiple_identifiers() {
 261         return false;
 262     }
 263
 264     /**
 265      * Returns the supported modes as a combined int.
 266      *
 267      * @param array $configuration
 268      * @return int
 269      */
 270     public static function get_supported_modes(array $configuration = array()) {
 271         return self::MODE_APPLICATION;
 272     }
 273
 274     /**
 275      * Parses the given key to make it work for this memcache backend.
 276      *
 277      * @param string $key The raw key.
 278      * @return string The resulting key.
 279      */
 280     protected function parse_key($key) {
 281         if (strlen($key) > 245) {
 282             $key = '_sha1_'.sha1($key);
 283         }
 284         $key = $this->prefix . $key;
 285         return $key;
 286     }
 287
 288     /**
 289      * Retrieves an item from the cache store given its key.
 290      *
 291      * @param string $key The key to retrieve
 292      * @return mixed The data that was associated with the key, or false if the key did not exist.
 293      */
 294     public function get($key) {
 295         return $this->connection->get($this->parse_key($key));
 296     }
 297
 298     /**
 299      * Retrieves several items from the cache store in a single transaction.
 300      *
 301      * 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.
 302      *
 303      * @param array $keys The array of keys to retrieve
 304      * @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
 305      *      be set to false.
 306      */
 307     public function get_many($keys) {
 308         $mkeys = array();
 309         foreach ($keys as $key) {
 310             $mkeys[$key] = $this->parse_key($key);
 311         }
 312         $result = $this->connection->get($mkeys);
 313         if (!is_array($result)) {
 314             $result = array();
 315         }
 316         $return = array();
 317         foreach ($mkeys as $key => $mkey) {
 318             if (!array_key_exists($mkey, $result)) {
 319                 $return[$key] = false;
 320             } else {
 321                 $return[$key] = $result[$mkey];
 322             }
 323         }
 324         return $return;
 325     }
 326
 327     /**
 328      * Sets an item in the cache given its key and data value.
 329      *
 330      * @param string $key The key to use.
 331      * @param mixed $data The data to set.
 332      * @return bool True if the operation was a success false otherwise.
 333      */
 334     public function set($key, $data) {
 335         if ($this->clustered) {
 336             $status = true;
 337             foreach ($this->setconnections as $connection) {
 338                 $status = $connection->set($this->parse_key($key), $data, MEMCACHE_COMPRESSED, $this->definition->get_ttl())
 339                         && $status;
 340             }
 341             return $status;
 342         }
 343
 344         return $this->connection->set($this->parse_key($key), $data, MEMCACHE_COMPRESSED, $this->definition->get_ttl());
 345     }
 346
 347     /**
 348      * Sets many items in the cache in a single transaction.
 349      *
 350      * @param array $keyvaluearray An array of key value pairs. Each item in the array will be an associative array with two
 351      *      keys, 'key' and 'value'.
 352      * @return int The number of items successfully set. It is up to the developer to check this matches the number of items
 353      *      sent ... if they care that is.
 354      */
 355     public function set_many(array $keyvaluearray) {
 356         $count = 0;
 357         foreach ($keyvaluearray as $pair) {
 358             if ($this->set($pair['key'], $pair['value'])) {
 359                 $count++;
 360             }
 361         }
 362         return $count;
 363     }
 364
 365     /**
 366      * Deletes an item from the cache store.
 367      *
 368      * @param string $key The key to delete.
 369      * @return bool Returns true if the operation was a success, false otherwise.
 370      */
 371     public function delete($key) {
 372         if ($this->clustered) {
 373             $status = true;
 374             foreach ($this->setconnections as $connection) {
 375                 $status = $connection->delete($this->parse_key($key)) && $status;
 376             }
 377             return $status;
 378         }
 379
 380         return $this->connection->delete($this->parse_key($key));
 381     }
 382
 383     /**
 384      * Deletes several keys from the cache in a single action.
 385      *
 386      * @param array $keys The keys to delete
 387      * @return int The number of items successfully deleted.
 388      */
 389     public function delete_many(array $keys) {
 390         $count = 0;
 391         foreach ($keys as $key) {
 392             if ($this->delete($key)) {
 393                 $count++;
 394             }
 395         }
 396         return $count;
 397     }
 398
 399     /**
 400      * Purges the cache deleting all items within it.
 401      *
 402      * @return boolean True on success. False otherwise.
 403      */
 404     public function purge() {
 405         if ($this->isready) {
 406             if ($this->clustered) {
 407                 foreach ($this->setconnections as $connection) {
 408                     $connection->flush();
 409                 }
 410             } else {
 411                 $this->connection->flush();
 412             }
 413         }
 414
 415         return true;
 416     }
 417
 418     /**
 419      * Given the data from the add instance form this function creates a configuration array.
 420      *
 421      * @param stdClass $data
 422      * @return array
 423      */
 424     public static function config_get_configuration_array($data) {
 425         $lines = explode("\n", $data->servers);
 426         $servers = array();
 427         foreach ($lines as $line) {
 428             // Trim surrounding colons and default whitespace.
 429             $line = trim(trim($line), ":");
 430             // Skip blank lines.
 431             if ($line === '') {
 432                 continue;
 433             }
 434             $servers[] = explode(':', $line, 3);
 435         }
 436
 437         $clustered = false;
 438         if (isset($data->clustered)) {
 439             $clustered = true;
 440         }
 441
 442         $lines = explode("\n", $data->setservers);
 443         $setservers = array();
 444         foreach ($lines as $line) {
 445             // Trim surrounding colons and default whitespace.
 446             $line = trim(trim($line), ":");
 447             if ($line === '') {
 448                 continue;
 449             }
 450             $setserver = explode(':', $line, 3);
 451             // We don't use weights, so display a debug message.
 452             if (count($setserver) > 2) {
 453                 debugging('Memcache Set Server '.$setserver[0].' has too many parameters.');
 454             }
 455             $setservers[] = $setserver;
 456         }
 457
 458         return array(
 459             'servers' => $servers,
 460             'prefix' => $data->prefix,
 461             'clustered' => $clustered,
 462             'setservers' => $setservers
 463         );
 464     }
 465
 466     /**
 467      * Allows the cache store to set its data against the edit form before it is shown to the user.
 468      *
 469      * @param moodleform $editform
 470      * @param array $config
 471      */
 472     public static function config_set_edit_form_data(moodleform $editform, array $config) {
 473         $data = array();
 474         if (!empty($config['servers'])) {
 475             $servers = array();
 476             foreach ($config['servers'] as $server) {
 477                 $servers[] = join(":", $server);
 478             }
 479             $data['servers'] = join("\n", $servers);
 480         }
 481         if (!empty($config['prefix'])) {
 482             $data['prefix'] = $config['prefix'];
 483         } else {
 484             $data['prefix'] = self::DEFAULT_PREFIX;
 485         }
 486         if (isset($config['clustered'])) {
 487             $data['clustered'] = (bool)$config['clustered'];
 488         }
 489         if (!empty($config['setservers'])) {
 490             $servers = array();
 491             foreach ($config['setservers'] as $server) {
 492                 $servers[] = join(":", $server);
 493             }
 494             $data['setservers'] = join("\n", $servers);
 495         }
 496
 497         $editform->set_data($data);
 498     }
 499
 500     /**
 501      * Performs any necessary clean up when the store instance is being deleted.
 502      */
 503     public function instance_deleted() {
 504         if ($this->connection) {
 505             $connection = $this->connection;
 506         } else {
 507             $connection = new Memcache;
 508             foreach ($this->servers as $server) {
 509                 $connection->addServer($server[0], $server[1], true, $server[2]);
 510             }
 511         }
 512         @$connection->flush();
 513         unset($connection);
 514         unset($this->connection);
 515     }
 516
 517     /**
 518      * Generates an instance of the cache store that can be used for testing.
 519      *
 520      * @param cache_definition $definition
 521      * @return cachestore_memcache|false
 522      */
 523     public static function initialise_test_instance(cache_definition $definition) {
 524         if (!self::are_requirements_met()) {
 525             return false;
 526         }
 527
 528         $config = get_config('cachestore_memcache');
 529         if (empty($config->testservers)) {
 530             return false;
 531         }
 532
 533         $configuration = array();
 534         $configuration['servers'] = explode("\n", $config->testservers);
 535         if (!empty($config->testclustered)) {
 536             $configuration['clustered'] = $config->testclustered;
 537         }
 538         if (!empty($config->testsetservers)) {
 539             $configuration['setservers'] = explode("\n", $config->testsetservers);
 540         }
 541
 542         $store = new cachestore_memcache('Test memcache', $configuration);
 543         $store->initialise($definition);
 544
 545         return $store;
 546     }
 547
 548     /**
 549      * Creates a test instance for unit tests if possible.
 550      * @param cache_definition $definition
 551      * @return bool|cachestore_memcache
 552      */
 553     public static function initialise_unit_test_instance(cache_definition $definition) {
 554         if (!self::are_requirements_met()) {
 555             return false;
 556         }
 557         if (!defined('TEST_CACHESTORE_MEMCACHE_TESTSERVERS')) {
 558             return false;
 559         }
 560         $configuration = array();
 561         $configuration['servers'] = explode("\n", TEST_CACHESTORE_MEMCACHE_TESTSERVERS);
 562
 563         $store = new cachestore_memcache('Test memcache', $configuration);
 564         $store->initialise($definition);
 565
 566         return $store;
 567     }
 568
 569     /**
 570      * Returns the name of this instance.
 571      * @return string
 572      */
 573     public function my_name() {
 574         return $this->name;
 575     }
 576
 577     /**
 578      * Used to notify of configuration conflicts.
 579      *
 580      * The warnings returned here will be displayed on the cache configuration screen.
 581      *
 582      * @return string[] Returns an array of warnings (strings)
 583      */
 584     public function get_warnings() {
 585         global $CFG;
 586         $warnings = array();
 587         if (isset($CFG->session_memcached_save_path) && count($this->servers)) {
 588             $bits = explode(':', $CFG->session_memcached_save_path, 3);
 589             $host = array_shift($bits);
 590             $port = (count($bits)) ? array_shift($bits) : '11211';
 591             foreach ($this->servers as $server) {
 592                 if ($server[0] === $host && $server[1] === $port) {
 593                     $warnings[] = get_string('sessionhandlerconflict', 'cachestore_memcache', $this->my_name());
 594                     break;
 595                 }
 596             }
 597         }
 598         return $warnings;
 599     }
 600 }