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_base {
  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      * An array of servers to use in the connection args.
  56      * @var array
  57      */
  58     protected $servers = array();
  59
  60     /**
  61      * An array of options used when establishing the connection.
  62      * @var array
  63      */
  64     protected $options = array();
  65
  66     /**
  67      * Set to true when things are ready to be initialised.
  68      * @var bool
  69      */
  70     protected $isready = false;
  71
  72     /**
  73      * The cache definition this store was initialised for.
  74      * @var cache_definition
  75      */
  76     protected $definition;
  77
  78     /**
  79      * Constructs the store instance.
  80      *
  81      * Noting that this function is not an initialisation. It is used to prepare the store for use.
  82      * The store will be initialised when required and will be provided with a cache_definition at that time.
  83      *
  84      * @param string $name
  85      * @param array $configuration
  86      */
  87     public function __construct($name, array $configuration = array()) {
  88         $this->name = $name;
  89         if (!array_key_exists('servers', $configuration) || empty($configuration['servers'])) {
  90             // Nothing configured.
  91             return;
  92         }
  93         if (!is_array($configuration['servers'])) {
  94             $configuration['servers'] = array($configuration['servers']);
  95         }
  96         foreach ($configuration['servers'] as $server) {
  97             if (!is_array($server)) {
  98                 $server = explode(':', $server, 3);
  99             }
 100             if (!array_key_exists(1, $server)) {
 101                 $server[1] = 11211;
 102                 $server[2] = 100;
 103             } else if (!array_key_exists(2, $server)) {
 104                 $server[2] = 100;
 105             }
 106             $this->servers[] = $server;
 107         }
 108
 109         $this->isready = true;
 110     }
 111
 112     /**
 113      * Initialises the cache.
 114      *
 115      * Once this has been done the cache is all set to be used.
 116      *
 117      * @param cache_definition $definition
 118      */
 119     public function initialise(cache_definition $definition) {
 120         if ($this->is_initialised()) {
 121             throw new coding_exception('This memcache instance has already been initialised.');
 122         }
 123         $this->definition = $definition;
 124         $this->connection = new Memcache;
 125         foreach ($this->servers as $server) {
 126             $this->connection->addServer($server[0], $server[1], true, $server[2]);
 127         }
 128     }
 129
 130     /**
 131      * Returns true once this instance has been initialised.
 132      *
 133      * @return bool
 134      */
 135     public function is_initialised() {
 136         return ($this->connection !== null);
 137     }
 138
 139     /**
 140      * Returns true if this store instance is ready to be used.
 141      * @return bool
 142      */
 143     public function is_ready() {
 144         return $this->isready;
 145     }
 146
 147     /**
 148      * Returns true if the store requirements are met.
 149      *
 150      * @return bool
 151      */
 152     public static function are_requirements_met() {
 153         return class_exists('Memcache');
 154     }
 155
 156     /**
 157      * Returns true if the given mode is supported by this store.
 158      *
 159      * @param int $mode One of cache_store::MODE_*
 160      * @return bool
 161      */
 162     public static function is_supported_mode($mode) {
 163         return ($mode === self::MODE_APPLICATION || $mode === self::MODE_SESSION);
 164     }
 165
 166     /**
 167      * Returns the supported features as a combined int.
 168      *
 169      * @param array $configuration
 170      * @return int
 171      */
 172     public static function get_supported_features(array $configuration = array()) {
 173         return self::SUPPORTS_NATIVE_TTL;
 174     }
 175
 176     /**
 177      * Returns the supported modes as a combined int.
 178      *
 179      * @param array $configuration
 180      * @return int
 181      */
 182     public static function get_supported_modes(array $configuration = array()) {
 183         return self::MODE_APPLICATION + self::MODE_SESSION;
 184     }
 185
 186     /**
 187      * Retrieves an item from the cache store given its key.
 188      *
 189      * @param string $key The key to retrieve
 190      * @return mixed The data that was associated with the key, or false if the key did not exist.
 191      */
 192     public function get($key) {
 193         return $this->connection->get($key);
 194     }
 195
 196     /**
 197      * Retrieves several items from the cache store in a single transaction.
 198      *
 199      * 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.
 200      *
 201      * @param array $keys The array of keys to retrieve
 202      * @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
 203      *      be set to false.
 204      */
 205     public function get_many($keys) {
 206         $result = $this->connection->get($keys);
 207         if (!is_array($result)) {
 208             $result = array();
 209         }
 210         foreach ($keys as $key) {
 211             if (!array_key_exists($key, $result)) {
 212                 $result[$key] = false;
 213             }
 214         }
 215         return $result;
 216     }
 217
 218     /**
 219      * Sets an item in the cache given its key and data value.
 220      *
 221      * @param string $key The key to use.
 222      * @param mixed $data The data to set.
 223      * @return bool True if the operation was a success false otherwise.
 224      */
 225     public function set($key, $data) {
 226         return $this->connection->set($key, $data, MEMCACHE_COMPRESSED, $this->definition->get_ttl());
 227     }
 228
 229     /**
 230      * Sets many items in the cache in a single transaction.
 231      *
 232      * @param array $keyvaluearray An array of key value pairs. Each item in the array will be an associative array with two
 233      *      keys, 'key' and 'value'.
 234      * @return int The number of items successfully set. It is up to the developer to check this matches the number of items
 235      *      sent ... if they care that is.
 236      */
 237     public function set_many(array $keyvaluearray) {
 238         $count = 0;
 239         foreach ($keyvaluearray as $pair) {
 240             if ($this->connection->set($pair['key'], $pair['value'], MEMCACHE_COMPRESSED, $this->definition->get_ttl())) {
 241                 $count++;
 242             }
 243         }
 244         return $count;
 245     }
 246
 247     /**
 248      * Deletes an item from the cache store.
 249      *
 250      * @param string $key The key to delete.
 251      * @return bool Returns true if the operation was a success, false otherwise.
 252      */
 253     public function delete($key) {
 254         return $this->connection->delete($key);
 255     }
 256
 257     /**
 258      * Deletes several keys from the cache in a single action.
 259      *
 260      * @param array $keys The keys to delete
 261      * @return int The number of items successfully deleted.
 262      */
 263     public function delete_many(array $keys) {
 264         $count = 0;
 265         foreach ($keys as $key) {
 266             if ($this->delete($key)) {
 267                 $count++;
 268             }
 269         }
 270         return $count;
 271     }
 272
 273     /**
 274      * Purges the cache deleting all items within it.
 275      *
 276      * @return boolean True on success. False otherwise.
 277      */
 278     public function purge() {
 279         $this->connection->flush();
 280         return true;
 281     }
 282
 283     /**
 284      * Given the data from the add instance form this function creates a configuration array.
 285      *
 286      * @param stdClass $data
 287      * @return array
 288      */
 289     public static function config_get_configuration_array($data) {
 290         $lines = explode("\n", $data->servers);
 291         $servers = array();
 292         foreach ($lines as $line) {
 293             $line = trim($line, ':');
 294             $servers[] = explode(':', $line, 3);
 295         }
 296         return array(
 297             'servers' => $servers,
 298         );
 299     }
 300
 301     /**
 302      * Allows the cache store to set its data against the edit form before it is shown to the user.
 303      *
 304      * @param moodleform $editform
 305      * @param array $config
 306      */
 307     public static function config_set_edit_form_data(moodleform $editform, array $config) {
 308         $data = array();
 309         if (!empty($config['servers'])) {
 310             $servers = array();
 311             foreach ($config['servers'] as $server) {
 312                 $servers[] = join(":", $server);
 313             }
 314             $data['servers'] = join("\n", $servers);
 315         }
 316         $editform->set_data($data);
 317     }
 318
 319     /**
 320      * Performs any necessary clean up when the store instance is being deleted.
 321      */
 322     public function cleanup() {
 323         $this->purge();
 324     }
 325
 326     /**
 327      * Generates an instance of the cache store that can be used for testing.
 328      *
 329      * @param cache_definition $definition
 330      * @return false
 331      */
 332     public static function initialise_test_instance(cache_definition $definition) {
 333         if (!self::are_requirements_met()) {
 334             return false;
 335         }
 336
 337         $config = get_config('cachestore_memcache');
 338         if (empty($config->testservers)) {
 339             return false;
 340         }
 341
 342         $configuration = array();
 343         $configuration['servers'] = explode("\n", $config->testservers);
 344
 345         $store = new cachestore_memcache('Test memcache', $configuration);
 346         $store->initialise($definition);
 347
 348         return $store;
 349     }
 350
 351     /**
 352      * Returns the name of this instance.
 353      * @return string
 354      */
 355     public function my_name() {
 356         return $this->name;
 357     }
 358 }