Proyectos de Subversion Moodle

<?php

// This file is part of Moodle - http://moodle.org/

//

// Moodle is free software: you can redistribute it and/or modify

// it under the terms of the GNU General Public License as published by

// the Free Software Foundation, either version 3 of the License, or

// (at your option) any later version.

//

// Moodle is distributed in the hope that it will be useful,

// but WITHOUT ANY WARRANTY; without even the implied warranty of

// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the

// GNU General Public License for more details.

//

// You should have received a copy of the GNU General Public License

// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.

namespace core_cache;

use core\exception\coding_exception;

use core\exception\moodle_exception;

/**

 * An application cache.

 *

 * This class is used for application caches returned by the cache::make methods.

 * On top of the standard functionality it also allows locking to be required and or manually operated.

 *

 * This cache class should never be interacted with directly. Instead you should always use the cache::make methods.

 * It is technically possible to call those methods through this class however there is no guarantee that you will get an

 * instance of this class back again.

 *

 * @internal don't use me directly.

 *

 * @package    core_cache

 * @category   cache

 * @copyright  2012 Sam Hemelryk

 * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later

 */

class application_cache extends cache implements loader_with_locking_interface {

    /**

     * Lock identifier.

     * This is used to ensure the lock belongs to the cache instance + definition + user.

     * @var string

     */

    protected $lockidentifier;

    /**

     * Gets set to true if the cache's primary store natively supports locking.

     * If it does then we use that, otherwise we need to instantiate a second store to use for locking.

     * @var store

     */

    protected $nativelocking = null;

    /**

     * Gets set to true if the cache is going to be using locking.

     * This isn't a requirement, it doesn't need to use locking (most won't) and this bool is used to quickly check things.

     * If required then locking will be forced for the get|set|delete operation.

     * @var bool

     */

    protected $requirelocking = false;

    /**

     * Gets set to true if the cache writes (set|delete) must have a manual lock created first

     * @var bool

     */

    protected $requirelockingbeforewrite = false;

    /**

     * Gets set to a store to use for locking if the caches primary store doesn't support locking natively.

     * @var lockable_cache_interface

     */

    protected $cachelockinstance;

    /**

     * Store a list of locks acquired by this process.

     * @var array

     */

    protected $locks;

    /**

     * Overrides the cache construct method.

     *

     * You should not call this method from your code, instead you should use the cache::make methods.

     *

     * @param definition $definition

     * @param store $store

     * @param loader_interface|data_source_interface $loader

     */

    public function __construct(definition $definition, store $store, $loader = null) {

        parent::__construct($definition, $store, $loader);

        $this->nativelocking = $this->store_supports_native_locking();

        if ($definition->require_locking()) {

            $this->requirelocking = true;

            $this->requirelockingbeforewrite = $definition->require_locking_before_write();

        }

        $this->handle_invalidation_events();

    }

    /**

     * Returns the identifier to use

     *

     * @staticvar int $instances Counts the number of instances. Used as part of the lock identifier.

     * @return string

     */

    public function get_identifier() {

        static $instances = 0;

        if ($this->lockidentifier === null) {

            $this->lockidentifier = md5(

                $this->get_definition()->generate_definition_hash() .

                sesskey() .

                $instances++ .

                application_cache::class,

            );

        }

        return $this->lockidentifier;

    }

    /**

     * Fixes the instance up after a clone.

     */

    public function __clone() {

        // Force a new idenfitier.

        $this->lockidentifier = null;

    }

    /**

     * Acquires a lock on the given key.

     *

     * This is done automatically if the definition requires it.

     * It is recommended to use a definition if you want to have locking although it is possible to do locking without having

     * it required by the definition.

     * The problem with such an approach is that you cannot ensure that code will consistently use locking. You will need to

     * rely on the integrators review skills.

     *

     * @param string|int $key The key as given to get|set|delete

     * @return bool Always returns true

     * @throws moodle_exception If the lock cannot be obtained

     */

    public function acquire_lock($key) {

        $releaseparent = false;

        try {

            if ($this->get_loader() !== false) {

                $this->get_loader()->acquire_lock($key);

                // We need to release this lock later if the lock is not successful.

                $releaseparent = true;

            }

            $hashedkey = helper::hash_key($key, $this->get_definition());

            $before = microtime(true);

            if ($this->nativelocking) {

                $lock = $this->get_store()->acquire_lock($hashedkey, $this->get_identifier());

            } else {

                $this->ensure_cachelock_available();

                $lock = $this->cachelockinstance->lock($hashedkey, $this->get_identifier());

            }

            $after = microtime(true);

            if ($lock) {

                $this->locks[$hashedkey] = $lock;

                if (MDL_PERF || $this->perfdebug) {

                    \core\lock\timing_wrapper_lock_factory::record_lock_data(

                        $after,

                        $before,

                        $this->get_definition()->get_id(),

                        $hashedkey,

                        $lock,

                        $this->get_identifier() . $hashedkey

                    );

                }

                $releaseparent = false;

                return true;

            } else {

                throw new moodle_exception(

                    'ex_unabletolock',

                    'cache',

                    '',

                    null,

                    'store: ' . get_class($this->get_store()) . ', lock: ' . $hashedkey

                );

            }

        } finally {

            // Release the parent lock if we acquired it, then threw an exception.

            if ($releaseparent) {

                $this->get_loader()->release_lock($key);

            }

        }

    }

    /**

     * Checks if this cache has a lock on the given key.

     *

     * @param string|int $key The key as given to get|set|delete

     * @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

     *      someone else has the lock.

     */

