Search moodle.org's
Developer Documentation
Developer Documentation
- Bug fixes for general core bugs in 4.0.x will end 8 May 2023 (12 months).
- Bug fixes for security issues in 4.0.x will end 13 November 2023 (18 months).
- PHP version: minimum PHP 7.3.0 Note: the minimum PHP version has increased since Moodle 3.10. PHP 7.4.x is also supported.
/cache/classes/ -> loaders.php (source)
Differences Between: [Versions 310 and 400] [Versions 311 and 400] [Versions 39 and 400] [Versions 400 and 401] [Versions 400 and 402] [Versions 400 and 403]
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 * Cache loaders 19 * 20 * This file is part of Moodle's cache API, affectionately called MUC. 21 * It contains the components that are required in order to use caching. 22 * 23 * @package core 24 * @category cache 25 * @copyright 2012 Sam Hemelryk 26 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later 27 */ 28 29 defined('MOODLE_INTERNAL') || die(); 30 31 /** 32 * The main cache class. 33 * 34 * This class if the first class that any end developer will interact with. 35 * In order to create an instance of a cache that they can work with they must call one of the static make methods belonging 36 * to this class. 37 * 38 * @package core 39 * @category cache 40 * @copyright 2012 Sam Hemelryk 41 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later 42 */ 43 class cache implements cache_loader { 44 45 /** 46 * @var int Constant for cache entries that do not have a version number 47 */ 48 const VERSION_NONE = -1; 49 50 /** 51 * We need a timestamp to use within the cache API. 52 * This stamp needs to be used for all ttl and time based operations to ensure that we don't end up with 53 * timing issues. 54 * @var int 55 */ 56 protected static $now; 57 58 /** 59 * A purge token used to distinguish between multiple cache purges in the same second. 60 * This is in the format <microtime>-<random string>. 61 * 62 * @var string 63 */ 64 protected static $purgetoken; 65 66 /** 67 * The definition used when loading this cache if there was one. 68 * @var cache_definition 69 */ 70 private $definition = false; 71 72 /** 73 * The cache store that this loader will make use of. 74 * @var cache_store 75 */ 76 private $store; 77 78 /** 79 * The next cache loader in the chain if there is one. 80 * If a cache request misses for the store belonging to this loader then the loader 81 * stored here will be checked next. 82 * If there is a loader here then $datasource must be false. 83 * @var cache_loader|false 84 */ 85 private $loader = false; 86 87 /** 88 * The data source to use if we need to load data (because if doesn't exist in the cache store). 89 * If there is a data source here then $loader above must be false. 90 * @var cache_data_source|false 91 */ 92 private $datasource = false; 93 94 /** 95 * Used to quickly check if the store supports key awareness. 96 * This is set when the cache is initialised and is used to speed up processing. 97 * @var bool 98 */ 99 private $supportskeyawareness = null; 100 101 /** 102 * Used to quickly check if the store supports ttl natively. 103 * This is set when the cache is initialised and is used to speed up processing. 104 * @var bool 105 */ 106 private $supportsnativettl = null; 107 108 /** 109 * Gets set to true if the cache is going to be using a static array for acceleration. 110 * The array statically caches items used during the lifetime of the request. This greatly speeds up interaction 111 * with the cache in areas where it will be repetitively hit for the same information such as with strings. 112 * There are several other variables to control how this static acceleration array works. 113 * @var bool 114 */ 115 private $staticacceleration = false; 116 117 /** 118 * The static acceleration array. 119 * Items will be stored in this cache as they were provided. This ensure there is no unnecessary processing taking place. 120 * @var array 121 */ 122 private $staticaccelerationarray = array(); 123 124 /** 125 * The number of items in the static acceleration array. Avoids count calls like you wouldn't believe. 126 * @var int 127 */ 128 private $staticaccelerationcount = 0; 129 130 /** 131 * An array containing just the keys being used in the static acceleration array. 132 * This seems redundant perhaps but is used when managing the size of the static acceleration array. 133 * Items are added to the end of the array and the when we need to reduce the size of the cache we use the 134 * key that is first on this array. 135 * @var array 136 */ 137 private $staticaccelerationkeys = array(); 138 139 /** 140 * The maximum size of the static acceleration array. 141 * 142 * If set to false there is no max size. 143 * Caches that make use of static acceleration should seriously consider setting this to something reasonably small, but 144 * still large enough to offset repetitive calls. 145 * 146 * @var int|false 147 */ 148 private $staticaccelerationsize = false; 149 150 /** 151 * Gets set to true during initialisation if the definition is making use of a ttl. 152 * Used to speed up processing. 153 * @var bool 154 */ 155 private $hasattl = false; 156 157 /** 158 * Gets set to the class name of the store during initialisation. This is used several times in the cache class internally 159 * and having it here helps speed up processing. 160 * @var strubg 161 */ 162 protected $storetype = 'unknown'; 163 164 /** 165 * Gets set to true if we want to collect performance information about the cache API. 166 * @var bool 167 */ 168 protected $perfdebug = false; 169 170 /** 171 * Determines if this loader is a sub loader, not the top of the chain. 172 * @var bool 173 */ 174 protected $subloader = false; 175 176 /** 177 * Creates a new cache instance for a pre-defined definition. 178 * 179 * @param string $component The component for the definition 180 * @param string $area The area for the definition 181 * @param array $identifiers Any additional identifiers that should be provided to the definition. 182 * @param string $unused Used to be datasourceaggregate but that was removed and this is now unused. 183 * @return cache_application|cache_session|cache_store 184 */ 185 public static function make($component, $area, array $identifiers = array(), $unused = null) { 186 $factory = cache_factory::instance(); 187 return $factory->create_cache_from_definition($component, $area, $identifiers); 188 } 189 190 /** 191 * Creates a new cache instance based upon the given params. 192 * 193 * @param int $mode One of cache_store::MODE_* 194 * @param string $component The component this cache relates to. 195 * @param string $area The area this cache relates to. 196 * @param array $identifiers Any additional identifiers that should be provided to the definition. 197 * @param array $options An array of options, available options are: 198 * - simplekeys : Set to true if the keys you will use are a-zA-Z0-9_ 199 * - simpledata : Set to true if the type of the data you are going to store is scalar, or an array of scalar vars 200 * - staticacceleration : If set to true the cache will hold onto data passing through it. 201 * - staticaccelerationsize : The max size for the static acceleration array. 202 * @return cache_application|cache_session|cache_store 203 */ 204 public static function make_from_params($mode, $component, $area, array $identifiers = array(), array $options = array()) { 205 $factory = cache_factory::instance(); 206 return $factory->create_cache_from_params($mode, $component, $area, $identifiers, $options); 207 } 208 209 /** 210 * Constructs a new cache instance. 211 * 212 * You should not call this method from your code, instead you should use the cache::make methods. 213 * 214 * This method is public so that the cache_factory is able to instantiate cache instances. 215 * Ideally we would make this method protected and expose its construction to the factory method internally somehow. 216 * The factory class is responsible for this in order to centralise the storage of instances once created. This way if needed 217 * we can force a reset of the cache API (used during unit testing). 218 * 219 * @param cache_definition $definition The definition for the cache instance. 220 * @param cache_store $store The store that cache should use. 221 * @param cache_loader|cache_data_source $loader The next loader in the chain or the data source if there is one and there 222 * are no other cache_loaders in the chain. 223 */ 224 public function __construct(cache_definition $definition, cache_store $store, $loader = null) { 225 global $CFG; 226 $this->definition = $definition; 227 $this->store = $store; 228 $this->storetype = get_class($store); 229 $this->perfdebug = (!empty($CFG->perfdebug) and $CFG->perfdebug > 7); 230 if ($loader instanceof cache_loader) { 231 $this->set_loader($loader); 232 } else if ($loader instanceof cache_data_source) { 233 $this->set_data_source($loader); 234 } 235 $this->definition->generate_definition_hash(); 236 $this->staticacceleration = $this->definition->use_static_acceleration(); 237 if ($this->staticacceleration) { 238 $this->staticaccelerationsize = $this->definition->get_static_acceleration_size(); 239 } 240 $this->hasattl = ($this->definition->get_ttl() > 0); 241 } 242 243 /** 244 * Set the loader for this cache. 245 * 246 * @param cache_loader $loader 247 */ 248 protected function set_loader(cache_loader $loader): void { 249 $this->loader = $loader; 250 251 // Mark the loader as a sub (chained) loader. 252 $this->loader->set_is_sub_loader(true); 253 } 254 255 /** 256 * Set the data source for this cache. 257 * 258 * @param cache_data_source $datasource 259 */ 260 protected function set_data_source(cache_data_source $datasource): void { 261 $this->datasource = $datasource; 262 } 263 264 /** 265 * Used to inform the loader of its state as a sub loader, or as the top of the chain. 266 * 267 * This is important as it ensures that we do not have more than one loader keeping static acceleration data. 268 * Subloaders need to be "pure" loaders in the sense that they are used to store and retrieve information from stores or the 269 * next loader/data source in the chain. 270 * Nothing fancy, nothing flash. 271 * 272 * @param bool $setting 273 */ 274 protected function set_is_sub_loader($setting = true) { 275 if ($setting) { 276 $this->subloader = true; 277 // Subloaders should not keep static acceleration data. 278 $this->staticacceleration = false; 279 $this->staticaccelerationsize = false; 280 } else { 281 $this->subloader = true; 282 $this->staticacceleration = $this->definition->use_static_acceleration(); 283 if ($this->staticacceleration) { 284 $this->staticaccelerationsize = $this->definition->get_static_acceleration_size(); 285 } 286 } 287 } 288 289 /** 290 * Alters the identifiers that have been provided to the definition. 291 * 292 * This is an advanced method and should not be used unless really needed. 293 * It allows the developer to slightly alter the definition without having to re-establish the cache. 294 * It will cause more processing as the definition will need to clear and reprepare some of its properties. 295 * 296 * @param array $identifiers 297 */ 298 public function set_identifiers(array $identifiers) { 299 if ($this->definition->set_identifiers($identifiers)) { 300 // As static acceleration uses input keys and not parsed keys 301 // it much be cleared when the identifier set is changed. 302 $this->staticaccelerationarray = array(); 303 if ($this->staticaccelerationsize !== false) { 304 $this->staticaccelerationkeys = array(); 305 $this->staticaccelerationcount = 0; 306 } 307 } 308 } 309 310 /** 311 * Process any outstanding invalidation events for the cache we are registering, 312 * 313 * Identifiers and event invalidation are not compatible with each other at this time. 314 * As a result the cache does not need to consider identifiers when working out what to invalidate. 315 */ 316 protected function handle_invalidation_events() { 317 if (!$this->definition->has_invalidation_events()) { 318 return; 319 } 320 321 // Each cache stores the current 'lastinvalidation' value within the cache itself. 322 $lastinvalidation = $this->get('lastinvalidation'); 323 if ($lastinvalidation === false) { 324 // There is currently no value for the lastinvalidation token, therefore the token is not set, and there 325 // can be nothing to invalidate. 326 // Set the lastinvalidation value to the current purge token and return early. 327 $this->set('lastinvalidation', self::get_purge_token()); 328 return; 329 } else if ($lastinvalidation == self::get_purge_token()) { 330 // The current purge request has already been fully handled by this cache. 331 return; 332 } 333 334 /* 335 * Now that the whole cache check is complete, we check the meaning of any specific cache invalidation events. 336 * These are stored in the core/eventinvalidation cache as an multi-dimensinoal array in the form: 337 * [ 338 * eventname => [ 339 * keyname => purgetoken, 340 * ] 341 * ] 342 * 343 * The 'keyname' value is used to delete a specific key in the cache. 344 * If the keyname is set to the special value 'purged', then the whole cache is purged instead. 345 * 346 * The 'purgetoken' is the token that this key was last purged. 347 * a) If the purgetoken matches the last invalidation, then the key/cache is not purged. 348 * b) If the purgetoken is newer than the last invalidation, then the key/cache is not purged. 349 * c) If the purge token is older than the last invalidation, or it has a different token component, then the 350 * cache is purged. 351 * 352 * Option b should not happen under normal operation, but may happen in race condition whereby a long-running 353 * request's cache is cleared in another process during that request, and prior to that long-running request 354 * creating the cache. In such a condition, it would be incorrect to clear that cache. 355 */ 356 $cache = self::make('core', 'eventinvalidation'); 357 $events = $cache->get_many($this->definition->get_invalidation_events()); 358 $todelete = array(); 359 $purgeall = false; 360 361 // Iterate the returned data for the events. 362 foreach ($events as $event => $keys) { 363 if ($keys === false) { 364 // No data to be invalidated yet. 365 continue; 366 } 367 368 // Look at each key and check the timestamp. 369 foreach ($keys as $key => $purgetoken) { 370 // If the timestamp of the event is more than or equal to the last invalidation (happened between the last 371 // invalidation and now), then we need to invaliate the key. 372 if (self::compare_purge_tokens($purgetoken, $lastinvalidation) > 0) { 373 if ($key === 'purged') { 374 $purgeall = true; 375 break; 376 } else { 377 $todelete[] = $key; 378 } 379 } 380 } 381 } 382 if ($purgeall) { 383 $this->purge(); 384 } else if (!empty($todelete)) { 385 $todelete = array_unique($todelete); 386 $this->delete_many($todelete); 387 } 388 // Set the time of the last invalidation. 389 if ($purgeall || !empty($todelete)) { 390 $this->set('lastinvalidation', self::get_purge_token(true)); 391 } 392 } 393 394 /** 395 * Retrieves the value for the given key from the cache. 396 * 397 * @param string|int $key The key for the data being requested. 398 * It can be any structure although using a scalar string or int is recommended in the interests of performance. 399 * In advanced cases an array may be useful such as in situations requiring the multi-key functionality. 400 * @param int $strictness One of IGNORE_MISSING | MUST_EXIST 401 * @return mixed|false The data from the cache or false if the key did not exist within the cache. 402 * @throws coding_exception 403 */ 404 public function get($key, $strictness = IGNORE_MISSING) { 405 return $this->get_implementation($key, self::VERSION_NONE, $strictness); 406 } 407 408 /** 409 * Retrieves the value and actual version for the given key, with at least the required version. 410 * 411 * If there is no value for the key, or there is a value but it doesn't have the required 412 * version, then this function will return null (or throw an exception if you set strictness 413 * to MUST_EXIST). 414 * 415 * This function can be used to make it easier to support localisable caches (where the cache 416 * could be stored on a local server as well as a shared cache). Specifying the version means 417 * that it will automatically retrieve the correct version if available, either from the local 418 * server or [if that has an older version] from the shared server. 419 * 420 * If the cached version is newer than specified version, it will be returned regardless. For 421 * example, if you request version 4, but the locally cached version is 5, it will be returned. 422 * If you request version 6, and the locally cached version is 5, then the system will look in 423 * higher-level caches (if any); if there still isn't a version 6 or greater, it will return 424 * null. 425 * 426 * You must use this function if you use set_versioned. 427 * 428 * @param string|int $key The key for the data being requested. 429 * @param int $requiredversion Minimum required version of the data 430 * @param int $strictness One of IGNORE_MISSING or MUST_EXIST. 431 * @param mixed $actualversion If specified, will be set to the actual version number retrieved 432 * @return mixed Data from the cache, or false if the key did not exist or was too old 433 * @throws \coding_exception If you call get_versioned on a non-versioned cache key 434 */ 435 public function get_versioned($key, int $requiredversion, int $strictness = IGNORE_MISSING, &$actualversion = null) { 436 return $this->get_implementation($key, $requiredversion, $strictness, $actualversion); 437 } 438 439 /** 440 * Checks returned data to see if it matches the specified version number. 441 * 442 * For versioned data, this returns the version_wrapper object (or false). For other 443 * data, it returns the actual data (or false). 444 * 445 * @param mixed $result Result data 446 * @param int $requiredversion Required version number or VERSION_NONE if there must be no version 447 * @return bool True if version is current, false if not (or if result is false) 448 * @throws \coding_exception If unexpected type of data (versioned vs non-versioned) is found 449 */ 450 protected static function check_version($result, int $requiredversion): bool { 451 if ($requiredversion === self::VERSION_NONE) { 452 if ($result instanceof \core_cache\version_wrapper) { 453 throw new \coding_exception('Unexpectedly found versioned cache entry'); 454 } else { 455 // No version checks, so version is always correct. 456 return true; 457 } 458 } else { 459 // If there's no result, obviously it doesn't meet the required version. 460 if (!cache_helper::result_found($result)) { 461 return false; 462 } 463 if (!($result instanceof \core_cache\version_wrapper)) { 464 throw new \coding_exception('Unexpectedly found non-versioned cache entry'); 465 } 466 // If the result doesn't match the required version tag, return false. 467 if ($result->version < $requiredversion) { 468 return false; 469 } 470 // The version meets the requirement. 471 return true; 472 } 473 } 474 475 /** 476 * Retrieves the value for the given key from the cache. 477 * 478 * @param string|int $key The key for the data being requested. 479 * It can be any structure although using a scalar string or int is recommended in the interests of performance. 480 * In advanced cases an array may be useful such as in situations requiring the multi-key functionality. 481 * @param int $requiredversion Minimum required version of the data or cache::VERSION_NONE 482 * @param int $strictness One of IGNORE_MISSING | MUST_EXIST 483 * @param mixed $actualversion If specified, will be set to the actual version number retrieved 484 * @return mixed|false The data from the cache or false if the key did not exist within the cache. 485 * @throws coding_exception 486 */ 487 protected function get_implementation($key, int $requiredversion, int $strictness, &$actualversion = null) { 488 // 1. Get it from the static acceleration array if we can (only when it is enabled and it has already been requested/set). 489 $usesstaticacceleration = $this->use_static_acceleration(); 490 491 if ($usesstaticacceleration) { 492 $result = $this->static_acceleration_get($key); 493 if (cache_helper::result_found($result) && self::check_version($result, $requiredversion)) { 494 if ($requiredversion === self::VERSION_NONE) { 495 return $result; 496 } else { 497 $actualversion = $result->version; 498 return $result->data; 499 } 500 } 501 } 502 503 // 2. Parse the key. 504 $parsedkey = $this->parse_key($key); 505 506 // 3. Get it from the store. Obviously wasn't in the static acceleration array. 507 $result = $this->store->get($parsedkey); 508 if (cache_helper::result_found($result)) { 509 // Check the result has at least the required version. 510 try { 511 $validversion = self::check_version($result, $requiredversion); 512 } catch (\coding_exception $e) { 513 // In certain circumstances this could happen before users are taken to the upgrade 514 // screen when upgrading from an earlier Moodle version that didn't use a versioned 515 // cache for this item, so redirect instead of showing error if that's the case. 516 redirect_if_major_upgrade_required(); 517 518 // If we still get an exception because there is incorrect data in the cache (not 519 // versioned when it ought to be), delete it so this exception goes away next time. 520 // The exception should only happen if there is a code bug (which is why we still 521 // throw it) but there are unusual scenarios in development where it might happen 522 // and that would be annoying if it doesn't fix itself. 523 $this->store->delete($parsedkey); 524 throw $e; 525 } 526 527 if (!$validversion) { 528 // If the result was too old, don't use it. 529 $result = false; 530 531 // Also delete it immediately. This improves performance in the 532 // case when the cache item is large and there may be multiple clients simultaneously 533 // requesting it - they won't all have to do a megabyte of IO just in order to find 534 // that it's out of date. 535 $this->store->delete($parsedkey); 536 } 537 } 538 if (cache_helper::result_found($result)) { 539 // Look to see if there's a TTL wrapper. It might be inside a version wrapper. 540 if ($requiredversion !== self::VERSION_NONE) { 541 $ttlconsider = $result->data; 542 } else { 543 $ttlconsider = $result; 544 } 545 if ($ttlconsider instanceof cache_ttl_wrapper) { 546 if ($ttlconsider->has_expired()) { 547 $this->store->delete($parsedkey); 548 $result = false; 549 } else if ($requiredversion === self::VERSION_NONE) { 550 // Use the data inside the TTL wrapper as the result. 551 $result = $ttlconsider->data; 552 } else { 553 // Put the data from the TTL wrapper directly inside the version wrapper. 554 $result->data = $ttlconsider->data; 555 } 556 } 557 if ($usesstaticacceleration) { 558 $this->static_acceleration_set($key, $result); 559 } 560 // Remove version wrapper if necessary. 561 if ($requiredversion !== self::VERSION_NONE) { 562 $actualversion = $result->version; 563 $result = $result->data; 564 } 565 if ($result instanceof cache_cached_object) { 566 $result = $result->restore_object(); 567 } 568 } 569 570 // 4. Load if from the loader/datasource if we don't already have it. 571 $setaftervalidation = false; 572 if (!cache_helper::result_found($result)) { 573 if ($this->perfdebug) { 574 cache_helper::record_cache_miss($this->store, $this->definition); 575 } 576 if ($this->loader !== false) { 577 // We must pass the original (unparsed) key to the next loader in the chain. 578 // The next loader will parse the key as it sees fit. It may be parsed differently 579 // depending upon the capabilities of the store associated with the loader. 580 if ($requiredversion === self::VERSION_NONE) { 581 $result = $this->loader->get($key); 582 } else { 583 $result = $this->loader->get_versioned($key, $requiredversion, IGNORE_MISSING, $actualversion); 584 } 585 } else if ($this->datasource !== false) { 586 if ($requiredversion === self::VERSION_NONE) { 587 $result = $this->datasource->load_for_cache($key); 588 } else { 589 if (!$this->datasource instanceof cache_data_source_versionable) { 590 throw new \coding_exception('Data source is not versionable'); 591 } 592 $result = $this->datasource->load_for_cache_versioned($key, $requiredversion, $actualversion); 593 if ($result && $actualversion < $requiredversion) { 594 throw new \coding_exception('Data source returned outdated version'); 595 } 596 } 597 } 598 $setaftervalidation = (cache_helper::result_found($result)); 599 } else if ($this->perfdebug) { 600 $readbytes = $this->store->get_last_io_bytes(); 601 cache_helper::record_cache_hit($this->store, $this->definition, 1, $readbytes); 602 } 603 // 5. Validate strictness. 604 if ($strictness === MUST_EXIST && !cache_helper::result_found($result)) { 605 throw new coding_exception('Requested key did not exist in any cache stores and could not be loaded.'); 606 } 607 // 6. Set it to the store if we got it from the loader/datasource. Only set to this direct 608 // store; parent method will have set it to all stores if needed. 609 if ($setaftervalidation) { 610 if ($requiredversion === self::VERSION_NONE) { 611 $this->set_implementation($key, self::VERSION_NONE, $result, false); 612 } else { 613 $this->set_implementation($key, $actualversion, $result, false); 614 } 615 } 616 // 7. Make sure we don't pass back anything that could be a reference. 617 // We don't want people modifying the data in the cache. 618 if (!$this->store->supports_dereferencing_objects() && !is_scalar($result)) { 619 // If data is an object it will be a reference. 620 // If data is an array if may contain references. 621 // We want to break references so that the cache cannot be modified outside of itself. 622 // Call the function to unreference it (in the best way possible). 623 $result = $this->unref($result); 624 } 625 return $result; 626 } 627 628 /** 629 * Retrieves an array of values for an array of keys. 630 * 631 * Using this function comes with potential performance implications. 632 * Not all cache stores will support get_many/set_many operations and in order to replicate this functionality will call 633 * the equivalent singular method for each item provided. 634 * This should not deter you from using this function as there is a performance benefit in situations where the cache store 635 * does support it, but you should be aware of this fact. 636 * 637 * @param array $keys The keys of the data being requested. 638 * Each key can be any structure although using a scalar string or int is recommended in the interests of performance. 639 * In advanced cases an array may be useful such as in situations requiring the multi-key functionality. 640 * @param int $strictness One of IGNORE_MISSING or MUST_EXIST. 641 * @return array An array of key value pairs for the items that could be retrieved from the cache. 642 * If MUST_EXIST was used and not all keys existed within the cache then an exception will be thrown. 643 * Otherwise any key that did not exist will have a data value of false within the results. 644 * @throws coding_exception 645 */ 646 public function get_many(array $keys, $strictness = IGNORE_MISSING) { 647 648 $keysparsed = array(); 649 $parsedkeys = array(); 650 $resultpersist = array(); 651 $resultstore = array(); 652 $keystofind = array(); 653 $readbytes = cache_store::IO_BYTES_NOT_SUPPORTED; 654 655 // First up check the persist cache for each key. 656 $isusingpersist = $this->use_static_acceleration(); 657 foreach ($keys as $key) { 658 $pkey = $this->parse_key($key); 659 if (is_array($pkey)) { 660 $pkey = $pkey['key']; 661 } 662 $keysparsed[$key] = $pkey; 663 $parsedkeys[$pkey] = $key; 664 $keystofind[$pkey] = $key; 665 if ($isusingpersist) { 666 $value = $this->static_acceleration_get($key); 667 if ($value !== false) { 668 $resultpersist[$pkey] = $value; 669 unset($keystofind[$pkey]); 670 } 671 } 672 } 673 674 // Next assuming we didn't find all of the keys in the persist cache try loading them from the store. 675 if (count($keystofind)) { 676 $resultstore = $this->store->get_many(array_keys($keystofind)); 677 if ($this->perfdebug) { 678 $readbytes = $this->store->get_last_io_bytes(); 679 } 680 // Process each item in the result to "unwrap" it. 681 foreach ($resultstore as $key => $value) { 682 if ($value instanceof cache_ttl_wrapper) { 683 if ($value->has_expired()) { 684 $value = false; 685 } else { 686 $value = $value->data; 687 } 688 } 689 if ($value !== false && $this->use_static_acceleration()) { 690 $this->static_acceleration_set($keystofind[$key], $value); 691 } 692 if ($value instanceof cache_cached_object) { 693 $value = $value->restore_object(); 694 } 695 $resultstore[$key] = $value; 696 } 697 } 698 699 // Merge the result from the persis cache with the results from the store load. 700 $result = $resultpersist + $resultstore; 701 unset($resultpersist); 702 unset($resultstore); 703 704 // Next we need to find any missing values and load them from the loader/datasource next in the chain. 705 $usingloader = ($this->loader !== false); 706 $usingsource = (!$usingloader && ($this->datasource !== false)); 707 if ($usingloader || $usingsource) { 708 $missingkeys = array(); 709 foreach ($result as $key => $value) { 710 if ($value === false) { 711 $missingkeys[] = $parsedkeys[$key]; 712 } 713 } 714 if (!empty($missingkeys)) { 715 if ($usingloader) { 716 $resultmissing = $this->loader->get_many($missingkeys); 717 } else { 718 $resultmissing = $this->datasource->load_many_for_cache($missingkeys); 719 } 720 foreach ($resultmissing as $key => $value) { 721 $result[$keysparsed[$key]] = $value; 722 if ($value !== false) { 723 $this->set($key, $value); 724 } 725 } 726 unset($resultmissing); 727 } 728 unset($missingkeys); 729 } 730 731 // Create an array with the original keys and the found values. This will be what we return. 732 $fullresult = array(); 733 foreach ($result as $key => $value) { 734 if (!is_scalar($value)) { 735 // If data is an object it will be a reference. 736 // If data is an array if may contain references. 737 // We want to break references so that the cache cannot be modified outside of itself. 738 // Call the function to unreference it (in the best way possible). 739 $value = $this->unref($value); 740 } 741 $fullresult[$parsedkeys[$key]] = $value; 742 } 743 unset($result); 744 745 // Final step is to check strictness. 746 if ($strictness === MUST_EXIST) { 747 foreach ($keys as $key) { 748 if (!array_key_exists($key, $fullresult)) { 749 throw new coding_exception('Not all the requested keys existed within the cache stores.'); 750 } 751 } 752 } 753 754 if ($this->perfdebug) { 755 $hits = 0; 756 $misses = 0; 757 foreach ($fullresult as $value) { 758 if ($value === false) { 759 $misses++; 760 } else { 761 $hits++; 762 } 763 } 764 cache_helper::record_cache_hit($this->store, $this->definition, $hits, $readbytes); 765 cache_helper::record_cache_miss($this->store, $this->definition, $misses); 766 } 767 768 // Return the result. Phew! 769 return $fullresult; 770 } 771 772 /** 773 * Sends a key => value pair to the cache. 774 * 775 * <code> 776 * // This code will add four entries to the cache, one for each url. 777 * $cache->set('main', 'http://moodle.org'); 778 * $cache->set('docs', 'http://docs.moodle.org'); 779 * $cache->set('tracker', 'http://tracker.moodle.org'); 780 * $cache->set('qa', 'http://qa.moodle.net'); 781 * </code> 782 * 783 * @param string|int $key The key for the data being requested. 784 * It can be any structure although using a scalar string or int is recommended in the interests of performance. 785 * In advanced cases an array may be useful such as in situations requiring the multi-key functionality. 786 * @param mixed $data The data to set against the key. 787 * @return bool True on success, false otherwise. 788 */ 789 public function set($key, $data) { 790 return $this->set_implementation($key, self::VERSION_NONE, $data); 791 } 792 793 /** 794 * Sets the value for the given key with the given version. 795 * 796 * The cache does not store multiple versions - any existing version will be overwritten with 797 * this one. This function should only be used if there is a known 'current version' (e.g. 798 * stored in a database table). It only ensures that the cache does not return outdated data. 799 * 800 * This function can be used to help implement localisable caches (where the cache could be 801 * stored on a local server as well as a shared cache). The version will be recorded alongside 802 * the item and get_versioned will always return the correct version. 803 * 804 * The version number must be an integer that always increases. This could be based on the 805 * current time, or a stored value that increases by 1 each time it changes, etc. 806 * 807 * If you use this function you must use get_versioned to retrieve the data. 808 * 809 * @param string|int $key The key for the data being set. 810 * @param int $version Integer for the version of the data 811 * @param mixed $data The data to set against the key. 812 * @return bool True on success, false otherwise. 813 */ 814 public function set_versioned($key, int $version, $data): bool { 815 return $this->set_implementation($key, $version, $data); 816 } 817 818 /** 819 * Sets the value for the given key, optionally with a version tag. 820 * 821 * @param string|int $key The key for the data being set. 822 * @param int $version Version number for the data or cache::VERSION_NONE if none 823 * @param mixed $data The data to set against the key. 824 * @param bool $setparents If true, sets all parent loaders, otherwise only this one 825 * @return bool True on success, false otherwise. 826 */ 827 protected function set_implementation($key, int $version, $data, bool $setparents = true): bool { 828 if ($this->loader !== false && $setparents) { 829 // We have a loader available set it there as well. 830 // We have to let the loader do its own parsing of data as it may be unique. 831 if ($version === self::VERSION_NONE) { 832 $this->loader->set($key, $data); 833 } else { 834 $this->loader->set_versioned($key, $version, $data); 835 } 836 } 837 $usestaticacceleration = $this->use_static_acceleration(); 838 839 if (is_object($data) && $data instanceof cacheable_object) { 840 $data = new cache_cached_object($data); 841 } else if (!$this->store->supports_dereferencing_objects() && !is_scalar($data)) { 842 // If data is an object it will be a reference. 843 // If data is an array if may contain references. 844 // We want to break references so that the cache cannot be modified outside of itself. 845 // Call the function to unreference it (in the best way possible). 846 $data = $this->unref($data); 847 } 848 849 if ($usestaticacceleration) { 850 // Static acceleration cache should include the cache version wrapper, but not TTL. 851 if ($version === self::VERSION_NONE) { 852 $this->static_acceleration_set($key, $data); 853 } else { 854 $this->static_acceleration_set($key, new \core_cache\version_wrapper($data, $version)); 855 } 856 } 857 858 if ($this->has_a_ttl() && !$this->store_supports_native_ttl()) { 859 $data = new cache_ttl_wrapper($data, $this->definition->get_ttl()); 860 } 861 $parsedkey = $this->parse_key($key); 862 863 if ($version !== self::VERSION_NONE) { 864 $data = new \core_cache\version_wrapper($data, $version); 865 } 866 867 $success = $this->store->set($parsedkey, $data); 868 if ($this->perfdebug) { 869 cache_helper::record_cache_set($this->store, $this->definition, 1, 870 $this->store->get_last_io_bytes()); 871 } 872 return $success; 873 } 874 875 /** 876 * Removes references where required. 877 * 878 * @param stdClass|array $data 879 * @return mixed What ever was put in but without any references. 880 */ 881 protected function unref($data) { 882 if ($this->definition->uses_simple_data()) { 883 return $data; 884 } 885 // Check if it requires serialisation in order to produce a reference free copy. 886 if ($this->requires_serialisation($data)) { 887 // Damn, its going to have to be serialise. 888 $data = serialize($data); 889 // We unserialise immediately so that we don't have to do it every time on get. 890 $data = unserialize($data); 891 } else if (!is_scalar($data)) { 892 // Its safe to clone, lets do it, its going to beat the pants of serialisation. 893 $data = $this->deep_clone($data); 894 } 895 return $data; 896 } 897 898 /** 899 * Checks to see if a var requires serialisation. 900 * 901 * @param mixed $value The value to check. 902 * @param int $depth Used to ensure we don't enter an endless loop (think recursion). 903 * @return bool Returns true if the value is going to require serialisation in order to ensure a reference free copy 904 * or false if its safe to clone. 905 */ 906 protected function requires_serialisation($value, $depth = 1) { 907 if (is_scalar($value)) { 908 return false; 909 } else if (is_array($value) || $value instanceof stdClass || $value instanceof Traversable) { 910 if ($depth > 5) { 911 // Skrew it, mega-deep object, developer you suck, we're just going to serialise. 912 return true; 913 } 914 foreach ($value as $key => $subvalue) { 915 if ($this->requires_serialisation($subvalue, $depth++)) { 916 return true; 917 } 918 } 919 } 920 // Its not scalar, array, or stdClass so we'll need to serialise. 921 return true; 922 } 923 924 /** 925 * Creates a reference free clone of the given value. 926 * 927 * @param mixed $value 928 * @return mixed 929 */ 930 protected function deep_clone($value) { 931 if (is_object($value)) { 932 // Objects must be cloned to begin with. 933 $value = clone $value; 934 } 935 if (is_array($value) || is_object($value)) { 936 foreach ($value as $key => $subvalue) { 937 $value[$key] = $this->deep_clone($subvalue); 938 } 939 } 940 return $value; 941 } 942 943 /** 944 * Sends several key => value pairs to the cache. 945 * 946 * Using this function comes with potential performance implications. 947 * Not all cache stores will support get_many/set_many operations and in order to replicate this functionality will call 948 * the equivalent singular method for each item provided. 949 * This should not deter you from using this function as there is a performance benefit in situations where the cache store 950 * does support it, but you should be aware of this fact. 951 * 952 * <code> 953 * // This code will add four entries to the cache, one for each url. 954 * $cache->set_many(array( 955 * 'main' => 'http://moodle.org', 956 * 'docs' => 'http://docs.moodle.org', 957 * 'tracker' => 'http://tracker.moodle.org', 958 * 'qa' => ''http://qa.moodle.net' 959 * )); 960 * </code> 961 * 962 * @param array $keyvaluearray An array of key => value pairs to send to the cache. 963 * @return int The number of items successfully set. It is up to the developer to check this matches the number of items. 964 * ... if they care that is. 965 */ 966 public function set_many(array $keyvaluearray) { 967 if ($this->loader !== false) { 968 // We have a loader available set it there as well. 969 // We have to let the loader do its own parsing of data as it may be unique. 970 $this->loader->set_many($keyvaluearray); 971 } 972 $data = array(); 973 $simulatettl = $this->has_a_ttl() && !$this->store_supports_native_ttl(); 974 $usestaticaccelerationarray = $this->use_static_acceleration(); 975 $needsdereferencing = !$this->store->supports_dereferencing_objects(); 976 foreach ($keyvaluearray as $key => $value) { 977 if (is_object($value) && $value instanceof cacheable_object) { 978 $value = new cache_cached_object($value); 979 } else if ($needsdereferencing && !is_scalar($value)) { 980 // If data is an object it will be a reference. 981 // If data is an array if may contain references. 982 // We want to break references so that the cache cannot be modified outside of itself. 983 // Call the function to unreference it (in the best way possible). 984 $value = $this->unref($value); 985 } 986 if ($usestaticaccelerationarray) { 987 $this->static_acceleration_set($key, $value); 988 } 989 if ($simulatettl) { 990 $value = new cache_ttl_wrapper($value, $this->definition->get_ttl()); 991 } 992 $data[$key] = array( 993 'key' => $this->parse_key($key), 994 'value' => $value 995 ); 996 } 997 $successfullyset = $this->store->set_many($data); 998 if ($this->perfdebug && $successfullyset) { 999 cache_helper::record_cache_set($this->store, $this->definition, $successfullyset, 1000 $this->store->get_last_io_bytes()); 1001 } 1002 return $successfullyset; 1003 } 1004 1005 /** 1006 * Test is a cache has a key. 1007 * 1008 * The use of the has methods is strongly discouraged. In a high load environment the cache may well change between the 1009 * test and any subsequent action (get, set, delete etc). 1010 * Instead it is recommended to write your code in such a way they it performs the following steps: 1011 * <ol> 1012 * <li>Attempt to retrieve the information.</li> 1013 * <li>Generate the information.</li> 1014 * <li>Attempt to set the information</li> 1015 * </ol> 1016 * 1017 * Its also worth mentioning that not all stores support key tests. 1018 * For stores that don't support key tests this functionality is mimicked by using the equivalent get method. 1019 * Just one more reason you should not use these methods unless you have a very good reason to do so. 1020 * 1021 * @param string|int $key 1022 * @param bool $tryloadifpossible If set to true, the cache doesn't contain the key, and there is another cache loader or 1023 * data source then the code will try load the key value from the next item in the chain. 1024 * @return bool True if the cache has the requested key, false otherwise. 1025 */ 1026 public function has($key, $tryloadifpossible = false) { 1027 if ($this->static_acceleration_has($key)) { 1028 // Hoorah, that was easy. It exists in the static acceleration array so we definitely have it. 1029 return true; 1030 } 1031 $parsedkey = $this->parse_key($key); 1032 1033 if ($this->has_a_ttl() && !$this->store_supports_native_ttl()) { 1034 // The data has a TTL and the store doesn't support it natively. 1035 // We must fetch the data and expect a ttl wrapper. 1036 $data = $this->store->get($parsedkey); 1037 $has = ($data instanceof cache_ttl_wrapper && !$data->has_expired()); 1038 } else if (!$this->store_supports_key_awareness()) { 1039 // The store doesn't support key awareness, get the data and check it manually... puke. 1040 // Either no TTL is set of the store supports its handling natively. 1041 $data = $this->store->get($parsedkey); 1042 $has = ($data !== false); 1043 } else { 1044 // The store supports key awareness, this is easy! 1045 // Either no TTL is set of the store supports its handling natively. 1046 $has = $this->store->has($parsedkey); 1047 } 1048 if (!$has && $tryloadifpossible) { 1049 if ($this->loader !== false) { 1050 $result = $this->loader->get($parsedkey); 1051 } else if ($this->datasource !== null) { 1052 $result = $this->datasource->load_for_cache($key); 1053 } 1054 $has = ($result !== null); 1055 if ($has) { 1056 $this->set($key, $result); 1057 } 1058 } 1059 return $has; 1060 } 1061 1062 /** 1063 * Test is a cache has all of the given keys. 1064 * 1065 * It is strongly recommended to avoid the use of this function if not absolutely required. 1066 * In a high load environment the cache may well change between the test and any subsequent action (get, set, delete etc). 1067 * 1068 * Its also worth mentioning that not all stores support key tests. 1069 * For stores that don't support key tests this functionality is mimicked by using the equivalent get method. 1070 * Just one more reason you should not use these methods unless you have a very good reason to do so. 1071 * 1072 * @param array $keys 1073 * @return bool True if the cache has all of the given keys, false otherwise. 1074 */ 1075 public function has_all(array $keys) { 1076 if (($this->has_a_ttl() && !$this->store_supports_native_ttl()) || !$this->store_supports_key_awareness()) { 1077 foreach ($keys as $key) { 1078 if (!$this->has($key)) { 1079 return false; 1080 } 1081 } 1082 return true; 1083 } 1084 $parsedkeys = array_map(array($this, 'parse_key'), $keys); 1085 return $this->store->has_all($parsedkeys); 1086 } 1087 1088 /** 1089 * Test if a cache has at least one of the given keys. 1090 * 1091 * It is strongly recommended to avoid the use of this function if not absolutely required. 1092 * In a high load environment the cache may well change between the test and any subsequent action (get, set, delete etc). 1093 * 1094 * Its also worth mentioning that not all stores support key tests. 1095 * For stores that don't support key tests this functionality is mimicked by using the equivalent get method. 1096 * Just one more reason you should not use these methods unless you have a very good reason to do so. 1097 * 1098 * @param array $keys 1099 * @return bool True if the cache has at least one of the given keys 1100 */ 1101 public function has_any(array $keys) { 1102 if (($this->has_a_ttl() && !$this->store_supports_native_ttl()) || !$this->store_supports_key_awareness()) { 1103 foreach ($keys as $key) { 1104 if ($this->has($key)) { 1105 return true; 1106 } 1107 } 1108 return false; 1109 } 1110 1111 if ($this->use_static_acceleration()) { 1112 foreach ($keys as $id => $key) { 1113 if ($this->static_acceleration_has($key)) { 1114 return true; 1115 } 1116 } 1117 } 1118 $parsedkeys = array_map(array($this, 'parse_key'), $keys); 1119 return $this->store->has_any($parsedkeys); 1120 } 1121 1122 /** 1123 * Delete the given key from the cache. 1124 * 1125 * @param string|int $key The key to delete. 1126 * @param bool $recurse When set to true the key will also be deleted from all stacked cache loaders and their stores. 1127 * This happens by default and ensure that all the caches are consistent. It is NOT recommended to change this. 1128 * @return bool True of success, false otherwise. 1129 */ 1130 public function delete($key, $recurse = true) { 1131 $this->static_acceleration_delete($key); 1132 if ($recurse && $this->loader !== false) { 1133 // Delete from the bottom of the stack first. 1134 $this->loader->delete($key, $recurse); 1135 } 1136 $parsedkey = $this->parse_key($key); 1137 return $this->store->delete($parsedkey); 1138 } 1139 1140 /** 1141 * Delete all of the given keys from the cache. 1142 * 1143 * @param array $keys The key to delete. 1144 * @param bool $recurse When set to true the key will also be deleted from all stacked cache loaders and their stores. 1145 * This happens by default and ensure that all the caches are consistent. It is NOT recommended to change this. 1146 * @return int The number of items successfully deleted. 1147 */ 1148 public function delete_many(array $keys, $recurse = true) { 1149 if ($this->use_static_acceleration()) { 1150 foreach ($keys as $key) { 1151 $this->static_acceleration_delete($key); 1152 } 1153 } 1154 if ($recurse && $this->loader !== false) { 1155 // Delete from the bottom of the stack first. 1156 $this->loader->delete_many($keys, $recurse); 1157 } 1158 $parsedkeys = array_map(array($this, 'parse_key'), $keys); 1159 return $this->store->delete_many($parsedkeys); 1160 } 1161 1162 /** 1163 * Purges the cache store, and loader if there is one. 1164 * 1165 * @return bool True on success, false otherwise 1166 */ 1167 public function purge() { 1168 // 1. Purge the static acceleration array. 1169 $this->static_acceleration_purge(); 1170 // 2. Purge the store. 1171 $this->store->purge(); 1172 // 3. Optionally pruge any stacked loaders. 1173 if ($this->loader) { 1174 $this->loader->purge(); 1175 } 1176 return true; 1177 } 1178 1179 /** 1180 * Parses the key turning it into a string (or array is required) suitable to be passed to the cache store. 1181 * 1182 * @param string|int $key As passed to get|set|delete etc. 1183 * @return string|array String unless the store supports multi-identifiers in which case an array if returned. 1184 */ 1185 protected function parse_key($key) { 1186 // First up if the store supports multiple keys we'll go with that. 1187 if ($this->store->supports_multiple_identifiers()) { 1188 $result = $this->definition->generate_multi_key_parts(); 1189 $result['key'] = $key; 1190 return $result; 1191 } 1192 // If not we need to generate a hash and to for that we use the cache_helper. 1193 return cache_helper::hash_key($key, $this->definition); 1194 } 1195 1196 /** 1197 * Returns true if the cache is making use of a ttl. 1198 * @return bool 1199 */ 1200 protected function has_a_ttl() { 1201 return $this->hasattl; 1202 } 1203 1204 /** 1205 * Returns true if the cache store supports native ttl. 1206 * @return bool 1207 */ 1208 protected function store_supports_native_ttl() { 1209 if ($this->supportsnativettl === null) { 1210 $this->supportsnativettl = ($this->store->supports_native_ttl()); 1211 } 1212 return $this->supportsnativettl; 1213 } 1214 1215 /** 1216 * Returns the cache definition. 1217 * 1218 * @return cache_definition 1219 */ 1220 protected function get_definition() { 1221 return $this->definition; 1222 } 1223 1224 /** 1225 * Returns the cache store 1226 * 1227 * @return cache_store 1228 */ 1229 protected function get_store() { 1230 return $this->store; 1231 } 1232 1233 /** 1234 * Returns the loader associated with this instance. 1235 * 1236 * @since Moodle 2.4.4 1237 * @return cache|false 1238 */ 1239 protected function get_loader() { 1240 return $this->loader; 1241 } 1242 1243 /** 1244 * Returns the data source associated with this cache. 1245 * 1246 * @since Moodle 2.4.4 1247 * @return cache_data_source|false 1248 */ 1249 protected function get_datasource() { 1250 return $this->datasource; 1251 } 1252 1253 /** 1254 * Returns true if the store supports key awareness. 1255 * 1256 * @return bool 1257 */ 1258 protected function store_supports_key_awareness() { 1259 if ($this->supportskeyawareness === null) { 1260 $this->supportskeyawareness = ($this->store instanceof cache_is_key_aware); 1261 } 1262 return $this->supportskeyawareness; 1263 } 1264 1265 /** 1266 * Returns true if the store natively supports locking. 1267 * 1268 * @return bool 1269 */ 1270 protected function store_supports_native_locking() { 1271 if ($this->nativelocking === null) { 1272 $this->nativelocking = ($this->store instanceof cache_is_lockable); 1273 } 1274 return $this->nativelocking; 1275 } 1276 1277 /** 1278 * @deprecated since 2.6 1279 * @see cache::use_static_acceleration() 1280 */ 1281 protected function is_using_persist_cache() { 1282 throw new coding_exception('cache::is_using_persist_cache() can not be used anymore.' . 1283 ' Please use cache::use_static_acceleration() instead.'); 1284 } 1285 1286 /** 1287 * Returns true if this cache is making use of the static acceleration array. 1288 * 1289 * @return bool 1290 */ 1291 protected function use_static_acceleration() { 1292 return $this->staticacceleration; 1293 } 1294 1295 /** 1296 * @see cache::static_acceleration_has 1297 * @deprecated since 2.6 1298 */ 1299 protected function is_in_persist_cache() { 1300 throw new coding_exception('cache::is_in_persist_cache() can not be used anymore.' . 1301 ' Please use cache::static_acceleration_has() instead.'); 1302 } 1303 1304 /** 1305 * Returns true if the requested key exists within the static acceleration array. 1306 * 1307 * @param string $key The parsed key 1308 * @return bool 1309 */ 1310 protected function static_acceleration_has($key) { 1311 // This could be written as a single line, however it has been split because the ttl check is faster than the instanceof 1312 // and has_expired calls. 1313 if (!$this->staticacceleration || !isset($this->staticaccelerationarray[$key])) { 1314 return false; 1315 } 1316 return true; 1317 } 1318 1319 /** 1320 * @deprecated since 2.6 1321 * @see cache::static_acceleration_get 1322 */ 1323 protected function get_from_persist_cache() { 1324 throw new coding_exception('cache::get_from_persist_cache() can not be used anymore.' . 1325 ' Please use cache::static_acceleration_get() instead.'); 1326 } 1327 1328 /** 1329 * Returns the item from the static acceleration array if it exists there. 1330 * 1331 * @param string $key The parsed key 1332 * @return mixed|false Dereferenced data from the static acceleration array or false if it wasn't there. 1333 */ 1334 protected function static_acceleration_get($key) { 1335 if (!$this->staticacceleration || !isset($this->staticaccelerationarray[$key])) { 1336 $result = false; 1337 } else { 1338 $data = $this->staticaccelerationarray[$key]['data']; 1339 1340 if ($data instanceof cache_cached_object) { 1341 $result = $data->restore_object(); 1342 } else if ($this->staticaccelerationarray[$key]['serialized']) { 1343 $result = unserialize($data); 1344 } else { 1345 $result = $data; 1346 } 1347 } 1348 if (cache_helper::result_found($result)) { 1349 if ($this->perfdebug) { 1350 cache_helper::record_cache_hit(cache_store::STATIC_ACCEL, $this->definition); 1351 } 1352 if ($this->staticaccelerationsize > 1 && $this->staticaccelerationcount > 1) { 1353 // Check to see if this is the last item on the static acceleration keys array. 1354 if (end($this->staticaccelerationkeys) !== $key) { 1355 // It isn't the last item. 1356 // Move the item to the end of the array so that it is last to be removed. 1357 unset($this->staticaccelerationkeys[$key]); 1358 $this->staticaccelerationkeys[$key] = $key; 1359 } 1360 } 1361 return $result; 1362 } else { 1363 if ($this->perfdebug) { 1364 cache_helper::record_cache_miss(cache_store::STATIC_ACCEL, $this->definition); 1365 } 1366 return false; 1367 } 1368 } 1369 1370 /** 1371 * @deprecated since 2.6 1372 * @see cache::static_acceleration_set 1373 */ 1374 protected function set_in_persist_cache() { 1375 throw new coding_exception('cache::set_in_persist_cache() can not be used anymore.' . 1376 ' Please use cache::static_acceleration_set() instead.'); 1377 } 1378 1379 /** 1380 * Sets a key value pair into the static acceleration array. 1381 * 1382 * @param string $key The parsed key 1383 * @param mixed $data 1384 * @return bool 1385 */ 1386 protected function static_acceleration_set($key, $data) { 1387 if ($this->staticaccelerationsize !== false && isset($this->staticaccelerationkeys[$key])) { 1388 $this->staticaccelerationcount--; 1389 unset($this->staticaccelerationkeys[$key]); 1390 } 1391 1392 // We serialize anything that's not; 1393 // 1. A known scalar safe value. 1394 // 2. A definition that says it's simpledata. We trust it that it doesn't contain dangerous references. 1395 // 3. An object that handles dereferencing by itself. 1396 if (is_scalar($data) || $this->definition->uses_simple_data() 1397 || $data instanceof cache_cached_object) { 1398 $this->staticaccelerationarray[$key]['data'] = $data; 1399 $this->staticaccelerationarray[$key]['serialized'] = false; 1400 } else { 1401 $this->staticaccelerationarray[$key]['data'] = serialize($data); 1402 $this->staticaccelerationarray[$key]['serialized'] = true; 1403 } 1404 if ($this->staticaccelerationsize !== false) { 1405 $this->staticaccelerationcount++; 1406 $this->staticaccelerationkeys[$key] = $key; 1407 if ($this->staticaccelerationcount > $this->staticaccelerationsize) { 1408 $dropkey = array_shift($this->staticaccelerationkeys); 1409 unset($this->staticaccelerationarray[$dropkey]); 1410 $this->staticaccelerationcount--; 1411 } 1412 } 1413 return true; 1414 } 1415 1416 /** 1417 * @deprecated since 2.6 1418 * @see cache::static_acceleration_delete() 1419 */ 1420 protected function delete_from_persist_cache() { 1421 throw new coding_exception('cache::delete_from_persist_cache() can not be used anymore.' . 1422 ' Please use cache::static_acceleration_delete() instead.'); 1423 } 1424 1425 /** 1426 * Deletes an item from the static acceleration array. 1427 * 1428 * @param string|int $key As given to get|set|delete 1429 * @return bool True on success, false otherwise. 1430 */ 1431 protected function static_acceleration_delete($key) { 1432 unset($this->staticaccelerationarray[$key]); 1433 if ($this->staticaccelerationsize !== false && isset($this->staticaccelerationkeys[$key])) { 1434 unset($this->staticaccelerationkeys[$key]); 1435 $this->staticaccelerationcount--; 1436 } 1437 return true; 1438 } 1439 1440 /** 1441 * Purge the static acceleration cache. 1442 */ 1443 protected function static_acceleration_purge() { 1444 $this->staticaccelerationarray = array(); 1445 if ($this->staticaccelerationsize !== false) { 1446 $this->staticaccelerationkeys = array(); 1447 $this->staticaccelerationcount = 0; 1448 } 1449 } 1450 1451 /** 1452 * Returns the timestamp from the first request for the time from the cache API. 1453 * 1454 * This stamp needs to be used for all ttl and time based operations to ensure that we don't end up with 1455 * timing issues. 1456 * 1457 * @param bool $float Whether to use floating precision accuracy. 1458 * @return int|float 1459 */ 1460 public static function now($float = false) { 1461 if (self::$now === null) { 1462 self::$now = microtime(true); 1463 } 1464 1465 if ($float) { 1466 return self::$now; 1467 } else { 1468 return (int) self::$now; 1469 } 1470 } 1471 1472 /** 1473 * Get a 'purge' token used for cache invalidation handling. 1474 * 1475 * Note: This function is intended for use from within the Cache API only and not by plugins, or cache stores. 1476 * 1477 * @param bool $reset Whether to reset the token and generate a new one. 1478 * @return string 1479 */ 1480 public static function get_purge_token($reset = false) { 1481 if (self::$purgetoken === null || $reset) { 1482 self::$now = null; 1483 self::$purgetoken = self::now(true) . '-' . uniqid('', true); 1484 } 1485 1486 return self::$purgetoken; 1487 } 1488 1489 /** 1490 * Compare a pair of purge tokens. 1491 * 1492 * If the two tokens are identical, then the return value is 0. 1493 * If the time component of token A is newer than token B, then a positive value is returned. 1494 * If the time component of token B is newer than token A, then a negative value is returned. 1495 * 1496 * Note: This function is intended for use from within the Cache API only and not by plugins, or cache stores. 1497 * 1498 * @param string $tokena 1499 * @param string $tokenb 1500 * @return int 1501 */ 1502 public static function compare_purge_tokens($tokena, $tokenb) { 1503 if ($tokena === $tokenb) { 1504 // There is an exact match. 1505 return 0; 1506 } 1507 1508 // The token for when the cache was last invalidated. 1509 list($atime) = explode('-', "{$tokena}-", 2); 1510 1511 // The token for this cache. 1512 list($btime) = explode('-', "{$tokenb}-", 2); 1513 1514 if ($atime >= $btime) { 1515 // Token A is newer. 1516 return 1; 1517 } else { 1518 // Token A is older. 1519 return -1; 1520 } 1521 } 1522 1523 /** 1524 * Subclasses may support purging cache of all data belonging to the 1525 * current user. 1526 */ 1527 public function purge_current_user() { 1528 } 1529 } 1530 1531 /** 1532 * An application cache. 1533 * 1534 * This class is used for application caches returned by the cache::make methods. 1535 * On top of the standard functionality it also allows locking to be required and or manually operated. 1536 * 1537 * This cache class should never be interacted with directly. Instead you should always use the cache::make methods. 1538 * It is technically possible to call those methods through this class however there is no guarantee that you will get an 1539 * instance of this class back again. 1540 * 1541 * @internal don't use me directly. 1542 * 1543 * @package core 1544 * @category cache 1545 * @copyright 2012 Sam Hemelryk 1546 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later 1547 */ 1548 class cache_application extends cache implements cache_loader_with_locking { 1549 1550 /** 1551 * Lock identifier. 1552 * This is used to ensure the lock belongs to the cache instance + definition + user. 1553 * @var string 1554 */ 1555 protected $lockidentifier; 1556 1557 /** 1558 * Gets set to true if the cache's primary store natively supports locking. 1559 * If it does then we use that, otherwise we need to instantiate a second store to use for locking. 1560 * @var cache_store 1561 */ 1562 protected $nativelocking = null; 1563 1564 /** 1565 * Gets set to true if the cache is going to be using locking. 1566 * This isn't a requirement, it doesn't need to use locking (most won't) and this bool is used to quickly check things. 1567 * If required then locking will be forced for the get|set|delete operation. 1568 * @var bool 1569 */ 1570 protected $requirelocking = false; 1571 1572 /** 1573 * Gets set to true if the cache must use read locking (get|has). 1574 * @var bool 1575 */ 1576 protected $requirelockingread = false; 1577 1578 /** 1579 * Gets set to true if the cache must use write locking (set|delete) 1580 * @var bool 1581 */ 1582 protected $requirelockingwrite = false; 1583 1584 /** 1585 * Gets set to a cache_store to use for locking if the caches primary store doesn't support locking natively. 1586 * @var cache_lock_interface 1587 */ 1588 protected $cachelockinstance; 1589 1590 /** 1591 * Overrides the cache construct method. 1592 * 1593 * You should not call this method from your code, instead you should use the cache::make methods. 1594 * 1595 * @param cache_definition $definition 1596 * @param cache_store $store 1597 * @param cache_loader|cache_data_source $loader 1598 */ 1599 public function __construct(cache_definition $definition, cache_store $store, $loader = null) { 1600 parent::__construct($definition, $store, $loader); 1601 $this->nativelocking = $this->store_supports_native_locking(); 1602 if ($definition->require_locking()) { 1603 $this->requirelocking = true; 1604 $this->requirelockingread = $definition->require_locking_read(); 1605 $this->requirelockingwrite = $definition->require_locking_write(); 1606 } 1607 1608 $this->handle_invalidation_events(); 1609 } 1610 1611 /** 1612 * Returns the identifier to use 1613 * 1614 * @staticvar int $instances Counts the number of instances. Used as part of the lock identifier. 1615 * @return string 1616 */ 1617 public function get_identifier() { 1618 static $instances = 0; 1619 if ($this->lockidentifier === null) { 1620 $this->lockidentifier = md5( 1621 $this->get_definition()->generate_definition_hash() . 1622 sesskey() . 1623 $instances++ . 1624 'cache_application' 1625 ); 1626 } 1627 return $this->lockidentifier; 1628 } 1629 1630 /** 1631 * Fixes the instance up after a clone. 1632 */ 1633 public function __clone() { 1634 // Force a new idenfitier. 1635 $this->lockidentifier = null; 1636 } 1637 1638 /** 1639 * Acquires a lock on the given key. 1640 * 1641 * This is done automatically if the definition requires it. 1642 * It is recommended to use a definition if you want to have locking although it is possible to do locking without having 1643 * it required by the definition. 1644 * The problem with such an approach is that you cannot ensure that code will consistently use locking. You will need to 1645 * rely on the integrators review skills. 1646 * 1647 * @param string|int $key The key as given to get|set|delete 1648 * @return bool Returns true if the lock could be acquired, false otherwise. 1649 */ 1650 public function acquire_lock($key) { 1651 $key = $this->parse_key($key); 1652 if ($this->nativelocking) { 1653 return $this->get_store()->acquire_lock($key, $this->get_identifier()); 1654 } else { 1655 $this->ensure_cachelock_available(); 1656 return $this->cachelockinstance->lock($key, $this->get_identifier()); 1657 } 1658 } 1659 1660 /** 1661 * Checks if this cache has a lock on the given key. 1662 * 1663 * @param string|int $key The key as given to get|set|delete 1664 * @return bool|null Returns true if there is a lock and this cache has it, null if no one has a lock on that key, false if 1665 * someone else has the lock. 1666 */ 1667 public function check_lock_state($key) { 1668 $key = $this->parse_key($key); 1669 if ($this->nativelocking) { 1670 return $this->get_store()->check_lock_state($key, $this->get_identifier()); 1671 } else { 1672 $this->ensure_cachelock_available(); 1673 return $this->cachelockinstance->check_state($key, $this->get_identifier()); 1674 } 1675 } 1676 1677 /** 1678 * Releases the lock this cache has on the given key 1679 * 1680 * @param string|int $key 1681 * @return bool True if the operation succeeded, false otherwise. 1682 */ 1683 public function release_lock($key) { 1684 $key = $this->parse_key($key); 1685 if ($this->nativelocking) { 1686 return $this->get_store()->release_lock($key, $this->get_identifier()); 1687 } else { 1688 $this->ensure_cachelock_available(); 1689 return $this->cachelockinstance->unlock($key, $this->get_identifier()); 1690 } 1691 } 1692 1693 /** 1694 * Ensure that the dedicated lock store is ready to go. 1695 * 1696 * This should only happen if the cache store doesn't natively support it. 1697 */ 1698 protected function ensure_cachelock_available() { 1699 if ($this->cachelockinstance === null) { 1700 $this->cachelockinstance = cache_helper::get_cachelock_for_store($this->get_store()); 1701 } 1702 } 1703 1704 /** 1705 * Sends a key => value pair to the cache. 1706 * 1707 * <code> 1708 * // This code will add four entries to the cache, one for each url. 1709 * $cache->set('main', 'http://moodle.org'); 1710 * $cache->set('docs', 'http://docs.moodle.org'); 1711 * $cache->set('tracker', 'http://tracker.moodle.org'); 1712 * $cache->set('qa', 'http://qa.moodle.net'); 1713 * </code> 1714 * 1715 * @param string|int $key The key for the data being requested. 1716 * @param int $version Version number 1717 * @param mixed $data The data to set against the key. 1718 * @param bool $setparents If true, sets all parent loaders, otherwise only this one 1719 * @return bool True on success, false otherwise. 1720 */ 1721 protected function set_implementation($key, int $version, $data, bool $setparents = true): bool { 1722 if ($this->requirelockingwrite && !$this->acquire_lock($key)) { 1723 return false; 1724 } 1725 $result = parent::set_implementation($key, $version, $data, $setparents); 1726 if ($this->requirelockingwrite && !$this->release_lock($key)) { 1727 debugging('Failed to release cache lock on set operation... this should not happen.', DEBUG_DEVELOPER); 1728 } 1729 return $result; 1730 } 1731 1732 /** 1733 * Sends several key => value pairs to the cache. 1734 * 1735 * Using this function comes with potential performance implications. 1736 * Not all cache stores will support get_many/set_many operations and in order to replicate this functionality will call 1737 * the equivalent singular method for each item provided. 1738 * This should not deter you from using this function as there is a performance benefit in situations where the cache store 1739 * does support it, but you should be aware of this fact. 1740 * 1741 * <code> 1742 * // This code will add four entries to the cache, one for each url. 1743 * $cache->set_many(array( 1744 * 'main' => 'http://moodle.org', 1745 * 'docs' => 'http://docs.moodle.org', 1746 * 'tracker' => 'http://tracker.moodle.org', 1747 * 'qa' => ''http://qa.moodle.net' 1748 * )); 1749 * </code> 1750 * 1751 * @param array $keyvaluearray An array of key => value pairs to send to the cache. 1752 * @return int The number of items successfully set. It is up to the developer to check this matches the number of items. 1753 * ... if they care that is. 1754 */ 1755 public function set_many(array $keyvaluearray) { 1756 if ($this->requirelockingwrite) { 1757 $locks = array(); 1758 foreach ($keyvaluearray as $id => $pair) { 1759 $key = $pair['key']; 1760 if ($this->acquire_lock($key)) { 1761 $locks[] = $key; 1762 } else { 1763 unset($keyvaluearray[$id]); 1764 } 1765 } 1766 } 1767 $result = parent::set_many($keyvaluearray); 1768 if ($this->requirelockingwrite) { 1769 foreach ($locks as $key) { 1770 if ($this->release_lock($key)) { 1771 debugging('Failed to release cache lock on set_many operation... this should not happen.', DEBUG_DEVELOPER); 1772 } 1773 } 1774 } 1775 return $result; 1776 } 1777 1778 /** 1779 * Retrieves the value for the given key from the cache. 1780 * 1781 * @param string|int $key The key for the data being requested. 1782 * @param int $requiredversion Minimum required version of the data or cache::VERSION_NONE 1783 * @param int $strictness One of IGNORE_MISSING | MUST_EXIST 1784 * @param mixed &$actualversion If specified, will be set to the actual version number retrieved 1785 * @return mixed|false The data from the cache or false if the key did not exist within the cache. 1786 */ 1787 protected function get_implementation($key, int $requiredversion, int $strictness, &$actualversion = null) { 1788 if ($this->requirelockingread && $this->check_lock_state($key) === false) { 1789 // Read locking required and someone else has the read lock. 1790 return false; 1791 } 1792 return parent::get_implementation($key, $requiredversion, $strictness, $actualversion); 1793 } 1794 1795 /** 1796 * Retrieves an array of values for an array of keys. 1797 * 1798 * Using this function comes with potential performance implications. 1799 * Not all cache stores will support get_many/set_many operations and in order to replicate this functionality will call 1800 * the equivalent singular method for each item provided. 1801 * This should not deter you from using this function as there is a performance benefit in situations where the cache store 1802 * does support it, but you should be aware of this fact. 1803 * 1804 * @param array $keys The keys of the data being requested. 1805 * @param int $strictness One of IGNORE_MISSING or MUST_EXIST. 1806 * @return array An array of key value pairs for the items that could be retrieved from the cache. 1807 * If MUST_EXIST was used and not all keys existed within the cache then an exception will be thrown. 1808 * Otherwise any key that did not exist will have a data value of false within the results. 1809 * @throws coding_exception 1810 */ 1811 public function get_many(array $keys, $strictness = IGNORE_MISSING) { 1812 if ($this->requirelockingread) { 1813 foreach ($keys as $id => $key) { 1814 $lock =$this->acquire_lock($key); 1815 if (!$lock) { 1816 if ($strictness === MUST_EXIST) { 1817 throw new coding_exception('Could not acquire read locks for all of the items being requested.'); 1818 } else { 1819 // Can't return this as we couldn't get a read lock. 1820 unset($keys[$id]); 1821 } 1822 } 1823 1824 } 1825 } 1826 return parent::get_many($keys, $strictness); 1827 } 1828 1829 /** 1830 * Delete the given key from the cache. 1831 * 1832 * @param string|int $key The key to delete. 1833 * @param bool $recurse When set to true the key will also be deleted from all stacked cache loaders and their stores. 1834 * This happens by default and ensure that all the caches are consistent. It is NOT recommended to change this. 1835 * @return bool True of success, false otherwise. 1836 */ 1837 public function delete($key, $recurse = true) { 1838 if ($this->requirelockingwrite && !$this->acquire_lock($key)) { 1839 return false; 1840 } 1841 $result = parent::delete($key, $recurse); 1842 if ($this->requirelockingwrite && !$this->release_lock($key)) { 1843 debugging('Failed to release cache lock on delete operation... this should not happen.', DEBUG_DEVELOPER); 1844 } 1845 return $result; 1846 } 1847 1848 /** 1849 * Delete all of the given keys from the cache. 1850 * 1851 * @param array $keys The key to delete. 1852 * @param bool $recurse When set to true the key will also be deleted from all stacked cache loaders and their stores. 1853 * This happens by default and ensure that all the caches are consistent. It is NOT recommended to change this. 1854 * @return int The number of items successfully deleted. 1855 */ 1856 public function delete_many(array $keys, $recurse = true) { 1857 if ($this->requirelockingwrite) { 1858 $locks = array(); 1859 foreach ($keys as $id => $key) { 1860 if ($this->acquire_lock($key)) { 1861 $locks[] = $key; 1862 } else { 1863 unset($keys[$id]); 1864 } 1865 } 1866 } 1867 $result = parent::delete_many($keys, $recurse); 1868 if ($this->requirelockingwrite) { 1869 foreach ($locks as $key) { 1870 if ($this->release_lock($key)) { 1871 debugging('Failed to release cache lock on delete_many operation... this should not happen.', DEBUG_DEVELOPER); 1872 } 1873 } 1874 } 1875 return $result; 1876 } 1877 } 1878 1879 /** 1880 * A session cache. 1881 * 1882 * This class is used for session caches returned by the cache::make methods. 1883 * 1884 * It differs from the application loader in a couple of noteable ways: 1885 * 1. Sessions are always expected to exist. 1886 * Because of this we don't ever use the static acceleration array. 1887 * 2. Session data for a loader instance (store + definition) is consolidate into a 1888 * single array for storage within the store. 1889 * Along with this we embed a lastaccessed time with the data. This way we can 1890 * check sessions for a last access time. 1891 * 3. Session stores are required to support key searching and must 1892 * implement cache_is_searchable. This ensures stores used for the cache can be 1893 * targetted for garbage collection of session data. 1894 * 1895 * This cache class should never be interacted with directly. Instead you should always use the cache::make methods. 1896 * It is technically possible to call those methods through this class however there is no guarantee that you will get an 1897 * instance of this class back again. 1898 * 1899 * @todo we should support locking in the session as well. Should be pretty simple to set up. 1900 * 1901 * @internal don't use me directly. 1902 * @method cache_store|cache_is_searchable get_store() Returns the cache store which must implement both cache_is_searchable. 1903 * 1904 * @package core 1905 * @category cache 1906 * @copyright 2012 Sam Hemelryk 1907 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later 1908 */ 1909 class cache_session extends cache { 1910 /** 1911 * The user the session has been established for. 1912 * @var int 1913 */ 1914 protected static $loadeduserid = null; 1915 1916 /** 1917 * The userid this cache is currently using. 1918 * @var int 1919 */ 1920 protected $currentuserid = null; 1921 1922 /** 1923 * The session id we are currently using. 1924 * @var array 1925 */ 1926 protected $sessionid = null; 1927 1928 /** 1929 * The session data for the above session id. 1930 * @var array 1931 */ 1932 protected $session = null; 1933 1934 /** 1935 * Constant used to prefix keys. 1936 */ 1937 const KEY_PREFIX = 'sess_'; 1938 1939 /** 1940 * This is the key used to track last access. 1941 */ 1942 const LASTACCESS = '__lastaccess__'; 1943 1944 /** 1945 * Override the cache::construct method. 1946 * 1947 * This function gets overriden so that we can process any invalidation events if need be. 1948 * If the definition doesn't have any invalidation events then this occurs exactly as it would for the cache class. 1949 * Otherwise we look at the last invalidation time and then check the invalidation data for events that have occured 1950 * between then now. 1951 * 1952 * You should not call this method from your code, instead you should use the cache::make methods. 1953 * 1954 * @param cache_definition $definition 1955 * @param cache_store $store 1956 * @param cache_loader|cache_data_source $loader 1957 */ 1958 public function __construct(cache_definition $definition, cache_store $store, $loader = null) { 1959 // First up copy the loadeduserid to the current user id. 1960 $this->currentuserid = self::$loadeduserid; 1961 $this->set_session_id(); 1962 parent::__construct($definition, $store, $loader); 1963 1964 // This will trigger check tracked user. If this gets removed a call to that will need to be added here in its place. 1965 $this->set(self::LASTACCESS, cache::now()); 1966 1967 $this->handle_invalidation_events(); 1968 } 1969 1970 /** 1971 * Sets the session id for the loader. 1972 */ 1973 protected function set_session_id() { 1974 $this->sessionid = preg_replace('#[^a-zA-Z0-9_]#', '_', session_id()); 1975 } 1976 1977 /** 1978 * Returns the prefix used for all keys. 1979 * @return string 1980 */ 1981 protected function get_key_prefix() { 1982 return 'u'.$this->currentuserid.'_'.$this->sessionid; 1983 } 1984 1985 /** 1986 * Parses the key turning it into a string (or array is required) suitable to be passed to the cache store. 1987 * 1988 * This function is called for every operation that uses keys. For this reason we use this function to also check 1989 * that the current user is the same as the user who last used this cache. 1990 * 1991 * On top of that if prepends the string 'sess_' to the start of all keys. The _ ensures things are easily identifiable. 1992 * 1993 * @param string|int $key As passed to get|set|delete etc. 1994 * @return string|array String unless the store supports multi-identifiers in which case an array if returned. 1995 */ 1996 protected function parse_key($key) { 1997 $prefix = $this->get_key_prefix(); 1998 if ($key === self::LASTACCESS) { 1999 return $key.$prefix; 2000 } 2001 return $prefix.'_'.parent::parse_key($key); 2002 } 2003 2004 /** 2005 * Check that this cache instance is tracking the current user. 2006 */ 2007 protected function check_tracked_user() { 2008 if (isset($_SESSION['USER']->id) && $_SESSION['USER']->id !== null) { 2009 // Get the id of the current user. 2010 $new = $_SESSION['USER']->id; 2011 } else { 2012 // No user set up yet. 2013 $new = 0; 2014 } 2015 if ($new !== self::$loadeduserid) { 2016 // The current user doesn't match the tracked userid for this request. 2017 if (!is_null(self::$loadeduserid)) { 2018 // Purge the data we have for the old user. 2019 // This way we don't bloat the session. 2020 $this->purge(); 2021 } 2022 self::$loadeduserid = $new; 2023 $this->currentuserid = $new; 2024 } else if ($new !== $this->currentuserid) { 2025 // The current user matches the loaded user but not the user last used by this cache. 2026 $this->purge_current_user(); 2027 $this->currentuserid = $new; 2028 } 2029 } 2030 2031 /** 2032 * Purges the session cache of all data belonging to the current user. 2033 */ 2034 public function purge_current_user() { 2035 $keys = $this->get_store()->find_by_prefix($this->get_key_prefix()); 2036 $this->get_store()->delete_many($keys); 2037 } 2038 2039 /** 2040 * Retrieves the value for the given key from the cache. 2041 * 2042 * @param string|int $key The key for the data being requested. 2043 * It can be any structure although using a scalar string or int is recommended in the interests of performance. 2044 * In advanced cases an array may be useful such as in situations requiring the multi-key functionality. 2045 * @param int $requiredversion Minimum required version of the data or cache::VERSION_NONE 2046 * @param int $strictness One of IGNORE_MISSING | MUST_EXIST 2047 * @param mixed &$actualversion If specified, will be set to the actual version number retrieved 2048 * @return mixed|false The data from the cache or false if the key did not exist within the cache. 2049 * @throws coding_exception 2050 */ 2051 protected function get_implementation($key, int $requiredversion, int $strictness, &$actualversion = null) { 2052 // Check the tracked user. 2053 $this->check_tracked_user(); 2054 2055 // Use parent code. 2056 return parent::get_implementation($key, $requiredversion, $strictness, $actualversion); 2057 } 2058 2059 /** 2060 * Sends a key => value pair to the cache. 2061 * 2062 * <code> 2063 * // This code will add four entries to the cache, one for each url. 2064 * $cache->set('main', 'http://moodle.org'); 2065 * $cache->set('docs', 'http://docs.moodle.org'); 2066 * $cache->set('tracker', 'http://tracker.moodle.org'); 2067 * $cache->set('qa', 'http://qa.moodle.net'); 2068 * </code> 2069 * 2070 * @param string|int $key The key for the data being requested. 2071 * It can be any structure although using a scalar string or int is recommended in the interests of performance. 2072 * In advanced cases an array may be useful such as in situations requiring the multi-key functionality. 2073 * @param mixed $data The data to set against the key. 2074 * @return bool True on success, false otherwise. 2075 */ 2076 public function set($key, $data) { 2077 $this->check_tracked_user(); 2078 $loader = $this->get_loader(); 2079 if ($loader !== false) { 2080 // We have a loader available set it there as well. 2081 // We have to let the loader do its own parsing of data as it may be unique. 2082 $loader->set($key, $data); 2083 } 2084 if (is_object($data) && $data instanceof cacheable_object) { 2085 $data = new cache_cached_object($data); 2086 } else if (!$this->get_store()->supports_dereferencing_objects() && !is_scalar($data)) { 2087 // If data is an object it will be a reference. 2088 // If data is an array if may contain references. 2089 // We want to break references so that the cache cannot be modified outside of itself. 2090 // Call the function to unreference it (in the best way possible). 2091 $data = $this->unref($data); 2092 } 2093 // We dont' support native TTL here as we consolidate data for sessions. 2094 if ($this->has_a_ttl() && !$this->store_supports_native_ttl()) { 2095 $data = new cache_ttl_wrapper($data, $this->get_definition()->get_ttl()); 2096 } 2097 $success = $this->get_store()->set($this->parse_key($key), $data); 2098 if ($this->perfdebug) { 2099 cache_helper::record_cache_set($this->get_store(), $this->get_definition(), 1, 2100 $this->get_store()->get_last_io_bytes()); 2101 } 2102 return $success; 2103 } 2104 2105 /** 2106 * Delete the given key from the cache. 2107 * 2108 * @param string|int $key The key to delete. 2109 * @param bool $recurse When set to true the key will also be deleted from all stacked cache loaders and their stores. 2110 * This happens by default and ensure that all the caches are consistent. It is NOT recommended to change this. 2111 * @return bool True of success, false otherwise. 2112 */ 2113 public function delete($key, $recurse = true) { 2114 $parsedkey = $this->parse_key($key); 2115 if ($recurse && $this->get_loader() !== false) { 2116 // Delete from the bottom of the stack first. 2117 $this->get_loader()->delete($key, $recurse); 2118 } 2119 return $this->get_store()->delete($parsedkey); 2120 } 2121 2122 /** 2123 * Retrieves an array of values for an array of keys. 2124 * 2125 * Using this function comes with potential performance implications. 2126 * Not all cache stores will support get_many/set_many operations and in order to replicate this functionality will call 2127 * the equivalent singular method for each item provided. 2128 * This should not deter you from using this function as there is a performance benefit in situations where the cache store 2129 * does support it, but you should be aware of this fact. 2130 * 2131 * @param array $keys The keys of the data being requested. 2132 * Each key can be any structure although using a scalar string or int is recommended in the interests of performance. 2133 * In advanced cases an array may be useful such as in situations requiring the multi-key functionality. 2134 * @param int $strictness One of IGNORE_MISSING or MUST_EXIST. 2135 * @return array An array of key value pairs for the items that could be retrieved from the cache. 2136 * If MUST_EXIST was used and not all keys existed within the cache then an exception will be thrown. 2137 * Otherwise any key that did not exist will have a data value of false within the results. 2138 * @throws coding_exception 2139 */ 2140 public function get_many(array $keys, $strictness = IGNORE_MISSING) { 2141 $this->check_tracked_user(); 2142 $parsedkeys = array(); 2143 $keymap = array(); 2144 foreach ($keys as $key) { 2145 $parsedkey = $this->parse_key($key); 2146 $parsedkeys[$key] = $parsedkey; 2147 $keymap[$parsedkey] = $key; 2148 } 2149 $result = $this->get_store()->get_many($parsedkeys); 2150 if ($this->perfdebug) { 2151 $readbytes = $this->get_store()->get_last_io_bytes(); 2152 } 2153 $return = array(); 2154 $missingkeys = array(); 2155 $hasmissingkeys = false; 2156 foreach ($result as $parsedkey => $value) { 2157 $key = $keymap[$parsedkey]; 2158 if ($value instanceof cache_ttl_wrapper) { 2159 /* @var cache_ttl_wrapper $value */ 2160 if ($value->has_expired()) { 2161 $this->delete($keymap[$parsedkey]); 2162 $value = false; 2163 } else { 2164 $value = $value->data; 2165 } 2166 } 2167 if ($value instanceof cache_cached_object) { 2168 /* @var cache_cached_object $value */ 2169 $value = $value->restore_object(); 2170 } else if (!$this->get_store()->supports_dereferencing_objects() && !is_scalar($value)) { 2171 // If data is an object it will be a reference. 2172 // If data is an array if may contain references. 2173 // We want to break references so that the cache cannot be modified outside of itself. 2174 // Call the function to unreference it (in the best way possible). 2175 $value = $this->unref($value); 2176 } 2177 $return[$key] = $value; 2178 if ($value === false) { 2179 $hasmissingkeys = true; 2180 $missingkeys[$parsedkey] = $key; 2181 } 2182 } 2183 if ($hasmissingkeys) { 2184 // We've got missing keys - we've got to check any loaders or data sources. 2185 $loader = $this->get_loader(); 2186 $datasource = $this->get_datasource(); 2187 if ($loader !== false) { 2188 foreach ($loader->get_many($missingkeys) as $key => $value) { 2189 if ($value !== false) { 2190 $return[$key] = $value; 2191 unset($missingkeys[$parsedkeys[$key]]); 2192 } 2193 } 2194 } 2195 $hasmissingkeys = count($missingkeys) > 0; 2196 if ($datasource !== false && $hasmissingkeys) { 2197 // We're still missing keys but we've got a datasource. 2198 foreach ($datasource->load_many_for_cache($missingkeys) as $key => $value) { 2199 if ($value !== false) { 2200 $return[$key] = $value; 2201 unset($missingkeys[$parsedkeys[$key]]); 2202 } 2203 } 2204 $hasmissingkeys = count($missingkeys) > 0; 2205 } 2206 } 2207 if ($hasmissingkeys && $strictness === MUST_EXIST) { 2208 throw new coding_exception('Requested key did not exist in any cache stores and could not be loaded.'); 2209 } 2210 if ($this->perfdebug) { 2211 $hits = 0; 2212 $misses = 0; 2213 foreach ($return as $value) { 2214 if ($value === false) { 2215 $misses++; 2216 } else { 2217 $hits++; 2218 } 2219 } 2220 cache_helper::record_cache_hit($this->get_store(), $this->get_definition(), $hits, $readbytes); 2221 cache_helper::record_cache_miss($this->get_store(), $this->get_definition(), $misses); 2222 } 2223 return $return; 2224 2225 } 2226 2227 /** 2228 * Delete all of the given keys from the cache. 2229 * 2230 * @param array $keys The key to delete. 2231 * @param bool $recurse When set to true the key will also be deleted from all stacked cache loaders and their stores. 2232 * This happens by default and ensure that all the caches are consistent. It is NOT recommended to change this. 2233 * @return int The number of items successfully deleted. 2234 */ 2235 public function delete_many(array $keys, $recurse = true) { 2236 $parsedkeys = array_map(array($this, 'parse_key'), $keys); 2237 if ($recurse && $this->get_loader() !== false) { 2238 // Delete from the bottom of the stack first. 2239 $this->get_loader()->delete_many($keys, $recurse); 2240 } 2241 return $this->get_store()->delete_many($parsedkeys); 2242 } 2243 2244 /** 2245 * Sends several key => value pairs to the cache. 2246 * 2247 * Using this function comes with potential performance implications. 2248 * Not all cache stores will support get_many/set_many operations and in order to replicate this functionality will call 2249 * the equivalent singular method for each item provided. 2250 * This should not deter you from using this function as there is a performance benefit in situations where the cache store 2251 * does support it, but you should be aware of this fact. 2252 * 2253 * <code> 2254 * // This code will add four entries to the cache, one for each url. 2255 * $cache->set_many(array( 2256 * 'main' => 'http://moodle.org', 2257 * 'docs' => 'http://docs.moodle.org', 2258 * 'tracker' => 'http://tracker.moodle.org', 2259 * 'qa' => ''http://qa.moodle.net' 2260 * )); 2261 * </code> 2262 * 2263 * @param array $keyvaluearray An array of key => value pairs to send to the cache. 2264 * @return int The number of items successfully set. It is up to the developer to check this matches the number of items. 2265 * ... if they care that is. 2266 */ 2267 public function set_many(array $keyvaluearray) { 2268 $this->check_tracked_user(); 2269 $loader = $this->get_loader(); 2270 if ($loader !== false) { 2271 // We have a loader available set it there as well. 2272 // We have to let the loader do its own parsing of data as it may be unique. 2273 $loader->set_many($keyvaluearray); 2274 } 2275 $data = array(); 2276 $definitionid = $this->get_definition()->get_ttl(); 2277 $simulatettl = $this->has_a_ttl() && !$this->store_supports_native_ttl(); 2278 foreach ($keyvaluearray as $key => $value) { 2279 if (is_object($value) && $value instanceof cacheable_object) { 2280 $value = new cache_cached_object($value); 2281 } else if (!$this->get_store()->supports_dereferencing_objects() && !is_scalar($value)) { 2282 // If data is an object it will be a reference. 2283 // If data is an array if may contain references. 2284 // We want to break references so that the cache cannot be modified outside of itself. 2285 // Call the function to unreference it (in the best way possible). 2286 $value = $this->unref($value); 2287 } 2288 if ($simulatettl) { 2289 $value = new cache_ttl_wrapper($value, $definitionid); 2290 } 2291 $data[$key] = array( 2292 'key' => $this->parse_key($key), 2293 'value' => $value 2294 ); 2295 } 2296 $successfullyset = $this->get_store()->set_many($data); 2297 if ($this->perfdebug && $successfullyset) { 2298 cache_helper::record_cache_set($this->get_store(), $this->get_definition(), $successfullyset, 2299 $this->get_store()->get_last_io_bytes()); 2300 } 2301 return $successfullyset; 2302 } 2303 2304 /** 2305 * Purges the cache store, and loader if there is one. 2306 * 2307 * @return bool True on success, false otherwise 2308 */ 2309 public function purge() { 2310 $this->get_store()->purge(); 2311 if ($this->get_loader()) { 2312 $this->get_loader()->purge(); 2313 } 2314 return true; 2315 } 2316 2317 /** 2318 * Test is a cache has a key. 2319 * 2320 * The use of the has methods is strongly discouraged. In a high load environment the cache may well change between the 2321 * test and any subsequent action (get, set, delete etc). 2322 * Instead it is recommended to write your code in such a way they it performs the following steps: 2323 * <ol> 2324 * <li>Attempt to retrieve the information.</li> 2325 * <li>Generate the information.</li> 2326 * <li>Attempt to set the information</li> 2327 * </ol> 2328 * 2329 * Its also worth mentioning that not all stores support key tests. 2330 * For stores that don't support key tests this functionality is mimicked by using the equivalent get method. 2331 * Just one more reason you should not use these methods unless you have a very good reason to do so. 2332 * 2333 * @param string|int $key 2334 * @param bool $tryloadifpossible If set to true, the cache doesn't contain the key, and there is another cache loader or 2335 * data source then the code will try load the key value from the next item in the chain. 2336 * @return bool True if the cache has the requested key, false otherwise. 2337 */ 2338 public function has($key, $tryloadifpossible = false) { 2339 $this->check_tracked_user(); 2340 $parsedkey = $this->parse_key($key); 2341 $store = $this->get_store(); 2342 if ($this->has_a_ttl() && !$this->store_supports_native_ttl()) { 2343 // The data has a TTL and the store doesn't support it natively. 2344 // We must fetch the data and expect a ttl wrapper. 2345 $data = $store->get($parsedkey); 2346 $has = ($data instanceof cache_ttl_wrapper && !$data->has_expired()); 2347 } else if (!$this->store_supports_key_awareness()) { 2348 // The store doesn't support key awareness, get the data and check it manually... puke. 2349 // Either no TTL is set of the store supports its handling natively. 2350 $data = $store->get($parsedkey); 2351 $has = ($data !== false); 2352 } else { 2353 // The store supports key awareness, this is easy! 2354 // Either no TTL is set of the store supports its handling natively. 2355 /* @var cache_store|cache_is_key_aware $store */ 2356 $has = $store->has($parsedkey); 2357 } 2358 if (!$has && $tryloadifpossible) { 2359 $result = null; 2360 if ($this->get_loader() !== false) { 2361 $result = $this->get_loader()->get($parsedkey); 2362 } else if ($this->get_datasource() !== null) { 2363 $result = $this->get_datasource()->load_for_cache($key); 2364 } 2365 $has = ($result !== null); 2366 if ($has) { 2367 $this->set($key, $result); 2368 } 2369 } 2370 return $has; 2371 } 2372 2373 /** 2374 * Test is a cache has all of the given keys. 2375 * 2376 * It is strongly recommended to avoid the use of this function if not absolutely required. 2377 * In a high load environment the cache may well change between the test and any subsequent action (get, set, delete etc). 2378 * 2379 * Its also worth mentioning that not all stores support key tests. 2380 * For stores that don't support key tests this functionality is mimicked by using the equivalent get method. 2381 * Just one more reason you should not use these methods unless you have a very good reason to do so. 2382 * 2383 * @param array $keys 2384 * @return bool True if the cache has all of the given keys, false otherwise. 2385 */ 2386 public function has_all(array $keys) { 2387 $this->check_tracked_user(); 2388 if (($this->has_a_ttl() && !$this->store_supports_native_ttl()) || !$this->store_supports_key_awareness()) { 2389 foreach ($keys as $key) { 2390 if (!$this->has($key)) { 2391 return false; 2392 } 2393 } 2394 return true; 2395 } 2396 // The cache must be key aware and if support native ttl if it a ttl is set. 2397 /* @var cache_store|cache_is_key_aware $store */ 2398 $store = $this->get_store(); 2399 return $store->has_all(array_map(array($this, 'parse_key'), $keys)); 2400 } 2401 2402 /** 2403 * Test if a cache has at least one of the given keys. 2404 * 2405 * It is strongly recommended to avoid the use of this function if not absolutely required. 2406 * In a high load environment the cache may well change between the test and any subsequent action (get, set, delete etc). 2407 * 2408 * Its also worth mentioning that not all stores support key tests. 2409 * For stores that don't support key tests this functionality is mimicked by using the equivalent get method. 2410 * Just one more reason you should not use these methods unless you have a very good reason to do so. 2411 * 2412 * @param array $keys 2413 * @return bool True if the cache has at least one of the given keys 2414 */ 2415 public function has_any(array $keys) { 2416 if (($this->has_a_ttl() && !$this->store_supports_native_ttl()) || !$this->store_supports_key_awareness()) { 2417 foreach ($keys as $key) { 2418 if ($this->has($key)) { 2419 return true; 2420 } 2421 } 2422 return false; 2423 } 2424 /* @var cache_store|cache_is_key_aware $store */ 2425 $store = $this->get_store(); 2426 return $store->has_any(array_map(array($this, 'parse_key'), $keys)); 2427 } 2428 2429 /** 2430 * The session loader never uses static acceleration. 2431 * Instead it stores things in the static $session variable. Shared between all session loaders. 2432 * 2433 * @return bool 2434 */ 2435 protected function use_static_acceleration() { 2436 return false; 2437 } 2438 } 2439 2440 /** 2441 * An request cache. 2442 * 2443 * This class is used for request caches returned by the cache::make methods. 2444 * 2445 * This cache class should never be interacted with directly. Instead you should always use the cache::make methods. 2446 * It is technically possible to call those methods through this class however there is no guarantee that you will get an 2447 * instance of this class back again. 2448 * 2449 * @internal don't use me directly. 2450 * 2451 * @package core 2452 * @category cache 2453 * @copyright 2012 Sam Hemelryk 2454 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later 2455 */ 2456 class cache_request extends cache { 2457 // This comment appeases code pre-checker ;) ! 2458 }
title
Description
Body
title
Description
Body
title
Description
Body
title
Body