    public function check_lock_state($key) {

        $key = helper::hash_key($key, $this->get_definition());

        if (!empty($this->locks[$key])) {

            return true; // Shortcut to save having to make a call to the cache store if the lock is held by this process.

        }

        if ($this->nativelocking) {

            return $this->get_store()->check_lock_state($key, $this->get_identifier());

        } else {

            $this->ensure_cachelock_available();

            return $this->cachelockinstance->check_state($key, $this->get_identifier());

        }

    }

    /**

     * Releases the lock this cache has on the given key

     *

     * @param string|int $key

     * @return bool True if the operation succeeded, false otherwise.

     */

    public function release_lock($key) {

        $loaderkey = $key;

        $key = helper::hash_key($key, $this->get_definition());

        if ($this->nativelocking) {

            $released = $this->get_store()->release_lock($key, $this->get_identifier());

        } else {

            $this->ensure_cachelock_available();

            $released = $this->cachelockinstance->unlock($key, $this->get_identifier());

        }

        if ($released && array_key_exists($key, $this->locks)) {

            unset($this->locks[$key]);

            if (MDL_PERF || $this->perfdebug) {

                \core\lock\timing_wrapper_lock_factory::record_lock_released_data($this->get_identifier() . $key);

            }

        }

        if ($this->get_loader() !== false) {

            $this->get_loader()->release_lock($loaderkey);

        }

        return $released;

    }

    /**

     * Ensure that the dedicated lock store is ready to go.

     *

     * This should only happen if the cache store doesn't natively support it.

     */

    protected function ensure_cachelock_available() {

        if ($this->cachelockinstance === null) {

            $this->cachelockinstance = helper::get_cachelock_for_store($this->get_store());

        }

    }

    /**

     * Sends a key => value pair to the cache.

     *

     * <code>

     * // This code will add four entries to the cache, one for each url.

     * $cache->set('main', 'http://moodle.org');

     * $cache->set('docs', 'http://docs.moodle.org');

     * $cache->set('tracker', 'http://tracker.moodle.org');

     * $cache->set('qa', 'http://qa.moodle.net');

     * </code>

     *

     * @param string|int $key The key for the data being requested.

     * @param int $version Version number

     * @param mixed $data The data to set against the key.

     * @param bool $setparents If true, sets all parent loaders, otherwise only this one

     * @return bool True on success, false otherwise.

     * @throws coding_exception If a required lock has not beeen acquired

     */

    protected function set_implementation($key, int $version, $data, bool $setparents = true): bool {

        if ($this->requirelockingbeforewrite && !$this->check_lock_state($key)) {

            throw new coding_exception('Attempted to set cache key "' . $key . '" without a lock. '

                . 'Locking before writes is required for ' . $this->get_definition()->get_id());

        }

        return parent::set_implementation($key, $version, $data, $setparents);

    }

    /**

     * Sends several key => value pairs to the cache.

     *

     * Using this function comes with potential performance implications.

     * Not all cache stores will support get_many/set_many operations and in order to replicate this functionality will call

     * the equivalent singular method for each item provided.

     * This should not deter you from using this function as there is a performance benefit in situations where the cache store

     * does support it, but you should be aware of this fact.

     *

     * <code>

     * // This code will add four entries to the cache, one for each url.

     * $cache->set_many(array(

     *     'main' => 'http://moodle.org',

     *     'docs' => 'http://docs.moodle.org',

     *     'tracker' => 'http://tracker.moodle.org',

     *     'qa' => ''http://qa.moodle.net'

     * ));

     * </code>

     *

     * @param array $keyvaluearray An array of key => value pairs to send to the cache.

     * @return int The number of items successfully set. It is up to the developer to check this matches the number of items.

     *      ... if they care that is.

     * @throws coding_exception If a required lock has not beeen acquired

     */

    public function set_many(array $keyvaluearray) {

        if ($this->requirelockingbeforewrite) {

            foreach ($keyvaluearray as $key => $value) {

                if (!$this->check_lock_state($key)) {

                    throw new coding_exception('Attempted to set cache key "' . $key . '" without a lock. '

                            . 'Locking before writes is required for ' . $this->get_definition()->get_id());

                }

            }

        }

        return parent::set_many($keyvaluearray);

    }

    /**

     * Delete the given key from the cache.

     *

     * @param string|int $key The key to delete.

     * @param bool $recurse When set to true the key will also be deleted from all stacked cache loaders and their stores.

     *     This happens by default and ensure that all the caches are consistent. It is NOT recommended to change this.

     * @return bool True of success, false otherwise.

     * @throws coding_exception If a required lock has not beeen acquired

     */

    public function delete($key, $recurse = true) {

        if ($this->requirelockingbeforewrite && !$this->check_lock_state($key)) {

            throw new coding_exception('Attempted to delete cache key "' . $key . '" without a lock. '

                    . 'Locking before writes is required for ' . $this->get_definition()->get_id());

        }

        return parent::delete($key, $recurse);

    }

    /**

     * Delete all of the given keys from the cache.

     *

     * @param array $keys The key to delete.

     * @param bool $recurse When set to true the key will also be deleted from all stacked cache loaders and their stores.

     *     This happens by default and ensure that all the caches are consistent. It is NOT recommended to change this.

     * @return int The number of items successfully deleted.

     * @throws coding_exception If a required lock has not beeen acquired

     */

    public function delete_many(array $keys, $recurse = true) {

        if ($this->requirelockingbeforewrite) {

            foreach ($keys as $key) {

                if (!$this->check_lock_state($key)) {

                    throw new coding_exception('Attempted to delete cache key "' . $key . '" without a lock. '

                            . 'Locking before writes is required for ' . $this->get_definition()->get_id());

                }

            }

        }

        return parent::delete_many($keys, $recurse);

    }

}

// Alias this class to the old name.

// This file will be autoloaded by the legacyclasses autoload system.

// In future all uses of this class will be corrected and the legacy references will be removed.

class_alias(application_cache::class, \cache_application::class);